Comparaison des points de terminaison Microsoft Graph et API REST Outlook

  • Article

Les API REST Outlook sont disponibles dans Microsoft Graph et le point de terminaison de l’API Outlook (https://outlook.office.com/api). Généralement, les API offrent les mêmes fonctionnalités et utilisent les mêmes types de ressource.

Remarque

Nous déconseillons les API REST Outlook.

Les points de terminaison REST Outlook seront entièrement désactivés en mars 2024. Migrez les applications existantes pour utiliser Microsoft Graph. Cela n’inclut pas l’audience de jeton OAuth2 comme décrit dans Authentifier une connexion IMAP, POP ou SMTP à l’aide d’OAuth.

Quel point de terminaison dois-je utiliser ?

Utilisez Microsoft Graph, Outlook REST v2.0 est sur son chemin pour la désactivation. Le point de terminaison Microsoft Graph vous permet d’accéder à Outlook et vous donne accès à bien d’autres services et fonctionnalités, notamment d’autres services Office 365, Enterprise Mobility + Security et Windows 10. Si vous choisissez le point de terminaison Microsoft Graph, votre application obtiendra un jeton d’accès pouvant fournir un accès aux données Outlook et à d’autres ressources, sans avoir à effectuer plusieurs demandes de jeton.

Différences en matière de fonctionnalités

Il existe des fonctionnalités qui, actuellement, sont soit uniquement disponibles sur le point de terminaison Outlook, soit se trouvent uniquement en version bêta sur Microsoft Graph.

Remarque

Nous travaillons continuellement pour intégrer toutes les fonctionnalités actuellement disponibles sur le point de terminaison Outlook dans Microsoft Graph. Veillez à vérifier régulièrement la liste des mises à jour.

Fonctionnalité Différence entre les points de terminaison
Tâches Outlook L’accès aux tâches des utilisateurs dans Microsoft Graph est disponible via l’API To Do
Notifications enrichies L’API Outlook permet aux développeurs de demander que des champs spécifiques soient inclus dans la charge utile de la notification à l’aide du paramètre $select. Microsoft Graph prend actuellement en charge cette fonctionnalité dans le point de terminaison bêta uniquement, en envisageant de la publier prochainement dans la version 1.0.
Notifications de diffusion en continu L’API Outlook prend en charge les notifications de diffusion en continu dans la version d’évaluation de la version bêta du point de terminaison. Microsoft Graph ne prend pas en charge cette fonctionnalité et ne fait pas partie de la feuille de route.

Passer d’un point de terminaison Outlook à Microsoft Graph

Les API sont très similaires sur le point de terminaison Microsoft Graph et sur le point de terminaison Outlook. Toutefois, il existe quelques différences dont vous devez être conscients, en particulier si vous migrez vers Microsoft Graph ou si vous utilisez les deux points de terminaison dans la même application.

Versions d’API

L’API Microsoft Graph propose deux versions : v1.0 et beta, tandis que Outlook propose v1.0, v2.0 et beta. Microsoft Graph v1.0 correspond à Outlook v2.0et Microsoft Graph beta correspond à Outlook beta.

Étendues OAuth

Étant donné que les points de terminaison Microsoft Graph et Outlook s’appuient tous deux sur les jetons émis par Azure AD et que les autorisations utilisées sont identiques, la manière dont votre application demande ces autorisations est légèrement différente pour chaque point de terminaison.

Point de terminaison Azure v2 OAuth2

Les applications qui utilisent le point de terminaison Azure AD v2.0 pour OAuth2 demandent des étendues d’autorisation dans le paramètre scope dans une demande d’authentification ou de jeton.

  • Pour Microsoft Graph, les applications indiquent des autorisations dotées du préfixe https://graph.microsoft.com/. Par exemple, une application peut demander l’autorisation Mail.Read en incluant https://graph.microsoft.com/Mail.Read dans le paramètre scope.
  • Pour le point de terminaison Outlook, les applications indiquent des autorisations dotées du préfixe https://outlook.office.com/. Par exemple, une application peut demander l’autorisation Mail.Read en incluant https://outlook.office.com/Mail.Read dans le paramètre scope.

Remarque

Si un domaine n’est pas inclus dans une étendue, on supposera qu’il s’agit de Microsoft Graph.

Les jetons émis pour un point de terminaison donné ne sont pas valides pour l’autre. Par ailleurs, vous ne pouvez pas mélanger les autorisations pour un point de terminaison avec les autorisations pour l’autre au sein d’une seule demande.

Le point de terminaison Azure AD v2.0 prend uniquement en charge le flux des informations d’identification client pour le point de terminaison Microsoft Graph. Les applications devant utiliser un jeton pour application uniquement avec le point de terminaison Outlook doivent utiliser le point de terminaison Azure AD v1.0.

Point de terminaison Azure v1 OAuth2

Les applications qui utilisent le point de terminaison Azure AD v1.0 indiquent les autorisations qu’elles requièrent lors de l’enregistrement des applications dans le portail Azure.

  • Pour Microsoft Graph, sélectionnez l’API Microsoft Graph lorsque vous ajoutez les autorisations requises.
  • Pour le point de terminaison Outlook, sélectionnez l’API Office 365 Exchange Online lorsque vous ajoutez les autorisations requises.

Noms de propriété de ressource

Les ressources sont en grande partie identiques entre Microsoft Graph et Outlook. Toutefois, les deux points de terminaison gèrent différemment la casse des noms de propriété. Microsoft Graph utilise camelCase pour les noms de propriété, tandis qu’Outlook utilise PascalCase. Il est nécessaire de modifier la casse pour effectuer la conversion entre les deux. Les noms de propriété modifiés sont spécifiés dans le tableau ci-dessous.

Par exemple, la ressource de message Microsoft Graph définit les propriétés telles que subject, from et receivedDateTime. Pour le point de terminaison Outlook, ces propriétés sont nommées Subject, From et ReceivedDateTime.

Noms de propriété modifiés

Les noms de propriété suivants sont différents pour Microsoft Graph et Outlook.

Type de ressource Propriété Microsoft Graph Propriété Outlook
contact mobilePhone MobilePhone1

Suivi des modifications (synchronisation)

Les deux points de terminaison prennent en charge les requêtes de collection pour les modifications concernant un état de synchronisation. Même si la fonctionnalité est la même, les méthodes sont légèrement différentes.

Sur le point de terminaison Microsoft Graph, les modifications sont interrogées à l’aide de requêtes delta. Cela est implémenté comme une fonction delta sur la collection.

Sur le point de terminaison Outlook, les modifications sont interrogées via l’ajout d’un en-tête aux requêtes de collection de ressources normales.

Traitement par lots

Les deux points de terminaison prennent en charge le traitement par lots comportant jusqu'à 20 demandes distinctes dans une seule demande HTTP.

Le traitement par lots Microsoft Graph encode plusieurs demandes API dans un corps JSON avec un type de contenu de application/json.

Outre le format du corps JSON, le traitement par lots de point de terminaison Outlook prend également en charge un format de corps à plusieurs parties avec un type de contenu de multipart/mixed.

Exemple : extraction d’un message

Examinons un exemple simple. Dans ce scénario, une application web demande une liste de messages dans la boîte de réception de l’utilisateur.

Microsoft Graph

L’application doit d’abord disposer de la connexion de l’utilisateur pour autoriser l’application. Étant donné que l’application utilise l’étendue Microsoft Graph Mail.Read, l’URL d’autorisation ressemble à ce qui suit :

https://login.microsoftonline.com/common/oauth2/v2.0/authorize?scope=openid+Mail.Read&response_type=code&client_id=<SOME GUID>&redirect_uri=<REDIRECT URL>

Une fois que l’application a un jeton d’accès, elle envoie la demande suivante :

GET https://graph.microsoft.com/v1.0/me/mailfolders/inbox/messages?$top=1&$select=subject,from,receivedDateTime,isRead
Accept: application/json
Authorization: Bearer <token>

Le serveur renvoie la réponse suivante :

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('b63d5fb9-4f43-44c4-8f9d-fd0727842876')/mailFolders('inbox')/messages(subject,from,receivedDateTime,isRead)",
  "@odata.nextLink": "https://graph.microsoft.com/v1.0/me/mailfolders/inbox/messages?$top=1&$select=subject%2cfrom%2creceivedDateTime%2cisRead&$skip=1",
  "value": [
    {
      "@odata.etag": "W/\"CwAAABYAAACd9nJ/tVysQos2hTfspaWRAAD8ujHV\"",
      "id": "AAMkAGI2...",
      "receivedDateTime": "2015-11-03T03:21:04Z",
      "subject": "Scrum",
      "isRead": false,
      "from": {
        "emailAddress": {
          "name": "user0TestUser",
          "address": "user0@contoso.com"
        }
      }
    }
  ]
}

