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

Outre l’utilisation de l’API Microsoft Graph pour lire et écrire des données, vous pouvez utiliser un certain nombre de modèles de requête pour parcourir les ressources de Microsoft Graph. Le document de métadonnées vous permet également de 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 l’API Microsoft 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.

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.

Notes

  • 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 peut être un GUID et 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}

Si l’opération aboutit, vous recevez une réponse 200 OK qui contient la collection de ressources user dans la charge utile. Chaque utilisateur est identifié par la propriété id et est accompagné de ses propriétés par défaut. La charge utile ci-dessous est tronquée pour des raisons 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.onmicrosoft.com",
      "mobilePhone":"+1 3528700812",
      "officeLocation":null,
      "preferredLanguage":"en-US",
      "surname":"Administrator",
      "userPrincipalName":"admin@contoso.onmicrosoft.com"
    },
    {
      "id":"d66f2902-9d12-4ff8-ab01-21ec6706079f",
      "businessPhones":[

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

Microsoft Graph vous permet de voir les collections en naviguant parmi les relations entre deux ressources. Par exemple, en utilisant la propriété de navigation mailFolders d’un utilisateur, vous pouvez demander 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}

Si l’opération aboutit, vous recevez une réponse 200 OK qui contient la collection de ressources mailFolder dans la charge utile. Chaque élément mailFolder est identifié par la propriété id et est accompagné de ses propriétés. La charge utile ci-dessous est tronquée pour des raisons 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

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.onmicrosoft.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.onmicrosoft.com",

    ...
}

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.onmicrosoft.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.

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.onmicrosoft.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 font des signalements. 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.onmicrosoft.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 user-messages permet la traversée d’un utilisateur Azure Active Directory (Azure AD) vers un ensemble de messages de Courrier Outlook. L’exemple ci-dessous décrit comment procéder 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.onmicrosoft.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. Elles prennent souvent la forme de requêtes POST HTTPS pour admettre des arguments de l’action ou 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.onmicrosoft.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 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) ? Vous pouvez toujours utiliser les API REST pour appeler Microsoft Graph et nous proposons un kit de développement logiciel (SDK) pour de nombreuses plates-formes courantes. Pour explorer les kits de développement logiciel (SDK) disponibles, consultez les exemples de code et SDK.

Voir aussi