Vue d’ensemble de l’utilisation d’API REST OutlookOverview of using the Outlook REST APIs

Conseil

Essayez des exemples d’appels REST l’Explorateur Graph. Vous pouvez utiliser votre propre compte ou l’un de vos comptes de test. Une fois que vous avez terminé d’explorer l’API, revenez sur cette page et sélectionnez votre plateforme favorite sur la gauche. Nous allons vous guider à travers les étapes d’écriture d’une application simple permettant de récupérer des messages à partir de votre boîte de réception.Try out sample REST calls in the Graph Explorer. You can use your own account, or one of our test accounts. Once you're done exploring the API, come back here and select your favorite platform on the left. We'll guide you through the steps to write a simple application to retrieve messages from your inbox.

Si votre plateforme préférée n’est pas encore répertoriée, poursuivez la lecture de cette page. Nous allons suivre les mêmes étapes en utilisant des requêtes HTTP brutes.If your preferred platform isn't listed yet, continue reading on this page. We'll go through the same set of steps using raw HTTP requests.

L’objectif de ce guide est de passer en revue les étapes du processus d’appel de l’API de messagerie Outlook pour extraire des messages dans Office 365 et Outlook.com. Contrairement aux guides de prise en main propres à la plateforme, ce guide se concentre sur les requêtes et les réponses OAuth et REST. Il décrira la séquence des demandes et réponses qu’une application utilise pour authentifier et récupérer des messages.The purpose of this guide is to walk through the process of calling the Outlook Mail API to retrieve messages in Office 365 and Outlook.com. Unlike the platform-specific getting started guides, this guide focuses on the OAuth and REST requests and responses. It will cover the sequence of requests and responses that an app uses to authenticate and retrieve messages.

