Gestion des erreurs de l'API Microsoft Graph : Conseils et astuces

Alexandre Cipriani

26 octobre 2024

Gestion des erreurs de l'API Microsoft Graph : Conseils et astuces

Alexandre Cipriani

26 octobre 2024

Difficultés avec Microsoft Graph API qui brisent l'automatisation de vos équipes ? Voici exactement ce que vous devez savoir :

Les 3 erreurs les plus courantes auxquelles vous serez confronté :

401 erreurs : Jetons d'accès manquants ou expirés
Erreurs 403 : Autorisations ou droits d'accès incorrects
Erreurs 503/504 : Délais d'attente et problèmes du serveur

Voici ce que vous devez vérifier lorsque des erreurs apparaissent :

Type d'erreur	Correction rapide	La prévention
Authentification (401)	Obtenir un nouveau jeton d'accès	Vérifier la validité du jeton (expire dans 59 minutes)
Permissions (403)	Ajouter les autorisations manquantes	Utilisation `Commande Find-MgGraphCommand` pour vérifier les autorisations nécessaires
Limites de taux (429)	Attendre et réessayer	Espacer les demandes, vérifier les en-têtes
Problèmes de serveur (5xx)	Réessai avec backoff	Contrôler l'état des services

Étapes incontournables pour chaque appel à l'API :

Ajouter le suivi des erreurs avec les identifiants des requêtes
Inclure une logique de réessai pour les erreurs 429 et 5xx
Vérifier les limites de débit dans les en-têtes de réponse
Mettre les réponses en cache lorsque c'est possible

Conseil de pro : Utilisation Explorateur de graphiques (aka.ms/ge) pour tester les appels à l'API avant d'écrire du code. Il indique exactement les autorisations dont vous avez besoin et vous permet de voir les réponses réelles.

Vous voulez un traitement automatique des erreurs ? Des outils comme nBold gère tout cela en arrière-plan pour l'automatisation des équipes.

Ce guide couvre tous les aspects, des codes d'erreur de base aux stratégies de traitement avancées, avec des exemples de code réels et des corrections pour les problèmes spécifiques aux équipes.

Liste de contrôle pour la gestion des erreurs

Voici comment corriger les erreurs de l'API Microsoft Graph :

Vérifier l'accès et les autorisations

Type d'erreur	Ce qu'il faut vérifier	Comment réparer
401 Non autorisé	Statut du jeton d'accès	Vérifier si le jeton existe et est valide (expire dans 59 minutes)
403 Interdit	Champs d'application des autorisations	Obtenir les autorisations manquantes à partir du centre d'administration Azure AD
Absence de consentement	Approbation administrative	Demander à l'administrateur d'approuver les autorisations de l'application

Les utilisateurs de PowerShell peuvent voir leurs permissions actuelles avec :

(Get-MgContext).Scopes

Correction des codes d'état

Code de statut	Ce que cela signifie	Que faire ?
400	Mauvais format de demande	Fixez le format et les paramètres de votre demande
401	Jeton erroné/manquant	Obtenir un nouveau jeton d'accès
403	Pas assez d'autorisations	Ajoutez les autorisations dont vous avez besoin
429	Limite du taux d'atteinte	Reculer et réessayer plus tard
500	Problèmes de serveur	Attendre et réessayer
503	Le service ne fonctionne pas	Vérifier si le service est en place

Faire de meilleures demandes d'API

Vos appels à l'API ont besoin :

Code pour réessayer les erreurs 429 et 5xx
Suivi des erreurs pour chaque appel
Contrôles des limites de débit dans les en-têtes de réponse
Mise en cache des réponses là où c'est utile

Comprendre les messages d'erreur

Les réponses d'erreur sont accompagnées de ce JSON :

Champ d'application	Spectacles	Comment l'utiliser
code	Type d'erreur	Comparer avec des erreurs connues
message	Ce qui n'a pas fonctionné	Sauvegarde pour le débogage
erreur interne	Détails supplémentaires	Trouver les problèmes à la racine

