Utiliser l’API Microsoft Graph

Article
11/07/2024

Microsoft Graph est une API web RESTful qui vous permet d’accéder aux ressources de service Cloud Microsoft. Après avoir enregistré votre application et obtenu des jetons d’authentification pour un utilisateur ou un service, vous pouvez effectuer des requêtes dans l’API Microsoft Graph.

Importante

La façon dont les stratégies d’accès conditionnel s’appliquent à Microsoft Graph change. Les applications doivent être mises à jour pour gérer les scénarios dans lesquels des stratégies d’accès conditionnel sont configurées. Pour plus d’informations et d’aide, consultez Conseils pour les développeurs pour Microsoft Entra l’accès conditionnel.

Espace de noms OData

L’API Microsoft Graph définit la plupart de ses ressources, méthodes et énumérations dans l’espace de noms OData, microsoft.graph, dans les métadonnées de Microsoft Graph. Un petit nombre d’ensembles d’API sont définis dans leurs sous-espaces de noms, tels que l’ API d’enregistrement d’appels qui définit des ressources commecallRecord dans microsoft.graph.callRecords.

Sauf indication contraire dans la rubrique correspondante, les types, les méthodes et les énumérations font partie de l’espace de noms microsoft.graph.

Appeler une méthode API REST

Pour lire ou écrire à une ressource comme un utilisateur ou un message électronique, vous créez une requête qui se présente comme suit :

{HTTP method} https://graph.microsoft.com/{version}/{resource}?{query-parameters}

Les composants d’une requête incluent :

{HTTP method} - Méthode HTTP utilisée dans la requête à Microsoft Graph.
{version} - Version de l’API Microsoft Graph que votre application utilise.
{resource} - Ressource dans Microsoft Graph que vous référencez.
{query-parameters} - Options de requête OData facultatives ou paramètres de méthode Rest qui personnalisent la réponse.
{headers} : en-têtes de requête qui personnalisent la demande. Peut être facultatif ou obligatoire en fonction de l’API.

Une fois que vous avez effectué une requête, la réponse renvoyée inclut ce qui suit :

Code d’état - Code d’état HTTP qui indique le succès ou l’échec. Pour plus d’informations sur les codes d’erreur HTTP, voir Erreurs.
Message de réponse : données que vous avez demandées ou résultat de l’opération. Le message de réponse peut être vide pour certaines opérations.
@odata.nextLink - Si votre requête renvoie un grand nombre de données, vous devez parcourir les pages en choisissant @odata.nextLink. Pour plus d’informations, reportez-vous à Pagination.
En-têtes de réponse : informations supplémentaires sur la réponse, telles que le type de contenu retourné et l’ID de requête que vous pouvez utiliser pour mettre en corrélation la réponse à la requête.

Méthodes HTTP

Microsoft Graph utilise la méthode HTTP sur votre requête pour déterminer ce que fait votre requête. En fonction de la ressource, l’API peut prendre en charge des opérations, notamment des actions, des fonctions ou des opérations CRUD décrites ci-dessous.

Méthode	Description
GET	Lire les données à partir d’une ressource.
POST	Créer une nouvelle ressource ou effectuer une action.
PATCH	Mettez à jour une ressource avec de nouvelles valeurs ou upsertez une ressource (créez si la ressource n’existe pas, mettez à jour dans le cas contraire).
PUT	Remplacer une ressource par une autre.
DELETE	Supprimer une ressource.

Pour les méthodes CRUDGET etDELETE, le corps de la requête n’est pas requis.
Les méthodes POST, PATCH et PUT nécessitent un corps de requête, généralement spécifié au format JSON, qui contient des informations supplémentaires, telles que les valeurs des propriétés de la ressource.

Importante

Les demandes d’écriture dans microsoft API Graph ont une taille limite de 4 Mo.

Dans certains cas, la limite réelle de taille des demandes d’écriture est inférieure à 4 Mo. Par exemple, l’attachement d’un fichier à un événement utilisateur par POST /me/events/{id}/attachments a une limite de taille de requête de 3 Mo, car un fichier d’environ 3,5 Mo peut dépasser 4 Mo lorsqu’il est encodé en base64.

Les demandes dépassant la limite de taille échouent avec le code status HTTP 413 et le message d’erreur « Entité de demande trop grande » ou « Charge utile trop grande ».

Version

Microsoft Graph prend actuellement en charge les deux versions : v1.0 et beta.

v1.0 inclut les API généralement disponibles. Utilisez la version v1.0 pour toutes les applications de production.
beta inclut des API qui sont actuellement en version préliminaire. Étant donné que nous pourrions apporter des modifications majeures à la version bêta de nos API, nous vous recommandons d’utiliser la version bêta uniquement pour tester les applications en cours de développement ; ne les utilisez pas dans vos applications de production.

Nous recherchons toujours des commentaires sur les versions bêta de nos API. Pour fournir des commentaires ou demander des fonctionnalités, consultez notre Forum des idées de la Plateforme des développeurs Microsoft 365.

Pour plus d’informations sur les versions API, voir Contrôle de version et prise en charge.

Resource

Une ressource peut être une entité ou un type complexe, généralement défini avec des propriétés. Les entités diffèrent des types complexes en incluant toujours une propriété ID.

