Accéder aux données et aux méthodes en explorant Microsoft Graph

  • Article

En plus d’utiliser microsoft API Graph pour lire et écrire des données, vous pouvez utiliser un certain nombre de modèles de requête pour parcourir les ressources dans Microsoft Graph. Le document de métadonnées vous aide également à comprendre le modèle de données des ressources et des relations dans Microsoft Graph.

Métadonnées de l’API Microsoft Graph

Le document de métadonnées ($metadata) est publié au niveau de la racine de service. Vous pouvez afficher le document de service pour les versions v1.0 et bêta de Microsoft API Graph via les URL suivantes.

Métadonnées de la version 1.0 de l’API Microsoft Graph

https://graph.microsoft.com/v1.0/$metadata

Métadonnées de la version bêta de l’API Microsoft Graph

https://graph.microsoft.com/beta/$metadata

Les métadonnées vous permettent de voir et de comprendre le modèle de données de Microsoft Graph, y compris les types d’entité, les types complexes et les énumérations qui constituent les ressources représentées dans les paquets de demande et de réponse.

Les métadonnées prennent également en charge la définition des types, des méthodes et des énumérations dans les espaces de noms OData correspondants. La majorité de l'API Microsoft Graph est définie dans l'espace de noms OData, microsoft.graph. Quelques API sont définies dans les sous-espaces de nom, par exemple . microsoft.graph.callRecords

Vous pouvez utiliser les métadonnées pour découvrir les relations entre les entités dans Microsoft Graph et établir des URL qui naviguent entre ces entités.

Remarque

  • Utilisez les ID de ressource dans le cas où ils sont renvoyés par les API Microsoft Graph.
  • Supposez que les ID ressources, les valeurs que vous attribuez, les autres valeurs codées en Base64 respectent la casse.
  • Supposez les noms des ressources URL de chemin d’accès, les paramètres de requête, les noms d’action et de fonction, leurs paramètres de corps de demande, y compris les noms et valeurs de propriété de l’API, ne respectent pas la casse.

Afficher une collection de ressources

Microsoft Graph vous permet d’afficher les ressources d’un client à l’aide de requêtes HTTP GET. La réponse à la requête inclut des propriétés de chaque ressource. Les ressources d’entité sont identifiées par leur ID. Le format d’un ID de ressource varie généralement en fonction du type de ressource.

Par exemple, vous pouvez obtenir la collection de ressources utilisateur définies dans un client :

GET https://graph.microsoft.com/v1.0/users HTTP/1.1
Authorization : Bearer {access_token}

En cas de réussite, vous obtenez une réponse 200 OK qui contient la collection de ressources utilisateur dans la charge utile. Chaque utilisateur est identifié par la propriété id et accompagné de ses propriétés par défaut. La charge utile indiquée ci-dessous est tronquée par souci de concision.

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users",
  "value":[
    {
      "id":"f71f1f74-bf1f-4e6b-b266-c777ea76e2c7",
      "businessPhones":[

      ],
      "displayName":"CIE Administrator",
      "givenName":"CIE",
      "jobTitle":null,
      "mail":"admin@contoso.com",
      "mobilePhone":"+1 3528700812",
      "officeLocation":null,
      "preferredLanguage":"en-US",
      "surname":"Administrator",
      "userPrincipalName":"admin@contoso.com"
    },
    {
      "id":"d66f2902-9d12-4ff8-ab01-21ec6706079f",
      "businessPhones":[

      ],
      "displayName":"Alan Steiner",
      "givenName":"Alan",
      "jobTitle":"VP Corporate Marketing",
      "mail":"alans@contoso.com",
      "mobilePhone":null,
      "officeLocation":null,
      "preferredLanguage":"en-US",
      "surname":"Steiner",
      "userPrincipalName":"alans@contoso.com"
    }
  ]
}

Microsoft Graph vous permet également d’afficher les collections en parcourant les relations d’une ressource avec une autre. Par exemple, via la propriété de navigation mailFolders d’un utilisateur, vous pouvez interroger la collection de ressources mailFolder dans la boîte aux lettres de l’utilisateur :

GET https://graph.microsoft.com/v1.0/me/mailfolders HTTP/1.1
Authorization : Bearer {access_token}

En cas de réussite, vous obtenez une réponse 200 OK qui contient la collection de ressources mailFolder dans la charge utile. Chaque mailFolder est identifié par la propriété id et accompagné de ses propriétés. La charge utile indiquée ci-dessous est tronquée par souci de concision.

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users('16f5a7b6-5a15-4568-aa5a-31bb117e9967')/mailFolders",
  "value":[
    {
      "id":"AAMkADRm9AABDGisXAAA=",
      "displayName":"Archive",
      "parentFolderId":"AQMkADRmZWj0AAAIBCAAAAA==",
      "childFolderCount":0,
      "unreadItemCount":0,
      "totalItemCount":0
    },
    {
      "id":"AQMkADRm0AAAIBXAAAAA==",
      "displayName":"Sales reports",
      "parentFolderId":"AQMkADRmZWj0AAAIBCAAAAA==",
      "childFolderCount":0,
      "unreadItemCount":0,
      "totalItemCount":0
    },
    {
      "id":"AAMkADRCxI9AAAT6CAIAAA=",
      "displayName":"Conversation History",
      "parentFolderId":"AQMkADRmZWj0AAAIBCAAAAA==",
      "childFolderCount":1,
      "unreadItemCount":0,
      "totalItemCount":0
    }
  ]
}