Travailler avec des limites de taux

Limites de l'API graphique :

Type d'appel	Maximum autorisé	Que faire ?
Appels standard	Dépend du point d'accès	Espacez vos demandes
Appels par lots	20 par lot	Utiliser des lots plus petits
Mises à jour de l'abonnement	4 en même temps	Mettre les appels supplémentaires dans une file d'attente

Pour /abonnements, Si vous obtenez une erreur 401, réessayez la même demande - de nombreux utilisateurs affirment que cette méthode fonctionne.

Rechercher et corriger les erreurs

Mise en place de journaux d'erreurs

Voici comment configurer les journaux d'activité de Microsoft Graph pour suivre les problèmes liés à l'API :

Composant	Exigences	Objectif
Licence	Microsoft Entra ID P1/P2	Accès à l'enregistrement des activités
Rôle	Administrateur de sécurité ou administrateur global	Configurer les paramètres de diagnostic
Stockage	Espace de travail Log Analytics	Stocker et analyser les journaux
Permissions	AuditLog.Read.All ou Directory.Read.All	Accéder aux données du journal

Voici ce dont vous aurez besoin pour l'entreposage en fonction de la taille de votre locataire :

Utilisateurs	Stockage mensuel (GiB)	Événements mensuels
1,000	14	62,000
100,000	1,000	4,800,000

Vérifier les détails de la demande

Voyons ce qui importe lorsque vous rencontrez une erreur de l'API graphique :

Composant	Ce qu'il faut vérifier	Pourquoi c'est important
En-têtes	Jeton d'autorisation	Évite les erreurs 401/403
Temps de réponse	Retards de livraison	Les événements peuvent durer jusqu'à 2 heures
Champs d'erreur	code, message, détails	Indique la cause exacte de l'erreur
Type d'activité	Type de requête HTTP	Permet de suivre des questions spécifiques

Voici à quoi ressemble une bonne capture d'erreur :

{
    "error" : {
        "code" : "Request_ResourceNotFound",
        "message" : "Resource ID not found",
        "details" : [
            {
                "code" : "ObjectNotFound",
                "target" : "id",
                "message" : "Specified ID invalid"
            }
        ]
    }
}

Conseil rapide: Enveloppez vos appels à l'API graphique dans des blocs try/catch. Vous obtiendrez de meilleurs messages d'erreur qui vous indiqueront des problèmes spécifiques, comme des identifiants d'objets erronés ou des données manquantes dans vos requêtes.

Encore une chose : n'essayez pas d'extraire trop de données à la fois. L'API graphique fonctionne mieux avec des requêtes plus petites et plus ciblées.

Corrections d'erreurs spécifiques aux équipes

Voici ce qu'il faut savoir pour corriger les erreurs de l'API Teams :

Erreurs courantes de l'API

Les erreurs d'équipes les plus fréquentes que vous rencontrerez :

Code d'erreur	Ce que cela signifie	Comment y remédier
53003	L'identification bloque l'accès aux ressources	Examinez l'enregistrement des appareils et vérifiez si la plateforme fonctionne avec Teams.
403 Interdit	Le modèle de backend échoue	Vérifier les autorisations des applications et les droits des propriétaires d'équipe
503/504	Service en panne/Période d'inactivité de la passerelle	Espacez vos demandes et surveillez l'en-tête "Retry-After".

Problèmes de canaux

Ils apparaissent lorsque l'on travaille avec des canaux et des membres :

Problème	Ce que vous verrez	Que faire ?
Accès externe	"Impossible d'ajouter des personnes externes au canal"	Activer l'accès des invités dans les groupes M365
Locataires multiples	"Je ne peux pas partager le canal avec cette organisation."	Examinez votre configuration Microsoft Entra cross-tenant
Création d'une équipe	"Le propriétaire de l'équipe doit être fourni"	Inscrire les coordonnées du propriétaire dans le contexte de l'application

Configuration du modèle

