Partager via

Utiliser l’API REST Outlook (version 2.0)

  • Article

S’applique à : Exchange Online | Office 365 | Hotmail.com | Live.com | MSN.com | Outlook.com | Passport.com

Notes

Utilisez Microsoft Graph pour créer des scénarios plus riches pour les services Microsoft 365, y compris Outlook. Découvrez comment passer à l’API REST Outlook basée sur Microsoft Graph.

L'API REST Outlook inclut les sous-ensembles suivants pour autoriser l'accès aux données de boîte aux lettres des utilisateurs d'Office 365, Hotmail.com, Live.com, MSN.com, Outlook.com et Passport.com.

La table ci-dessous répertorie la première version dans laquelle la fonctionnalité de base de chaque sous-ensemble a été rendue disponible. Remarque : Au sein d’un sous-ensemble, de nouvelles fonctionnalités et API peuvent être ensuite ajoutées à une version ultérieure.

Sous-ensemble d’API Versions disponibles
Grouper plusieurs appels d’API v2.0, bêta
API de calendrier v2.0, v 1.0, bêta
API de contacts v2.0, v 1.0, bêta
API des extensions de données v2.0, bêta
API de propriétés étendues v2.0, bêta
API de messagerie v2.0, v 1.0, bêta
API de notifications Push v2.0, bêta
API des Notifications Streaming (préversion) bêta
API de contacts bêta
API des tâches v2.0, bêta
API de photo utilisateur v2.0, bêta

Notes

Le reste de cet article décrit des informations communes applicables à tous les sous-ensembles de l’API REST Outlook. Par souci de simplicité de la référence, le reste de cet article utilise Outlook.com pour inclure les comptes dans les domaines Hotmail.com, Live.com, MSN.com, Outlook.com et Passport.com.

Inscription et authentification de votre application

Pour utiliser l'API REST Outlook pour accéder aux données de la boîte aux lettres d'un utilisateur, votre application doit gérer l'inscription et l'autorisation de l'utilisateur :

  1. Commencez par inscrire votre application pour accéder à l'API REST Outlook. Vous pouvez ensuite implémenter les appels d'API dans votre application.

  2. Lors de l'exécution, obtenez l'autorisation de l'utilisateur et faites des requêtes API REST pour accéder à la boîte aux lettres de l'utilisateur.

Il existe actuellement deux approches pour gérer l'inscription des applications et l'autorisation de l'utilisateur :

Point de terminaison d’authentification Azure AD v2

Le point de terminaison d'authentification Azure AD version 2 simplifie la génération d'une application compatible avec les comptes Microsoft personnels et organisationnels. Il permet aux utilisateurs d'un compte de travail, d'école et personnel de se connecter avec un simple bouton.

Ce modèle de programmation convergé est l’approche la plus récente et se compose des éléments suivants :

Cette approche vous offre une expérience d'inscription d'application et d'autorisation utilisateur sans faute pour obtenir les jetons appropriés afin d'accéder aux données de boîte aux lettres des utilisateurs sur Office 365 et/ou Outlook.com. Si vous développez une application pour Outlook.com, vous devez utiliser cette approche.

Au lieu de demander des autorisations lors de l'inscription de l'application, le point de terminaison d'authentification version 2 vous permet d'inviter dynamiquement et demander les autorisations nécessaires en fonction des actions de l'utilisateur correspondantes au moment de l'exécution.

Ce modèle de programmation convergé est constitué de plusieurs composants, donc si vous utilisez un composant, vous devez également utiliser les autres.

Pour en savoir plus, voir Exemples de prise en main, et Authentification des API Office 365 et Outlook.com à l’aide du point de terminaison d’authentification v2.

Important

Alors que vous créez ou mettez à jour une application, assurez-vous que votre application peut gérer les boîtes aux lettres Outlook.com qui ont été activées et auxquelles vous pouvez accéder à l'aide de l'API REST Outlook, ainsi que les boîtes aux lettres en attente d'activation. En savoir plus sur tester et gérer de tels scénarios Outlook.com.

Inscription et authentification à l'aide d'Azure AD et OAuth

Il s'agit d'une approche antérieure pour accéder aux données de boîte aux lettres sur Office 365 uniquement. Si vous envisagez d'accéder à des données sur Outlook.com ou de créer une nouvelle application pour Office 365, utilisez le point de terminaison d'authentification version2 à la place.