Afficher une ressource spécifique à partir d’une collection par ID

Pour la plupart des entités dans Microsoft Graph, l’ID est la clé primaire.

Toujours en utilisant la ressource user comme exemple, vous pouvez utiliser une requête GET HTTPS pour obtenir les informations relatives à un utilisateur spécifique par ID. Pour une entité user , vous pouvez utiliser la propriété id ou userPrincipalName comme identificateur.

L’exemple de requête suivant utilise la valeur userPrincipalName comme ID utilisateur.

GET https://graph.microsoft.com/v1.0/users/john.doe@contoso.com HTTP/1.1
Authorization : Bearer {access_token}

Si l’opération réussit, vous obtiendrez une réponse 200 OK contenant la représentation de la ressource utilisateur dans la charge, comme illustré.

HTTP/1.1 200 OK
content-type: application/json;odata.metadata=minimal
content-length: 982

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users/$entity",
    "id": "c95e3b3a-c33b-48da-a6e9-eb101e8a4205",
    "city": "Redmond",
    "country": "USA",
    "department": "Help Center",
    "displayName": "John Doe",
    "givenName": "John",
    "userPrincipalName": "john.doe@contoso.com",

    ...
}

Afficher une ressource spécifique à partir d’une collection par clé de remplacement

Certaines entités prennent en charge une autre clé, que vous pouvez utiliser pour récupérer un objet au lieu de l’ID de clé primaire. Par exemple, les entités application et servicePrincipal prennent en charge la clé alternative appId .

L’exemple suivant utilise la syntaxe de clé alternative pour récupérer un principal de service par son appId.

GET https://graph.microsoft.com/v1.0/servicePrincipals(appId='00000003-0000-0000-c000-000000000000') HTTP/1.1
Authorization : Bearer {access_token}

Lire les propriétés spécifiques d’une ressource

Pour récupérer uniquement les données biographiques de l’utilisateur, telles que la description de ses informations personnelles et ses compétences, vous pouvez ajouter le paramètre de requête $select à la demande précédente, comme illustré dans l’exemple suivant.

GET https://graph.microsoft.com/v1.0/users/john.doe@contoso.com?$select=displayName,aboutMe,skills HTTP/1.1
Authorization : Bearer {access_token}

La réponse réussie renvoie l’état 200 OK et une charge, comme illustré.

HTTP/1.1 200 OK
content-type: application/json;odata.metadata=minimal
content-length: 169

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users/$entity",
    "aboutMe": "A cool and nice guy.",
    "displayName": "John Doe",
    "skills": [
        "n-Lingual",
        "public speaking",
        "doodling"
    ]
}

Ici, au lieu des ensembles de propriété entiers sur l’entité user, seules les propriétés de base aboutMe, displayName et skills sont renvoyées.

Lorsque vous effectuez une requête GET sans utiliser $select pour limiter la quantité de données de propriétés, Microsoft Graph inclut une propriété @microsoft.graph.tips qui fournit une recommandation de bonne pratique pour l’utilisation $select similaire au message suivant :

"@microsoft.graph.tips": "Use $select to choose only the properties your app needs, as this can lead to performance improvements. For example: GET groups?$select=appMetadata,assignedLabels",

Lire une seule propriété d’une ressource

Vous pouvez récupérer une seule propriété d’une ressource sans utiliser $select, en spécifiant le nom de la propriété comme segment de chemin d’accès. Cette requête ne vous permet pas de récupérer plusieurs propriétés, mais elle peut être utile lorsque vous n’avez besoin que d’une seule propriété.

L’exemple suivant récupère le displayName d’un utilisateur.

GET https://graph.microsoft.com/beta/users/8afc02cb-4d62-4dba-b536-9f6d73e9be26/displayName HTTP/1.1
Authorization : Bearer {access_token}

Lire les propriétés spécifiques des ressources dans une collection

En plus de la lecture des propriétés spécifiques d’une ressource, vous pouvez également appliquer le même paramètre de requête $select à une collection pour obtenir toutes les ressources dans la collection avec simplement les propriétés spécifiques sur chacune.

Par exemple, pour interroger le nom des éléments de lecteur de l’utilisateur connecté, vous pouvez envoyer la requête HTTPS GET suivante.

GET https://graph.microsoft.com/v1.0/me/drive/root/children?$select=name HTTP/1.1
Authorization : Bearer {access_token}