Ce didacticiel utilise Microsoft Graph pour appeler l’API de messagerie.This tutorial will use Microsoft Graph to call the Mail API. Microsoft recommande d’utiliser Microsoft Graph pour accéder à la messagerie, au calendrier et aux contacts Outlook.Microsoft recommends using Microsoft Graph to access Outlook mail, calendar, and contacts. Vous devez utiliser les API Outlook directement (via https://outlook.office.com/api) uniquement si vous avez besoin d’une fonctionnalité qui n’est pas disponible sur les points de terminaison de Graph.You should use the Outlook APIs directly (via https://outlook.office.com/api) only if you require a feature that is not available on the Graph endpoints.

Avec les informations contenues dans ce guide, vous pouvez implémenter ceci dans tout langage ou sur toute plateforme capable d’envoyer des requêtes HTTP.With the information in this guide, you can implement this in any language or platform capable of sending HTTP requests.

Utilisation d’OAuth2 pour s’authentifierUse OAuth2 to authenticate

Pour appeler l’API de messagerie, l’application nécessite un jeton d’accès d’Azure Active Directory. Pour ce faire, l’application implémente l’un des flux OAuth pris en charge dans le point de terminaison Azure v2.0. Toutefois, avant que cela fonctionne, l’application doit être inscrite auprès du portail d’inscription d’application.In order to call the Mail API, the app requires an access token from Azure Active Directory. In order to do that, the app implements one of the supported OAuth flows in the Azure v2.0 endpoint. However, before this will work, the app must be registered in the Application Registration Portal.

Inscription d’une applicationRegistering an app

Notes

Ce scénario d'exemple simple utilisera un flux de code d'autorisation de base.This simple example scenario will use a basic authorization code flow. Pour plus de détails sur les options disponibles dans ce flux, voir Flux de code d'autorisation.For full details on the available options in this flow, see authorization code flow. Les étapes du flux implicite ou du flux d’informations d’identification client peuvent être légèrement différentes.The steps for the implicit flow or client credentials flow will be slightly different.

Vous pouvez utiliser le Centre d’administration Azure Active Directory pour inscrire rapidement une application qui utilise des API Outlook dans Microsoft Graph.You can use the Azure Active Directory admin center to quickly register an app that uses any of the Outlook APIs in Microsoft Graph.

Important

Configuration requise de compteAccount requirements

Pour utiliser le Centre d’administration Azure Active Directory, vous avez besoin d’un compte professionnel ou scolaire Office 365, ou d’un compte Microsoft.In order to use the Azure Active Directory admin center, you need either an Office 365 work or school account, or a Microsoft account. Si vous n’avez pas un de ces comptes, les options suivantes sont possibles :If you don't have either of these, you have a number of options:

  • Vous inscrire à un nouveau compte Microsoft ici.Sign up for a new Microsoft account here.
  • Vous pouvez obtenir un abonnement Office 365 de deux manières différentes :You can obtain an Office 365 subscription in a couple of different ways:

Une fois l’application inscrite, vous obtenez un ID client et une clé secrète.Once you register the app, you will have a client ID and secret. Ces informations sont utilisées dans le flux de code d’autorisation.These are used in the authorization code flow.

Obtention d’un code d’autorisationGetting an authorization code

La première étape dans le flux de code d’autorisation consiste à obtenir un code d’autorisation. Ce code est renvoyé à l’application par Azure lorsque l’utilisateur se connecte et accepte le niveau d’accès requis par l’application.The first step in the authorization code flow is to get an authorization code. That code is returned to the app by Azure when the user logs on and consents to the level of access the app requires.

Tout d’abord, l’application crée une URL de connexion pour l’utilisateur. Cette URL doit être ouverte dans un navigateur pour que l’utilisateur puisse se connecter et fournir son consentement.First the app constructs a logon URL for the user. This URL must be opened in a browser so that the user can login and provide consent.

L’URL de base pour la connexion ressemble à ce qui suit :The base URL for logon looks like:

https://login.microsoftonline.com/common/oauth2/v2.0/authorize

L’application ajoute des paramètres de requête à cette URL de base pour indiquer à Azure quelle application demande la connexion et quelles autorisations elle requiert.The app appends query parameters to this base URL to let Azure know what app is requesting the logon, and what permissions it is requesting.

  • client_id : ID client généré en inscrivant l’application. Il permet à Azure de savoir quelle application demande la connexion.client_id: the client ID generated by registering the app. This lets Azure know which app is requesting the logon.
  • redirect_uri : emplacement vers lequel Azure redirige l’utilisateur une fois qu’il a accordé son consentement à l’application. Cette valeur doit correspondre à la valeur de l’URI de redirection utilisé lors de l’inscription de l’application.redirect_uri: the location that Azure will redirect to once the user has granted consent to the app. This value must correspond to the value of Redirect URI used when registering the app.
  • response_type : type de réponse attendu par l’application. Pour le flux d’octroi d’autorisation, cet élément doit toujours avoir la valeur code.response_type: the type of response the app is expecting. For the Authorization Grant Flow, this should always be code.
  • scope : liste des étendues d’accès délimitées par des espaces requise par votre application.scope: a space-delimited list of access scopes that your app requires. Pour obtenir la liste complète des étendues d’Outlook dans Microsoft Graph, voir Étendues d’autorisation Microsoft Graph.For a full list of Outlook scopes in Microsoft Graph, see Microsoft Graph permission scopes.

Par exemple, une application nécessitant un accès en lecture aux courriers électroniques placerait tous ces éléments ensemble pour générer une URL de demande comme suit :For example, an application that requires read access to mail would put all of those together to generate a request URL like the following:

Demande de code d’autorisationAuthorization code request

GET https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=<CLIENT ID>&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F&response_type=code&scope=openid+Mail.Read

L’utilisateur voit apparaître un écran de connexion qui affiche le nom de l’application. Une fois connecté, si c’est la première fois qu’il utilise l’application, l’utilisateur voit apparaître la liste des autorisations requises par l’application. Il est invité à l’autoriser ou à la refuser. En supposant que l’accès requis soit autorisé, le navigateur sera redirigé vers l’URI de redirection spécifié dans la demande initiale.The user will be presented with a sign in screen that displays the name of the app. Once they sign in, if it is their first time using the app, the user will be presented with a list of the app permissions the app requires and asked to allow or deny. Assuming they allow the required access, the browser will be redirected to the redirect URI specified in the initial request.

Demande de redirection après connexionRedirect request after successful sign in

GET  HTTP/1.1 302 Found
Location: http://localhost/myapp/?code= AwABAAAA...cZZ6IgAA&session_state=7B29111D-C220-4263-99AB-6F6E135D75EF&state=D79E5777-702E-4260-9A62-37F75FF22CCE

La valeur du paramètre de requête code dans l’URL est le code d’autorisation. L’étape suivante consiste à échanger ce code avec un jeton d’accès.The value of the code query parameter in the URL is the authorization code. The next step is to exchange that code for an access token.

Obtention d’un jeton d’accèsGetting an access token

Pour obtenir un jeton d’accès, l’application publie des paramètres encodés dans l’URL de demande de jeton, qui se présente toujours comme suit :To get an access token, the app posts form-encoded parameters to the token request URL, which is always:

https://login.microsoftonline.com/common/oauth2/v2.0/token

L’application inclut les paramètres suivants.The app includes the following parameters.

  • client_id : ID client généré en inscrivant l’application.client_id: the client ID generated by registering the app.
  • client_secret : clé secrète client générée en inscrivant l’application.client_secret: the client secret generated by registering the app.
  • code : code d’autorisation obtenu à l’étape précédente.code: the authorization code obtained in the prior step.
  • redirect_uri : cette valeur doit être identique à la valeur utilisée dans la demande de code d’autorisation.redirect_uri: this value must be the same as the value used in the authorization code request.
  • grant_type : type d’octroi utilisé par l’application. Pour le flux d’octroi d’autorisation, cet élément doit toujours avoir la valeur authorization_code.grant_type: the type of grant the app is using. For the Authorization Grant Flow, this should always be authorization_code.

Ces paramètres sont encodés dans le type de contenu application/x-www-form-urlencoded et envoyés à l’URL de demande de jeton.These parameters are encoded to the application/x-www-form-urlencoded content type and sent to the token request URL.

Demande de jeton d’accèsAccess token request

POST https://login.microsoftonline.com/common/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=AwABAAAA...cZZ6IgAA&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F&client_id=<CLIENT ID>&client_secret=<CLIENT SECRET>

Azure répond avec une charge JSON qui inclut le jeton d’accès.Azure responds with a JSON payload which includes the access token.

Réponse de jeton d’accèsAccess token response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "token_type":"Bearer",
  "expires_in":"3600",
  "access_token":"eyJ0eXAi...b66LoPVA",
  "scope":"Mail.Read",
}