Votre URL doit inclure la ressource avec laquelle vous interagissez dans la requête, notamment me, utilisateur, groupe , drive, et site. Souvent, les ressources de niveau supérieur incluent également des relations, que vous pouvez utiliser pour accéder à des ressources supplémentaires, par exemple me/messages ou me/drive. Vous pouvez également interagir avec les ressources à l’aide de méthodes. Par exemple, pour envoyer un e-mail, utilisez me/sendMail. Pour plus d’informations, voiraccéder aux données et aux méthodes en accédant à Microsoft Graph.

Chaque ressource peut nécessiter des autorisations différentes pour y accéder. Vous aurez souvent besoin d’un niveau d’autorisations plus élevé pour créer ou mettre à jour une ressource que pour la lire. Pour plus d’informations sur les autorisations requises, consultez la rubrique de référence sur les méthodes.

Pour plus d’informations sur les autorisations, reportez-vous à Référence aux autorisations.

Paramètres de requête

Les paramètres de requête peuvent être des options de requête système OData ou d’autres chaînes qu’une méthode accepte pour personnaliser sa réponse.

Vous pouvez utiliser la requête de système OData optionnel pour inclure plus ou moins de propriétés que la réponse par défaut, filtrer la réponse pour les éléments qui correspondent à une requête personnalisée ou fournir des paramètres supplémentaires pour une méthode.

Par exemple, l’ajout du paramètrefiltersuivant restreint les messages renvoyés uniquement à ceux avec laemailAddresspropriété dejon@contoso.com.

GET https://graph.microsoft.com/v1.0/me/messages?filter=emailAddress eq 'jon@contoso.com'

Pour plus d’informations sur les options de requête OData, voir utiliser les paramètres de requête pour personnaliser les réponses.

Hormis les options de requête OData, certaines méthodes nécessitent des valeurs de paramètre spécifiées dans le cadre de l’URL de requête. Par exemple, vous pouvez obtenir une collection d’événements qui se sont produits au cours d’un laps de temps dans le calendrier d’un utilisateur, en interrogeant la relation de calendarView d'un utilisateur et en spécifiant le pointstartDateTime et endDateTime les valeurs comme paramètres de requête :

GET https://graph.microsoft.com/me/calendarView?startDateTime=2019-09-01T09:00:00.0000000&endDateTime=2019-09-01T17:00:00.0000000

En-têtes

Microsoft Graph prend en charge les en-têtes HTTP standard et les en-têtes personnalisés.

Des API spécifiques peuvent nécessiter l’inclusion d’en-têtes supplémentaires dans la demande. En revanche, Microsoft Graph retourne toujours les en-têtes obligatoires, tels que l’en-tête request-id dans la réponse, ou certains en-têtes peuvent être spécifiques à certaines API ou fonctionnalités, par exemple, l’en-tête Retry-After est inclus lorsque votre application atteint les limites de limitation ou l’en-tête Location inclus pour les opérations de longue durée.

Les en-têtes ne respectent pas la casse comme défini dans rfc 9110 , sauf indication contraire explicite.

Outils d’interaction avec Microsoft Graph

Afficheur Graph

L’Afficheur Graph est un outil web que vous pouvez utiliser pour créer et tester des requêtes à l’aide des API Microsoft Graph. Vous pouvez accéder à l’Afficheur Graph à l’adresse suivante : https://developer.microsoft.com/graph/graph-explorer.

Vous pouvez accéder aux données de démonstration sans vous connecter, ou vous pouvez vous connecter par l’intermédiaire du client de votre choix. Procédez comme suit pour créer la requête :

Sélectionnez la méthode HTTP.
Sélectionnez la version d’API que vous souhaitez utiliser.
Tapez la requête dans la zone de texte de la requête.
Sélectionnez Exécuter la requête.

L’exemple suivant présente une requête qui retourne des informations sur les utilisateurs vers le client de démonstration :

Capture d’écran de l’Afficheur Graph avec une requête utilisateur GET mise en surbrillance

Des exemples de requêtes sont fournis dans l’Afficheur Graph pour vous permettre d’exécuter plus rapidement des requêtes courantes. Pour afficher des exemples disponibles, sélectionnez Afficher plus d’exemples. Sélectionnez Activé pour la série d’exemples que vous voulez afficher, puis après fermeture de la fenêtre de sélection, une liste de requêtes prédéfinies doit s’afficher.

Un code d’état et un message s’affichent après l’envoi de la requête et la réponse apparaît dans l’onglet Aperçu de la réponse.

Postman

Postman est un outil que vous pouvez utiliser pour créer et tester des requêtes à l’aide des API Microsoft Graph. Vous pouvez télécharger Postman à l'adresse suivante : https://www.getpostman.com/. Pour interagir avec Microsoft Graph dans Postman, vous utilisez la collection Microsoft Graph.

Pour obtenir plus d’informations, consultez Utilisation de Postman avec l’API Microsoft Graph.

Étapes suivantes

Vous êtes prêt à devenir opérationnel avec Microsoft Graph. Découvrez le Démarrage rapide ou débutez à l’aide de l’un de nos exemples de codes et kits de développement logiciel (SDK).

Partage via