Utiliser l’API REST de Outlook (bêta)

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

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 ajoutées à une version ultérieure plus tard.

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 :

• Utilisez le point de terminaison d'authentification Azure AD version 2
• Utilisez Azure Active Directory et OAuth

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 convergeant est l’approche la plus récente et se compose des éléments suivants :

• Portail d’inscription des applications Microsoft
• étendues d'autorisation version 2
• points de terminaison d’authentification version 2
  • https://login.microsoftonline.com/common/oauth2/v2.0/authorize
  • https://login.microsoftonline.com/common/oauth2/v2.0/token
• bibliothèques ADAL version 2

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.

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 obsolète 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 ces applications basées sur l’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.

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.

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.

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.

Remarques pour les développeurs en Chine

• |||UNTRANSLATED_CONTENT_START|||If you are developing apps for Office 365 in China, you should continue to use the API endpoints of Office 365 for China.|||UNTRANSLATED_CONTENT_END|||

• Si vous créez des applications pour Outlook.com en Chine, essayez le point de terminaison d’authentification version 2et utilisez le nouveau point de terminaison REST Outlook suivant : https://outlook.office.com/api/{version}/{user_context}.

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 :

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

• version 2.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.

• version 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 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}.

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 :

• iOS
• Android
• JavaScript
• .NET

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 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 à passer à https://outlook.office.com/api/v1.0 d’ici au 15 octobre 2015. La version 1.0 était 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 :

• Référence de l'API courrier
• Référence de l'API calendrier
• Référence de l'API contacts
• API REST de tâches
• Référence de ressource pour les API REST Courrier, Calendrier, Contacts et Tâche
• Référence de l’API REST contacts
• Référence de l'API extensions des données
• Référence de l'API Propriétés Étendues
• Référence de l’API REST de notifications Push
• Référence de l'API REST de notifications de diffusions en continu (préversion)
• Référence de l’API REST de photo utilisateur
• Requêtes REST Outlook en lot