Le jeton d’accès se trouve dans le champ access_token de la charge JSON. L’application utilise cette valeur pour définir l’en-tête Authorization lors de l’exécution d’appels REST à l’API.The access token is found in the access_token field of the JSON payload. The app uses this value to set the Authorization header when making REST calls to the API.

Appel de l’API de messagerieCalling the Mail API

Une fois que l’application a un jeton d’accès, elle peut appeler l’API de messagerie. La référence d’API de messagerie contient tous les détails. Étant donné que l’application récupère des messages, elle utilise une requête HTTP GET auprès de l’URL https://graph.microsoft.com/v1.0/me/mailfolders/inbox/messages. Cela permet de récupérer les messages dans la boîte de réception.Once the app has an access token, it's ready to call the Mail API. The Mail API Reference has all of the details. Since the app is retrieving messages, it will use an HTTP GET request to the https://graph.microsoft.com/v1.0/me/mailfolders/inbox/messages URL. This will retrieve messages from the inbox.

Amélioration de la requêteRefining the request

Les applications peuvent contrôler le comportement des requêtes GET à l’aide de paramètres de requête OData. Il est recommandé que les applications utilisent ces paramètres, afin de limiter le nombre de résultats renvoyés et les champs qui sont renvoyés pour chaque élément. Prenons un exemple.Apps can control the behavior of GET requests by using OData query parameters. It is recommended that apps use these parameters to limit the number of results that are returned and to limit the fields that are returned for each item. Let's look at an example.

Envisagez une application qui affiche les messages dans un tableau. Le tableau affiche uniquement l’objet, l’expéditeur, et la date et l’heure auxquelles le message a été reçu. Le tableau affiche un maximum de 25 lignes et doit être trié de manière à ce que le message reçu en dernier apparaisse en haut.Consider an app that displays messages in a table. The table only displays the subject, sender, and the date and time the message was received. The table displays a maximum of 25 rows, and should be sorted so that the most recently received message is at the top.

Pour ce faire, l’application utilise les paramètres de requête suivants :To achieve this, the app uses the following query parameters:

  • Le paramètre $select permet d’indiquer les champs subject, from et receivedDateTime uniquement.The $select parameter is used to specify only the subject, from, and receivedDateTime fields.
  • Le paramètre $top est utilisé pour spécifier un maximum de 25 éléments.The $top parameter is used to specify a maximum of 25 items.
  • Le paramètre $orderby permet de trier les résultats en fonction du champ receivedDateTime.The $orderby parameter is used to sort the results by the receivedDateTime field.

Cela entraîne la demande suivante.This results in the following request.