Votre modèle risque de ne pas fonctionner si ces paramètres ne sont pas corrects :

Partie	Ce qu'il faut mettre en place	Où les trouver
Accès des invités	"Permettre aux propriétaires de groupes d'ajouter des personnes externes"	Centre d'administration M365
Contenu du groupe	"Permettre aux membres du groupe d'invités d'accéder au contenu"	Centre d'administration M365
Politique de la chaîne	Invitations d'utilisateurs externes = "On"	Centre d'administration des équipes

Lorsque le clonage de votre modèle échoue, vous pouvez voir ceci :

{
    "error" : {
        "code" : "ResourceNotFound",
        "message" : "Invalid version : teams",
        "innerError" : {
            "request-id" : "24ee407c-7baa-4e2c-a88a-77af52424150",
            "date" : "2019-12-11T18:04:04"
        }
    }
}

Réparation rapide: Ajout d'informations sur le propriétaire de l'équipe lors de la création d'une équipe :

{
    "template@odata.bind" : "https://graph.microsoft.com/v1.0/teamsTemplates('standard')",
    "displayName" : "Équipe d'échantillonnage",
    "owners@odata.bind" : ["https://graph.microsoft.com/v1.0/users('userId')"]
}

Conseil de pro: Définissez des propriétaires par défaut dans vos modèles - cela permet d'éviter l'erreur "le propriétaire de l'équipe doit être indiqué" avant qu'elle ne se produise.

Une meilleure gestion des erreurs

Voici ce qu'il faut savoir pour prévenir et corriger les erreurs de l'API graphique :

Arrêter les erreurs avant qu'elles ne se produisent

Vous voulez éviter les erreurs d'API ? Vérifiez les points suivants avant d'effectuer des appels :

Type de contrôle	Ce qu'il faut vérifier	Pourquoi c'est important
Permissions	Autorisations pour les applications dans Azure AD	Plus d'erreurs 403
Fuseaux horaires	Dates d'échéance des tâches et paramètres temporels	Synchronisation des horaires
Limites de taux	Utilisation actuelle de l'API par rapport aux limites	Arrêt de l'étranglement 429
Jetons d'accès	Expiration du jeton (limite de 59 minutes)	L'authentification continue de fonctionner

Voici ce qui fonctionne :