La réponse réussie renvoie un code d’état 200 OK et une charge contenant uniquement les noms des fichiers partagés, comme indiqué dans l’exemple suivant.

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('john.doe%40contoso.com')/drive/root/children(name,type)",
  "value": [
    {
      "@odata.etag": "\"{896A8E4D-27BF-424B-A0DA-F073AE6570E2},2\"",
      "name": "Shared with Everyone"
    },
    {
      "@odata.etag": "\"{B39D5D2E-E968-491A-B0EB-D5D0431CB423},1\"",
      "name": "Documents"
    },
    {
      "@odata.etag": "\"{9B51EA38-3EE6-4DC1-96A6-230E325EF054},2\"",
      "name": "newFile.txt"
    }
  ]
}

Traversée d’une ressource vers une autre via une relation

Un responsable a une relation directReports avec les autres utilisateurs qui lui rendent compte. Pour interroger la liste des collaborateurs d’un utilisateur, vous pouvez utiliser la requête HTTPS GET pour naviguer vers la cible souhaitée via la traversée de relation.

GET https://graph.microsoft.com/v1.0/users/john.doe@contoso.com/directReports HTTP/1.1
Authorization : Bearer {access_token}

La réponse réussie renvoie l’état 200 OK et une charge, comme illustré.

HTTP/1.1 200 OK
content-type: application/json;odata.metadata=minimal
content-length: 152

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#directoryObjects/$entity",
    "@odata.type": "#microsoft.graph.user",
    "id": "c37b074d-fe9d-4e68-83ad-b4401d3be174",
    "department": "Sales & Marketing",
    "displayName": "Bonnie Kearney",

    ...
}

De même, vous pouvez suivre une relation pour naviguer vers des ressources connexes. Par exemple, la relation utilisateur-messages permet de parcourir un utilisateur Microsoft Entra à un ensemble de messages électroniques Outlook. L’exemple suivant montre comment effectuer cette opération dans un appel d’API REST.

GET https://graph.microsoft.com/v1.0/me/messages HTTP/1.1
Authorization : Bearer {access_token}

La réponse réussie renvoie l’état 200 OK et une charge, comme illustré.

HTTP/1.1 200 OK
content-type: application/json;odata.metadata=minimal
odata-version: 4.0
content-length: 147

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('john.doe%40contoso.com')/Messages",
  "@odata.nextLink": "https://graph.microsoft.com/v1.0/me/messages?$top=1&$skip=1",
  "value": [
    {
      "@odata.etag": "W/\"FwAAABYAAABMR67yw0CmT4x0kVgQUH/3AAJL+Kej\"",
      "id": "<id-value>",
      "createdDateTime": "2015-11-14T00:24:42Z",
      "lastModifiedDateTime": "2015-11-14T00:24:42Z",
      "changeKey": "FwAAABYAAABMR67yw0CmT4x0kVgQUH/3AAJL+Kej",
      "categories": [],
      "receivedDateTime": "2015-11-14T00:24:42Z",
      "sentDateTime": "2015-11-14T00:24:28Z",
      "hasAttachments": false,
      "subject": "Did you see last night's game?",
      "body": {
        "ContentType": "HTML",
        "Content": "<content>"
      },
      "BodyPreview": "it was great!",
      "Importance": "Normal",

       ...
    }
  ]
}

Vous pouvez afficher toutes les relations sur une ressource donnée en accédant aux métadonnées, en recherchant EntityType et en observant NavigationProperty pour cet EntityType.

Fonctions et actions d’appel

Microsoft Graph prend également en charge des actions et fonctions permettant de manipuler des ressources au-delà de la simple création, lecture, mise à jour et suppression d’opérations(CRUD). Elles prennent souvent la forme de requêtes POST HTTPS pour admettre des arguments de la fonction. Par exemple, la requête suivante permet à l’utilisateur connecté (me) d’envoyer un e-mail.

POST https://graph.microsoft.com/v1.0/me/sendMail HTTP/1.1
authorization: bearer {access_token}
content-type: application/json
content-length: 96

{
  "message": {
    "subject": "Meet for lunch?",
    "body": {
      "contentType": "Text",
      "content": "The new cafeteria is open."
    },
    "toRecipients": [
      {
        "emailAddress": {
          "address": "garthf@contoso.com"
        }
      }
    ],
    "attachments": [
      {
        "@odata.type": "microsoft.graph.fileAttachment",
        "name": "menu.txt",
        "contentBytes": "bWFjIGFuZCBjaGVlc2UgdG9kYXk="
      }
    ]
  },
  "saveToSentItems": "false"
}

Vous pouvez voir toutes les fonctions disponibles dans les métadonnées. Elles apparaissent sous la forme De fonctions ou d’actions.

Utiliser les kits de développement logiciel Microsoft Graph

Vous appréciez la puissance et la simplicité du kit de développement logiciel (SDK) ? Bien que vous puissiez toujours utiliser des API REST pour appeler Microsoft Graph, nous fournissons également des sdk pour de nombreuses plateformes populaires. Pour explorer les Kits de développement logiciel (SDK) disponibles, consultez Exemples de code et Kits de développement logiciel (SDK).

Contenu connexe