Pour l'instant, pour accéder aux données de la boîte aux lettres Office 365, vous pouvez continuer à enregistrer une application dans Azure AD, en spécifiant les autorisations à la portée appropriée requise par votre application. Au moment de l'exécution, votre application peut continuer à utiliser Azure AD et OAuth pour authentifier les requêtes d'application. Vous pouvez trouver des détails à Concepts d'authentification de l'application Office 365. Vous devez avoir un plan de tracé de mise à niveau.

Avec cette approche, vous pouvez choisir d'accéder à l'API REST Outlook en l'appelant directement dans vos applications Office 365 ou en utilisant les bibliothèques client Office 365.

Tracé de mise à niveau

Le point de terminaison d'authentification version 2 a été mis à niveau de l'état de préversion à l'état général disponible (GA) pour les développeurs Outlook et Outlook.com.

Si vous disposez d'une application en production qui accède aux données de boîte aux lettres Office 365 ou si vous créez une nouvelle application pour Office 365 ou Outlook.com, prévoyez d'utiliser le point de terminaison d'authentification version 2 avec le dernier point de terminaison Outlook (https://outlook.office.com/, voir plus ci-dessous) pour tirer parti de l'écriture d'un seul jeu de code à la fois pour les utilisateurs organisationnels d'Office 365 et les utilisateurs personnels d'Outlook.com.

Si vous disposez d'une application en production qui utilise l'API Windows Live pour accéder aux données de boîte aux lettres Outlook.com, vous devez mettre à jour l'application pour qu'elle utilise le point de terminaison d'authentification version 2 et l'API REST Outlook. Puisque l’API Windows Live est déconseillée pour Outlook.com, et que les utilisateurs d’Outlook.com activent leurs boîtes aux lettres pour l’API REST Outlook, ces utilisateurs recevront des erreurs HTTP 404 lorsqu’ils tenteront d’exécuter ces applications basées sur l’API Windows Live.

En revanche, l’API REST Outlook vous offre de nouvelles opportunités—vous pouvez choisir parmi une liste de langages communs tels que Node, Python, Swift, Java, etc., écrire l’application une seule fois et capturer à la fois les utilisateurs Outlook.com et Office 365 sur le Web, sur iOS, sur Android ou sur Windows.

Notes

Si vous souhaitez que votre application en production continue d'accéder seulement aux données de la boîte aux lettres Outlook.com, vous pouvez continuer à utiliser les mêmes étendues Windows Live pour accéder à la plupart de l'API REST Outlook. Pour plus d’informations, consultez Utilisation des étendues Windows Live et de l’API REST Outlook pour accéder aux données de la boîte aux lettres Outlook.com.

Quelle que soit l'approche que vous utilisez pour l'inscription et l'autorisation utilisateur, ou si votre application cible Office 365 et les données de la boîte aux lettres Outlook.com, le dernier point de terminaison REST Outlook est en production et vous pouvez l'utiliser dans vos appels d'API REST quand vous voulez :

https://outlook.office.com/api/{version}/{user_context}

Le point de terminaison REST Outlook suivant continuera de fonctionner pendant un certain temps uniquement pour les données de boîte aux lettres Office 365 :

https://outlook.office365.com/api/{version}/{user_context}

En savoir plus sur les actions REST prises en charge, les points de terminaison et les versions ci-dessous.

Important

  • L’autorisation de base n’est plus prise en charge par le point de terminaison de l’API REST Outlook https://outlook.office.com. Utilisez le point de terminaison d'authentification version 2 ou Azure AD pour effectuer l'autorisation et l'authentification pour une application qui utilise le nouveau point de terminaison de l'API REST Outlook.
  • Pour un niveau de performance optimal lors de l'utilisation du nouveau point de terminaison REST Outlook, ajoutez une x-AnchorMailbox en-tête pour chaque requête et définissez-la à l'adresse e-mail de l'utilisateur. Par exemple : x-AnchorMailbox:john@contoso.com
  • Étant donné que l'activation des boîtes aux lettres sur Outlook.com pour l'API REST Outlook se produit sur une période de temps, votre compte Outlook.com existant peut prendre un certain temps pour être activé. Pour tester l’accès de votre application aux données sur des boîtes aux lettres Outlook.com qui ont déjà été activées, vous pouvez demander un nouveau compte Outlook.com de préversion actif pour développeur en envoyant un e-mail à outlookdev@microsoft.com.
  • Si votre application accède aux données de la boîte aux lettres Outlook.com, elle doit gérer les scénarios dans lesquels la boîte aux lettres de l'utilisateur n'a pas encore été activée pour l'API REST Outlook. Dans de telles situations, lorsque vous effectuez une requête REST, vous obtenez une erreur comme ce qui suit :
    • Erreur HTTP : 404
    • Code d'erreur : MailboxNotEnabledForRESTAPI ou MailboxNotSupportedForRESTAPI
    • Message d'erreur : « L'API REST n'est pas encore prise en charge pour cette boîte aux lettres ».
  • Pour les exemples de code qui utilisent le point de terminaison d’authentification v2, voir dev.outlook.com.

