Interroger Microsoft Graph à l’aide de REST

3 minutes

Microsoft Graph est une API web RESTful qui vous permet d’accéder à des ressources de service cloud Microsoft. Une fois que vous avez inscrit votre application et obtenu les jetons d’authentification d’un utilisateur ou d’un service, vous pouvez adresser des demandes à l’API Microsoft Graph.

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. Quelques ensembles d’API sont définis dans leurs sous-espaces de noms, comme l’API Call Records, qui définit des ressources comme callRecord dans microsoft.graph.callRecords.

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

Appeler une méthode d’API REST

Pour lire ou écrire dans une ressource telle qu’un utilisateur ou un e-mail, créez une requête qui ressemble à ceci :

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

Les composants d’une requête sont les suivants :

{HTTP method} - Méthode HTTP utilisée sur la requête pour Microsoft Graph.
{version} - Version de l’API Microsoft Graph utilisée par votre application.
{resource} - La ressource dans Microsoft Graph à laquelle vous faites référence.
{query-parameters} - Options de requête OData ou paramètres de méthode REST facultatifs qui personnalisent la réponse.

Une fois que vous avez effectué une requête, une réponse est renvoyée, et comprend :

Code d’état : Code d’état HTTP qui indique la réussite ou l’échec.
Message de réponse : Les données que vous avez demandées ou le résultat de l’opération. Le message de réponse peut être vide pour certaines opérations.
nextLink - Si votre requête renvoie de nombreuses données, vous devez effectuer une pagination à l’aide de l’URL retournée dans @odata.nextLink.

Méthodes HTTP

Microsoft Graph utilise la méthode HTTP sur votre requête pour déterminer ce que fait votre requête. L’API prend en charge les méthodes suivantes.

Méthode	Description
GET	Lire des données à partir d’une ressource.
POST	Créer une ressource ou effectuer une action.
PATCH	Mettre à jour une ressource avec de nouvelles valeurs.
PUT	Remplacer une ressource par une autre.
DELETE	Supprimer une ressource.

Pour les méthodes CRUD GET et DELETE, aucun corps de requête n’est requis.
Les méthodes POST, PATCH et PUT nécessitent un corps de requête, spécifié au format JSON, qui contient des informations supplémentaires. Il peut s’agir des valeurs des propriétés de la ressource.

Version

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

v1.0 comprend les API en disponibilité générale. Utilisez la version v1.0 pour toutes les applications de production.
beta comprend les API actuellement en préversion. Comme nos API bêta sont susceptibles d’introduire des changements cassants, nous vous recommandons d’utiliser la version bêta uniquement pour tester des applications en phase de développement. N’utilisez pas les API bêta dans vos applications de production.

Ressource

Une ressource peut être une entité ou un type complexe, que vous définissez généralement avec des propriétés. Les entités diffèrent des types complexes en cela qu’elles incluent toujours une propriété id.

Votre URL inclut la ressource avec laquelle vous interagissez dans la requête, par exemple me, user, group, drive et site. Souvent, les ressources de niveau supérieur incluent également des relations, que vous pouvez utiliser pour accéder à d’autres ressources, comme 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.

Chaque ressource peut nécessiter des autorisations différentes pour y accéder. Vous avez 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.

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 acceptées par une méthode pour personnaliser sa réponse.

Vous pouvez utiliser des options de requête système OData facultatives 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 d’autres paramètres pour une méthode.

Par exemple, l’ajout du paramètre filter suivant limite les messages retournés à ceux dont la propriété emailAddress a la valeur jon@contoso.com.

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

Autres ressources

Voici des liens vers des outils que vous pouvez utiliser pour générer et tester des requêtes à l’aide des API Microsoft Graph.

Continuer