Outlook

L’application doit d’abord disposer de la connexion de l’utilisateur pour autoriser l’application. Étant donné que l’application utilise l’étendue Outlook https://outlook.office.com/Mail.Read, l’URL d’autorisation ressemble à ce qui suit :

https://login.microsoftonline.com/common/oauth2/v2.0/authorize?scope=openid+https%3A%2F%2Foutlook.office.com%2Fmail.read&response_type=code&client_id=<SOME GUID>&redirect_uri=<REDIRECT URL>

Une fois que l’application a un jeton d’accès, elle envoie la demande suivante :

GET https://outlook.office.com/api/v2.0/me/mailfolders/inbox/messages?$top=1&$select=Subject,From,ReceivedDateTime,IsRead
Accept: application/json
Authorization: Bearer <token>

Le serveur renvoie la réponse suivante :

{
  "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/MailFolders('inbox')/Messages(Subject,From,ReceivedDateTime,IsRead)",
  "@odata.nextLink": "https://outlook.office.com/api/v2.0/$metadata#Me/MailFolders('inbox')/Messages(Subject,From,ReceivedDateTime,IsRead)",
  "value": [
    {
      "@odata.etag": "W/\"CwAAABYAAACd9nJ/tVysQos2hTfspaWRAAD8ujHV\"",
      "Id": "AAMkAGI2...",
      "ReceivedDateTime": "2015-11-03T03:21:04Z",
      "Subject": "Scrum",
      "IsRead": false,
      "From": {
        "EmailAddress": {
          "Name": "user0TestUser",
          "Address": "user0@contoso.com"
        }
      }
    }
  ]
}