Utilisation des étendues Windows Live et de l’API REST Outlook pour accéder aux données de boîte aux lettres Outlook.com

Si votre application en production pour Outlook.com utilise les étendues Windows Live et que vous n'avez pas l'intention de cibler les données de boîte aux lettres Office 365, vous pouvez continuer à utiliser ces étendues Windows Live avec la majeure partie de l'API REST Outlook. Le tableau ci-dessous montre comment les étendues Windows Live sont mappées aux étendues de l'API REST Outlook. Notez qu'il n'y a pas un mappage direct d'étendue Windows Live pour Mail.Read. Votre application peut utiliser wl.imap pour accéder aux opérations de l'API REST Outlook nécessitant Mail.Read.

Étendues Windows Live Étendues de l’API REST Outlook
wl.basic User.Read, Contacts.Read
wl.calendars Calendars.Read
wl.calendars_update Calendars.ReadWrite
wl.contacts_create Contacts.ReadWrite
wl.contacts_calendars Calendars.Read
wl.emails User.Read
wl.events_create Calendars.ReadWrite
wl.imap Mail.ReadWrite, Mail.Send

Actions REST et points de terminaison pris en charge

Pour interagir avec l'API REST Outlook, vous envoyez des requêtes HTTP qui utilisent une méthode prise en charge : GET, POST, PATCH ou DELETE. Les corps de requête POST et PATCH et les réponses du serveur sont envoyés dans les charges utiles JSON.

Les noms de ressources de chemin d'accès de l'URL et les paramètres de requête sont insensibles à la casse. Toutefois, les valeurs que vous attribuez, les identifiants d’entité et les autres valeurs codées en base64 sont sensibles à la casse.

Toutes les requêtes d'API REST utilisent le nouveau format d'URL racine suivant :

https://outlook.office.com/api/{version}/{user_context}

Avec l'autorisation utilisateur appropriée, l'API REST dans cette URL racine permet d'accéder aux données de la boîte aux lettres sur Office 365 et Outlook.com. Le reste de cet article décrit l’API REST dans ce point de terminaison.

Si vous avez du code qui utilise l’URL racine préexistante https://outlook.office365.com/api/{version}/{user_context}, votre code continuera à fonctionner pendant un certain temps sur Office 365, mais vous devriez envisager de passer à la nouvelle URL racine.

Important

Pour un niveau de performance optimal, lorsque vous effectuez une requête REST à l’aide de la nouvelle URL racine, ajoutez un en-tête x-AnchorMailbox et définissez-le à l’adresse e-mail de l’utilisateur. Gérez également le cas où la boîte aux lettres d’un utilisateur Outlook.com n’a pas encore été activée pour l’API REST d’Outlook. Recherchez les codes d’erreur MailboxNotEnabledForRESTAPI et MailboxNotSupportedForRESTAPI. Plus d’information ici.

Remarques pour les développeurs en Chine

Versions API prises en charge

{version} représente la version de l'API REST Outlook dans l'URL racine spécifiée. Vous pouvez spécifier l’une des valeurs suivantes :

  • v1.0. Ceci est la plus ancienne version en statut de disponibilité générale (GA) et peut être utilisée dans du code de production. Voici un exemple d’URL : http://outlook.office.com/api/v1.0/me/events.

  • v2.0. Cette version est également en statut GA et peut être utilisée dans du code de production. Voici un exemple d’URL : http://outlook.office.com/api/v2.0/me/events. Cette version inclut des modifications susceptibles de porter atteinte à la v1.0, ainsi que des ensembles d’API supplémentaires qui ont atteint leur maturité et ont depuis été promus de préversion à GA.

  • bêta. Il s’agit d’une préversion qui ne doit donc pas être utilisée dans du code en production. Voici un exemple d’URL : http://outlook.office.com/api/beta/me/events. Cette version inclut les dernières API en GA, ainsi que des ensembles d'API en préversion dont l'état est susceptible de changer avant leur finalisation.

