Comparaison des points de terminaison Microsoft Graph et API REST OutlookCompare Microsoft Graph and Outlook REST API endpoints

Les API REST Outlook sont disponibles dans Microsoft Graph et le point de terminaison d’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 ressources.The Outlook REST APIs are available in both Microsoft Graph and the Outlook API endpoint (https://outlook.office.com/api). The APIs generally provide the same functionality and use the same resource types.

Quel point de terminaison dois-je utiliser ?Which endpoint should I use?

Utilisez Microsoft Graph dès que possible.Use Microsoft Graph whenever possible. 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.The Microsoft Graph endpoint lets you access Outlook and many more services and features, including other Office 365 services, Enterprise Mobility + Security, and 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.Choosing the Microsoft Graph endpoint allows your app to get an access token that can provide access to both Outlook data and other resources, without having to make multiple token requests.

Différences en matière de fonctionnalitésFeature differences

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.There are some features that are currently either only available on the Outlook endpoint, or are only in beta in Microsoft Graph. Si votre application a besoin de ces fonctionnalités, vous pouvez y accéder par le biais des points de terminaison Outlook.If your app needs these features, you should access them via the Outlook endpoint.

Notes

Nous travaillons continuellement pour intégrer toutes les fonctionnalités actuellement disponibles sur le point de terminaison Outlook dans Microsoft Graph.We are constantly working to incorporate all of the features currently available on the Outlook endpoint into Microsoft Graph. Veillez à vérifier régulièrement la liste des mises à jour.Be sure to check back periodically as this list is updated.

FonctionnalitéFeature Différence entre les points de terminaisonDifference between endpoints
Tâches OutlookOutlook tasks L’API Outlook fournit l’accès aux tâches de l’utilisateur.The Outlook API provides access to user's tasks. Cette fonctionnalité est actuellement disponible uniquement en version bêta dans Microsoft Graph.This feature is currently only available in beta in Microsoft Graph.
Pièces jointes d’une taille supérieure à 4 MoAttachments over 4MB in size La prise en charge de pièces jointes volumineuses est disponible uniquement dans la version bêta de Microsoft Graph.Large file attachment support is only available in beta in Microsoft Graph.
Notifications enrichiesRich notifications 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.The Outlook API allows developers to request specific fields to be included with the notification payload by using the $select parameter. Microsoft Graph ne prend pas en charge cette fonctionnalité.Microsoft Graph does not support this feature.
Notifications de diffusion en continuStreaming notifications 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.The Outlook API supports streaming notifications in preview on the beta endpoint. Microsoft Graph ne prend pas en charge cette fonctionnalité.Microsoft Graph does not support this feature.

Passer d’un point de terminaison Outlook à Microsoft GraphMoving from Outlook endpoint to Microsoft Graph

Les API sont très similaires sur le point de terminaison Microsoft Graph et sur le point de terminaison Outlook.The APIs are very similar on the Microsoft Graph endpoint and the Outlook endpoint. 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.However, there are some differences to be aware of, especially if you are migrating to Microsoft Graph or using both endpoints in the same application.

Versions d’APIAPI versions

L’API Microsoft Graph propose deux versions : v1.0 et beta, tandis que Outlook propose v1.0, v2.0 et beta.The Microsoft Graph API offers two versions: v1.0 and beta, while Outlook offers v1.0, v2.0, and beta. Microsoft Graph v1.0 correspond à Outlook v2.0et Microsoft Graph beta correspond à Outlook beta.Microsoft Graph v1.0 matches Outlook v2.0, and Microsoft Graph beta matches Outlook beta. La version Outlook v1.0 est déconseillée.The Outlook v1.0 version is being deprecated.

Étendues OAuthOAuth scopes

É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.While the Microsoft Graph and Outlook endpoints both rely on Azure AD-issued tokens, and the permissions used are the same, the way that your application requests those permissions is slightly different for each endpoint.

Point de terminaison Azure v2 OAuth2Azure v2 OAuth2 endpoint

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.Apps that use the Azure AD v2.0 endpoint for OAuth2 request permission scopes in the scope parameter in an authentication or token request.

  • Pour Microsoft Graph, les applications indiquent des autorisations dotées du préfixe https://graph.microsoft.com/.For Microsoft Graph, apps specify permissions prefixed with 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.For example, an app can request the Mail.Read permission by including https://graph.microsoft.com/Mail.Read in the scope parameter.
  • Pour le point de terminaison Outlook, les applications indiquent des autorisations dotées du préfixe https://outlook.office.com/.For the Outlook endpoint, apps specify permissions prefixed with 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.For example, an app can request the Mail.Read permission by including https://outlook.office.com/Mail.Read in the scope parameter.

Notes

Si un domaine n’est pas inclus dans une étendue, on supposera qu’il s’agit de Microsoft Graph.If a domain is not included in a scope, Microsoft Graph is assumed.

Les jetons émis pour un point de terminaison donné ne sont pas valides pour l’autre.Tokens issued for one endpoint are not valid for the other. 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.Additionally, you cannot mix permissions for one endpoint with permissions for the other in a single request.

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.The Azure AD v2.0 endpoint only supports the client credentials flow for the Microsoft Graph endpoint. 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.Apps that need to use an app-only token with the Outlook endpoint must use the Azure AD v1.0 endpoint.

Point de terminaison Azure v1 OAuth2Azure v1 OAuth2 endpoint

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.Apps that use the Azure AD v1.0 endpoint specify their required permissions during app registration in the Azure Portal.

  • Pour Microsoft Graph, sélectionnez l’API Microsoft Graph lorsque vous ajoutez les autorisations requises.For Microsoft Graph, choose the Microsoft Graph API when adding required permissions.
  • Pour le point de terminaison Outlook, sélectionnez l’API Office 365 Exchange Online lorsque vous ajoutez les autorisations requises.For the Outlook endpoint, choose the Office 365 Exchange Online API when adding required permissions.

Noms de propriété de ressourceResource property names

Les ressources sont identiques pour 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.The resources are the same between Microsoft Graph and Outlook. However, the two endpoints handle casing of the property names differently. Microsoft Graph uses camelCase for property names, while Outlook uses PascalCase. Translating between the two simply requires converting the case.

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.For example, the Microsoft Graph message resource defines properties such as subject, from, and receivedDateTime. On the Outlook endpoint, these properties are named Subject, From, and ReceivedDateTime.

Suivi des modifications (synchronisation)Tracking changes (synchronization)

Les deux points de terminaison prennent en charge les requêtes de collection pour les modifications concernant un état de synchronisation.Both endpoints support querying collections for changes relative to a synchronization state. Même si la fonctionnalité est la même, les méthodes sont légèrement différentes.While the functionality is the same, the methods are slightly different.

Sur le point de terminaison Microsoft Graph, les modifications sont interrogées à l’aide de requêtes delta.On the Microsoft Graph endpoint, changes are queried by using delta queries. Cela est implémenté comme une fonction delta sur la collection.This is implemented as a delta function on the 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.On the Outlook endpoint, changes are queried by adding a header to normal resource collection queries.

Traitement par lotsBatching

Les deux points de terminaison prennent en charge le traitement par lots comportant jusqu'à 20 demandes distinctes dans une seule demande HTTP.Both endpoints support batching up to 20 separate requests into one HTTP request.

Le traitement par lots Microsoft Graph encode plusieurs demandes API dans un corps JSON avec un type de contenu de application/json.Microsoft Graph batching encodes multiple API requests into a JSON body with a content type of 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.In addition to the JSON body format, Outlook endpoint batching also supports a multi-part body format with a content type of multipart/mixed.

Exemple : extraction d’un messageExample: retrieving a 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.Let's take a look at a simple example. In this scenario, a web app requests a list of messages in the user's inbox.

Microsoft GraphMicrosoft 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 :First, the app has the user sign in to authorize the application. Because the app uses the Microsoft Graph scope Mail.Read, the authorization URL looks like the following:

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 :Once the app has an access token, it sends the following request:

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 :The server returns the following response:

{
  "@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"
        }
      }
    }
  ]
}

OutlookOutlook

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 :First, the app has the user sign in to authorize the application. Because the app uses the Outlook scope https://outlook.office.com/Mail.Read, the authorization URL looks like the following:

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 :Once the app has an access token, it sends the following request:

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 :The server returns the following response:

{
  "@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"
        }
      }
    }
  ]
}