Vue d’ensemble de l’utilisation d’API REST Outlook

  • Article

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.

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.

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.

Ce didacticiel utilise Microsoft Graph pour appeler l’API de messagerie. Microsoft recommande d’utiliser Microsoft Graph pour accéder à la messagerie, au calendrier et aux contacts Outlook. 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.

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.

Utilisation d’OAuth2 pour s’authentifier

Afin d’appeler l’API de messagerie, l’application nécessite un jeton d’accès de la Plateforme d’identités Microsoft. Utilisez l’un des flux OAuth 2.0 pris en charge pour obtenir un jeton d’accès.

Appel de l’API de messagerie

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.

Amélioration de la requête

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.

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.

Pour ce faire, l’application utilise les paramètres de requête suivants :

  • Le paramètre $select permet d’indiquer les champs subject, from et receivedDateTime uniquement.
  • Le paramètre $top est utilisé pour spécifier un maximum de 25 éléments.
  • Le paramètre $orderby permet de trier les résultats en fonction du champ receivedDateTime.

Cela entraîne la demande suivante.

Demande d’API de messagerie pour les messages dans la boîte de réception

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 messagerie

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.