La majorité des opérations REST dans l'API REST Outlook est prise en charge et se comporte de la manière décrite dans les versions répertoriées ci-dessus.

Utilisateur cible

À l'exception de l'API REST photo utilisateur, {user_context} est l'utilisateur actuellement connecté, car les requêtes d'API REST Outlook sont toujours exécutées au nom de l'utilisateur actuel.

Pour l'API REST photo utilisateur, {user_context} peut être l'utilisateur connecté ou un utilisateur spécifié par une ID utilisateur.

Indépendamment de l'ensemble d'API REST Outlook, vous pouvez spécifier dans la {user_context} requête REST de l'une des façons suivantes :

  • Avec le raccourci me : /api/{version}/me. L'URL racine devient https://outlook.office.com/api/{version}/me.

  • Avec le format users/{upn} pour transmettre le nom UPN ou une adresse de serveur mandataire de l'utilisateur connecté, par exemple : /api/beta/users/sadie@contoso.com. Dans cet exemple, l’URL racine deviendrait https://outlook.office.com/api/beta/users/sadie@contoso.com.

  • Avec le format users/{AAD_userId@AAD_tenandId}, en utilisant l’ID d’utilisateur et l’ID du client dans Azure Active Directory. Par exemple, users/ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77 l’URL racine devient https://outlook.office.com/api/beta/users/ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77.

L’utilisation de l’une des options est une question de préférence.

Dans les réponses du serveur, le contexte utilisateur est identifié dans ce format : users/{AAD_userId@AAD_tenandId}.

Accéder à un élément dans une collection

L'API REST Outlook prend en charge deux façons de spécifier un élément dans une collection d'entités. Elles sont évalués de manière identique, donc l'utilisation est une question de préférence.

  • Dans le segment d'URL après la collecte, par exemple : /api/{version}/me/events/AAMkAGI3...

  • Entre parenthèses comme une chaîne entre guillemets, par exemple : /api/{version}/me/events('AAMkAGI3...')

Utilisation d’une bibliothèque client pour accéder à l’API REST Outlook

Les bibliothèques client de l’API Office 365 simplifient l’interaction avec l’API REST :

Elles aident à gérer les jetons d'authentification et simplifient le code nécessaire pour interroger et consommer des données sur Office 365.

Arrêt du point de terminaison d'une préversion antérieure

Si vous utilisez déjà https://outlook.office.com/api ou https://outlook.office365.com/api comme l'URL racine
pour accéder à l'API REST Outlook, cette dépréciation ne vous affecte pas. Continuez à lire si vous utilisez toujours le point de terminaison d'une préversion antérieure https://outlook.office365.com/ews/odata.

L’API REST Outlook est passée de sa préversion initiale à sa v1.0 de disponibilité générale (GA) en octobre 2014. Pour terminer cette transition, nous fermerons l’ancien point de terminaison de préversion https://outlook.office365.com/ews/odata le 15 octobre 2015.

Nous demandons à toutes les applications et à tous les services utilisant l’ancien point de terminaison https://outlook.office365.com/ews/odata de passer à https://outlook.office.com/api/v1.0 d’ici au 15 octobre 2015. La v1.0 était le point de terminaison de disponibilité générale (GA) minimal vers lequel se déplacer à cette date.

Vous pouvez également utiliser de préférence la v2.0 du point de terminaison en disponibilité générale (https://outlook.office.com/api/v2.0) ou la préversion du point de terminaison (https://outlook.office.com/api/beta) pour essayer les dernières API dans l’état de préversion. Gardez à l'esprit qu'en général, l'état de l'API en préversion peut changer avant la finalisation. Si vous les utilisez, soyez prêt à vérifier les fonctionnalités de votre application et à apporter les modifications appropriées. Lorsque les API en préversion sont finalisées, vous pouvez également accéder à ces améliorations dans un point de terminaison de GA.

Étapes suivantes

Passez à l'utilisation de l'API REST Outlook :