Passer à une authentification basée sur un certificat (ignorer les secrets d'application)
Ajouter un client-request-id avec GUID
Mise en place de journaux d'erreurs avec les identifiants des requêtes
Observez-les Réessayer après en-têtes

Corriger les erreurs lorsqu'elles apparaissent

Voici votre manuel de correction des erreurs :

Code d'erreur	Ce que cela signifie	Que faire ?
429	Trop de demandes	Attendre (vérifier `Réessayer après` en-tête)
503	Service Down	Réessayer avec une nouvelle connexion HTTP
504	Délai d'attente de la passerelle	Déposer des objets lourds tels que `$search`
403	Interdit	Double vérification des autorisations Azure

Voici un peu de code qui gère les tentatives :

if (response.StatusCode == 429 || response.StatusCode == 503)
{
    var retryAfter = response.Headers.RetryAfter ;
    await Task.Delay(retryAfter.Delta ? ? TimeSpan.FromSeconds(10)) ;
    // Retenter la requête
}

Conseil rapideLes modèles d'équipes : nBold gère la plupart de ces erreurs automatiquement lorsque vous créez des modèles d'équipes.

Gérer les erreurs comme un pro :

Sauvegarder les request-id et Date en-têtes
Utiliser la bibliothèque d'utilitaires Graph de Microsoft
Rédiger des messages d'erreur clairs
Gardez un œil sur les statistiques de votre API

Outils de gestion des erreurs

Voici comment détecter et corriger les erreurs de l'API graphique :

Utilisation Explorateur de graphiques

Graph Explorer (aka.ms/ge) vous permet de tester les appels d'API avant d'écrire le moindre code.

Fonctionnalité	Ce qu'il fait
Demande de test	Essayez les appels GET, POST, PATCH, DELETE
Génération de codes	Obtenir des exemples de code en C#, Java, JavaScript, Go, PowerShell
Contrôle de l'autorisation	Déterminer les autorisations nécessaires pour chaque appel d'API
Analyse des réponses	Voir les réponses JSON et les messages d'erreur
Vue des en-têtes	Examiner les en-têtes des requêtes/réponses pour déboguer les problèmes

Vous voulez voir les appels à l'API graphique en action ? Ouvrez la console de votre navigateur (F12) lorsque vous utilisez les services M365.

Outils de suivi des erreurs

Voici les meilleurs outils pour repérer les problèmes :

Outil	Principaux points d'attention	Prix de départ
Sentinelle	Traces de piles, détails des erreurs	$26/mois
Raygun	Diagnostic approfondi	Événements $4/10k
Testé avec succès	Contrôles API, chaînes de test	$49/mois
Datadog	Surveillance à grande échelle	$5/mois
APIToolkit	Surveillance de base	Gratuit jusqu'à 20 000 demandes

Lorsque vous choisissez un outil de surveillance, recherchez les éléments suivants :

Des tableaux de bord clairs sur les erreurs
Accès à la documentation de l'API
Suivi des problèmes dans les commits
Données contextuelles
Connexions prêtes à l'emploi
Options d'auto-hébergement

Voici comment procéder :

Ajouter des en-têtes client-request-id aux appels de suivi
Conserver les en-têtes request-id et date des réponses
Définir des alertes d'erreur
Surveillez votre utilisation de l'API par rapport aux limites de taux

Vous voulez détecter rapidement les problèmes ? Des outils comme Testfully et Datadog peuvent vérifier votre API toutes les 30 secondes, bien avant que vos utilisateurs ne remarquent quoi que ce soit d'anormal.

Résumé

Voici comment gérer les erreurs de l'API Microsoft Graph :

Type d'erreur	Causes communes	Correction rapide
401 Non autorisé	Jeton manquant/expiré	Vérifier la validité du jeton, le rafraîchir si nécessaire
403 Interdit	Permissions insuffisantes	Examiner les autorisations requises avec `Commande Find-MgGraphCommand`
404 Non trouvé	Point final/ressource non valide	Double vérification de l'URL du point de terminaison de l'API
429 Trop de demandes	Limite de taux dépassée	Ajouter une logique de réessai avec backoff
500 Erreur de serveur	Problèmes de backend	Attendre et réessayer, vérifier l'état du service

Voici ce dont vous avez besoin pour améliorer le suivi des erreurs :

Ajouter client-request-id à chaque appel à l'API
Économiser request-id et Date les en-têtes des réponses
Tester les appels API dans Graph Explorer (aka.ms/ge)
Exécuter Mise à jour du module Microsoft.Graph pour maintenir le SDK à jour

Pour les scripts d'automatisation Teams, procédez comme suit :

Action	Comment faire
Enregistrement des erreurs	Set (jeu de mots) `$ErrorActionPreference = "Stop" (Arrêt)"`
Mode débogage	Utilisation `-Debug` paramètre
Capture d'erreur	Appliquer `-Variable d'erreur`
Contrôle de l'autorisation	Exécuter `Commande Find-MgGraphCommand`
Suivi du statut	Contrôler les codes de réponse et les limites de taux

Des outils comme nBold aident à gérer l'automatisation des modèles Teams avec une gestion intégrée des erreurs. L'application prend en charge les autorisations et les limites de débit lorsque vous travaillez avec des modèles Teams.

Connaître les codes d'état HTTP :

Gamme de codes	Ce que cela signifie
2xx (200-299)	Succès
4xx (400-499)	Erreurs du client
5xx (500-599)	Erreurs de serveur

Vos réponses aux erreurs doivent inclure

Code d'erreur
Détails du message
Étapes de dépannage
Coordonnées de l'assistance

A propos de nBold pour les équipes

nBold fait Automatisation de Microsoft Teams fonctionne mieux en gérant automatiquement les erreurs de l'API graphique. Plus besoin de s'occuper de problèmes techniques - cela fonctionne tout simplement.

Voici ce que vous obtiendrez :

Fonctionnalité	Ce qu'il fait
Constructeur de modèles	Arrêter les erreurs d'autorisation avant qu'elles ne se produisent
Création d'une équipe	Vous permet de rester dans les limites de l'API
Gouvernance informatique	S'assure que les appels à l'API fonctionnent d'abord
Intégration de tiers	Corrige automatiquement les problèmes de connexion

L'application s'occupe des aspects techniques en arrière-plan :

Vérifie si vous pouvez accéder aux équipes avant de faire quoi que ce soit
Vérifie que vous disposez des autorisations nécessaires
Évite d'atteindre les limites de l'API
Conserve la trace des erreurs afin que vous puissiez les corriger

Plans et tarifs

Choisissez le plan qui correspond à vos besoins :

Caractéristiques	Pro ($3/utilisateur/mois)	CRM ($15/utilisateur/mois)
Enregistrement des erreurs	✓	✓
Gestion des tarifs API	✓	✓
Contrôle des autorisations	✓	✓
Gestion des erreurs d'intégration	-	✓

Vous voulez économiser de l'argent ? Achetez Pro pour plus de 100 utilisateurs ou CRM pour plus de 50 utilisateurs.

Commencer à utiliser nBold

Il faut 30 secondes pour démarrer :

Équipes ouvertes
Cliquer sur les applications
Tapez "nBold"
Cliquez sur Installer
Suivez les étapes de configuration

C'est tout. nBold s'occupe des tâches complexes pendant que vous vous concentrez sur votre travail.

FAQ

Comment gérez-vous les erreurs de l'API ?

Voici comment gérer les erreurs de l'API Microsoft Graph :

Type d'erreur	Comment y faire face	Exemple de réponse
401 Non autorisé	Vérifier la validité du jeton d'accès	`{"error" : {"code" : "non autorisé", "message" : "Le jeton d'accès est expiré"}}`
403 Interdit	Vérifier les autorisations	`{"error" : {"code" : "forbidden", "message" : "Insufficient permissions to access resource"}}`
429 Trop de demandes	Ajouter une logique de réessai	`{"error" : {"code" : "tooManyRequests", "message" : "Request limit exceeded"}}`

Vous voulez de meilleurs résultats ? Faites ce qui suit :

Enregistrez vos erreurs: Mettre en place un système de suivi des dysfonctionnements
Test dans l'explorateur de graphes: Assurez-vous que vos appels à l'API fonctionnent avant de les mettre en ligne
Normaliser les erreurs: Veillez à ce que le format des messages d'erreur soit cohérent
Ajouter des tentatives: Intégrer une logique pour gérer les défaillances temporaires

Voici à quoi ressemble une réponse d'erreur correcte :

{
  "error" : {
    "code" : "badRequest",
    "message" : "Impossible de traiter la demande en raison d'un format incorrect",
    "target" : "ressource"
  }
}

Lorsque vous obtenez une erreur :

Regardez le code d'état HTTP
Vérifier le message d'erreur
Recherche du code d'erreur
Réparer ce qui ne va pas
Testez votre solution

Conseil de pro: Microsoft Graph plafonne à 2 000 requêtes par seconde. Décomposez les gros lots de requêtes pour ne pas dépasser cette limite.

Voici ce que signifient les différents codes d'état :

Code de statut	Ce que cela signifie	Que faire ?
400	Mauvais format de demande	Corriger la syntaxe des demandes
404	Ressource non trouvée	Vérifier l'ID de la ressource
500	Erreur de serveur	Attendre et réessayer
503	Service en panne	Réessayer plus tard

Postes connexes

Passez moins de temps à gérer des équipes et plus de temps à collaborer

Laissez-nous nous occuper des détails

Prendre contact

Microsoft présente GPT-5.2 dans Microsoft 365 Copilot