Demande d’API de messagerie pour les messages dans la boîte de réceptionMail API request for messages in the inbox

GET https://graph.microsoft.com/v1.0/me/mailfolders/inbox/messages?$select=subject,from,receivedDateTime&$top=25&$orderby=receivedDateTime%20DESC

Accept: application/json
Authorization: Bearer eyJ0eXAi...b66LoPVA

Réponse d’API de messagerieMail API Response

HTTP/1.1 200 OK
Content-Type: application/json;odata.metadata=minimal;odata.streaming=true;IEEE754Compatible=false;charset=utf-8

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(...)/mailfolders('inbox')messages(subject,from,receivedDateTime)",
  "value": [
    {
      "@odata.etag": "W/\"CQAAABYAAAAoPBSqxXQOT6tuE0pxCMrtAABufX4i\"",
      "id": "AAMkADRmMDExYzhjLWYyNGMtNDZmMC1iZDU4LTRkMjk4YTdjMjU5OABGAAAAAABp4MZ-5xP3TJnNAPmjsRslBwAoPBSqxXQOT6tuE0pxCMrtAAAAAAEMAAAoPBSqxXQOT6tuE0pxCMrtAABufW1UAAA=",
      "subject": "Ruby on Rails tutorial",
      "from": {
        "emailAddress": {
          "address": "jason@contoso.onmicrosoft.com",
          "name": "Jason Johnston"
        }
      },
      "receivedDateTime": "2015-01-29T20:44:53Z"
    },
    {
      "@odata.etag": "W/\"CQAAABYAAAAoPBSqxXQOT6tuE0pxCMrtAABSzmz4\"",
      "id": "AAMkADRmMDExYzhjLWYyNGMtNDZmMC1iZDU4LTRkMjk4YTdjMjU5OABGAAAAAABp4MZ-5xP3TJnNAPmjsRslBwAoPBSqxXQOT6tuE0pxCMrtAAAAAAEMAAAoPBSqxXQOT6tuE0pxCMrtAABMirSeAAA=",
      "subject": "Trip Information",
      "from": {
        "emailAddress": {
          "address": "jason@contoso.onmicrosoft.com",
          "name": "Jason Johnston"
        }
      },
      "receivedDateTime": "2014-12-09T21:55:41Z"
    },
    {
      "@odata.etag": "W/\"CQAAABYAAAAoPBSqxXQOT6tuE0pxCMrtAABzxiLG\"",
      "id": "AAMkADRmMDExYzhjLWYyNGMtNDZmMC1iZDU4LTRkMjk4YTdjMjU5OABGAAAAAABp4MZ-5xP3TJnNAPmjsRslBwAoPBSqxXQOT6tuE0pxCMrtAAAAAAEMAAAoPBSqxXQOT6tuE0pxCMrtAABAblZoAAA=",
      "subject": "Multiple attachments",
      "from": {
        "emailAddress": {
          "address": "jason@contoso.onmicrosoft.com",
          "name": "Jason Johnston"
        }
      },
      "receivedDateTime": "2014-11-19T20:35:59Z"
    },
    {
      "@odata.etag": "W/\"CQAAABYAAAAoPBSqxXQOT6tuE0pxCMrtAAA9yBBa\"",
      "id": "AAMkADRmMDExYzhjLWYyNGMtNDZmMC1iZDU4LTRkMjk4YTdjMjU5OABGAAAAAABp4MZ-5xP3TJnNAPmjsRslBwAoPBSqxXQOT6tuE0pxCMrtAAAAAAEMAAAoPBSqxXQOT6tuE0pxCMrtAAA9x_8YAAA=",
      "subject": "Attachments",
      "from": {
        "emailAddress": {
          "address": "jason@contoso.onmicrosoft.com",
          "name": "Jason Johnston"
        }
      },
      "receivedDateTime": "2014-11-18T20:38:43Z"
    }
  ]
}

Maintenant que vous avez vu comment appeler l’API de messagerie, vous pouvez utiliser la référence d’API pour créer tout autre type d’appel que votre application doit effectuer. Toutefois, gardez à l’esprit que votre application doit disposer des autorisations appropriées configurées lors de l’inscription de l’application pour les appels qu’elle effectue.Now that you've seen how to make calls to the Mail API, you can use the API reference to construct any other kinds of calls your app needs to make. However, bear in mind that your app needs to have the appropriate permissions configured on the app registration for the calls it makes.