Table of contents
TOC
Réduire la table des matières
Développer la table des matières
Dernière mise à jour: 20/06/2018

Utilisation l'API REST Outlook

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

La version 1.0 de l’API REST Outlook est actuellement déconseillée. À partir du 1er novembre 2018, les applications ne pourront plus utiliser l’authentification de base avec la version 1.0 du point de terminaison REST (https://outlook.office.com/api/v1.0). D’ici le 1er novembre 2019, la version 1.0 du point de terminaison REST sera complètement désactivée et la documentation de la version 1.0 sera supprimée peu de temps après. Début de la migration de votre application pour l'utilisation de la version 1.0 de l'API REST Outlook dans la version 1.0 de Microsoft Graph. Voir plus de détails dans notre annonce.

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 de la fonctionnalité de base avec laquelle chaque sous-ensemble a été rendue disponible. Remarque : Au sein d'un sous-ensemble, de nouvelles fonctionnalités et API peuvent être ajoutées à une version ultérieure plus tard. Par exemple, l'API Calendrier a été introduite dans la version 1.0 et la fonctionnalité qui suggère les heures de réunion n'est actuellement disponible qu'en version bêta, mais pas en version 1.0 ou 2.0.

Sousensemble APIVersions disponibles
API du calendrierVersion 1.0 et versions ultérieures
API des contactsVersion 1.0 et versions ultérieures
API des extensions de donnéesVersion 2.0 et versions ultérieures
API des propriétés étenduesVersion 2.0 et versions ultérieures
API de courrierVersion 1.0 et versions ultérieures
API de notifications PushVersion 2.0 et versions ultérieures
API des Notifications Streaming (préversion)Bêta
API des Contacts (préversion)Bêta
API des tâchesVersion 2.0 et versions ultérieures
API de photo utilisateurVersion 2.0 et versions ultérieures
Traitement par lot de plusieurs API d'appelsVersion 2.0 et versions ultérieures

Remarque :

Le reste de cet article décrit des informations communes applicables à tous les sous-ensembles de l'API REST Outlook. Pour la simplicité de référence, le reste de cet article utilise « Outlook.com » pour inclure des 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 version 2

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 la dernière approche qui comprend ce qui suit :

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 sur comment démarrer, et Authentification des API Office 365 et Outlook.com à l'aide du point de terminaison d'authentification version 2.

Attention :

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, lorsque les utilisateurs Outlook.com activent leurs boîtes aux lettres pour l'API REST Outlook, ces utilisateurs reçoivent des erreurs HTTP 404 lorsqu'ils tentent d'exécuter cette application API Windows LivE. Par contre, l'API REST Outlook vous offre de nouvelles opportunités. En effet, 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.

Remarque :

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. Voir
Utilisation des étendues Windows Live et de l'API REST Outlook pour accéder aux données de boîte aux lettres Outlook.com pour plus d'informations.

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, points de terminaison et versions ci-dessous.

Attention :

  • 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 votre application sur des données dans une boîte aux lettres activée, vous pouvez vous inscrire à un nouveau compte Outlook.com ici. Tous les nouveaux comptes sont activés pour l'API REST immédiatement.
  • 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 version 2, 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.basicUser.Read, Contacts.Read
wl.calendarsCalendars.Read
wl.calendars_updateCalendars.ReadWrite
wl.contacts_createContacts.ReadWrite
wl.contacts_calendarsCalendars.Read
wl.emailsUser.Read
wl.events_createCalendars.ReadWrite
wl.imapMail.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.

Attention : Pour un niveau de performance optimal, lorsque vous effectuez une requête REST à l'aide de la nouvelle URL racine, ajoutez un x-AnchorMailbox en-tête et définissez-la sur 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 version la plus ancienne en statut de disponibilité générale (GA) est en cours de désapprobation. Voici un exemple d'URL : http://outlook.office.com/api/v1.0/me/events Faites migrer votre application pour utiliser Microsoft Graph. Voir plus de détails dans notre annonce.

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

  • beta. 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 deviendrait https://outlook.office.com/api/beta/users/ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77.

L'utilisation est une question de préférence.

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

  • 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 deviendrait https://outlook.office.com/api/beta/users/ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77.

L'utilisation est une question de préférence.

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

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

L'utilisation est une question de préférence. Dans les réponses le contexte utilisateur est identifié sous ce format : /api/v1.0/users('sadie@contoso.com')

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 facilitent l'interaction avec l'API REST : .NET, JavaScript, Android, et iOS. Ils 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 version 1.0 de disponibilité générale (GA) en octobre 2014. Pour terminer cette transition, nous fermons enfin l'ancien préversion du point de terminaison https://outlook.office365.com/ews/odata le 15 octobre 2015.

Nous avons besoin que toutes les applications et services utilisant l'ancien point de terminaison :

https://outlook.office365.com/ews/odata

soit déplacés vers :

https://outlook.office.com/api/v1.0

dès le 15 octobre 2015. La version 1.0 est le point de terminaison de disponibilité générale (GA) minimal vers lequel se déplacer à cette date.

Vous pouvez également utiliser la version 2.0 du point de terminaison de GA préféré (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 lpré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 :

© 2018 Microsoft