Utilisation des API REST Outlook d’un complément Outlook
Article
L’espace de noms Office.context.mailbox.item permet d’accéder à de nombreux champs communs pour les messages et les rendez-vous. Toutefois, dans certains scénarios, un complément peut avoir besoin d’accéder aux données qui ne sont pas exposées par l’espace de noms. Par exemple, le complément peut dépendre de propriétés personnalisées définies par une application extérieure ou avoir besoin rechercher dans la boîte aux lettres de l’utilisateur des messages provenant du même expéditeur. Dans ces scénarios, l’API REST Outlook est la méthode recommandée pour récupérer les informations.
Important
Dépréciation des points de terminaison REST v2.0 et bêta Outlook
Les points de terminaison REST v2.0 et bêta Outlook seront entièrement déconseillés le 31 mars 2024. Toutefois, les compléments publiés en privé et hébergés par AppSource peuvent utiliser le service REST jusqu’à la fin du support étendu pour Outlook 2019 le 14 octobre 2025. Le trafic de ces compléments est automatiquement identifié pour l’exemption. Cette exemption s’applique également aux nouveaux compléments développés après la date de mise hors service.
Les API REST Outlook nécessitent un jeton du porteur dans l’en-tête Authorization. En règle générale, les applications utilisent les flux OAuth2 pour extraire un jeton. Toutefois, les compléments peuvent récupérer un jeton sans implémenter OAuth2 à l’aide de la nouvelle méthode Office.context.mailbox.getCallbackTokenAsync introduite dans l’ensemble de conditions requises mailbox 1.5.
En définissant l’option isRest sur true, vous pouvez demander un jeton compatible avec les API REST.
Autorisations des compléments et étendue du jeton
Il est important de savoir de quel niveau d’accès votre complément aura besoin avec les API REST. Dans la plupart des cas, le jeton renvoyé par getCallbackTokenAsync fournit un accès en lecture seule à l’élément actif uniquement. Cela est vrai même si votre complément spécifie le niveau d’autorisation d’élément en lecture/écriture dans son manifeste.
Si votre complément nécessite un accès en écriture à l’élément actif ou à d’autres éléments de la boîte aux lettres de l’utilisateur, votre complément doit spécifier l’autorisation de boîte aux lettres en lecture/écriture.
dans son manifeste. Dans ce cas, le jeton renvoyé contiendra l’accès en lecture/écriture aux messages, événements et contacts de l’utilisateur.
Exemple
JavaScript
Office.context.mailbox.getCallbackTokenAsync({isRest: true}, function(result){
if (result.status === "succeeded") {
const accessToken = result.value;
// Use the access token.
getCurrentItem(accessToken);
} else {
// Handle the error.
}
});
Obtenir l’ID de l’élément
Pour extraire l’élément en cours via REST, votre complément aura besoin de l’ID de l’élément, correctement mis en forme pour REST. Cet ID peut être extrait de la propriété Office.context.mailbox.item.itemId, mais certaines vérifications doivent être apportées pour vous assurer qu’il s’agit d’un ID au format REST.
Dans Outlook sur les appareils mobiles, la valeur retournée par Office.context.mailbox.item.itemId est un ID au format REST et peut être utilisée telle quelle.
Dans d’autres clients Outlook, la valeur renvoyée par Office.context.mailbox.item.itemId est un ID au format EWS et doit être convertie à l’aide de la méthode Office.context.mailbox.convertToRestId.
Vous devez également convertir l’ID de pièce jointe en ID au format REST afin de l’utiliser. La raison pour laquelle les ID doivent être convertis est que les ID EWS peuvent contenir des valeurs approuvées autres que des URL, ce qui entraîne des problèmes pour REST.
functiongetItemRestId() {
if (Office.context.mailbox.diagnostics.hostName === 'OutlookIOS') {
// itemId is already REST-formatted.return Office.context.mailbox.item.itemId;
} else {
// Convert to an item ID for API v2.0.return Office.context.mailbox.convertToRestId(
Office.context.mailbox.item.itemId,
Office.MailboxEnums.RestVersion.v2_0
);
}
}
Obtenir l’URL de l’API REST
La dernière information dont votre complément a besoin pour appeler l’API REST est le nom d’hôte qu'il doit utiliser pour envoyer des demandes d’API. Cette information figure dans la propriété Office.context.mailbox.restUrl.
Une fois que votre complément a le jeton d’accès, l’ID de l’élément et l’URL de l’API REST, il peut transmettre ces informations à un service principal qui appelle l’API REST, ou l’appeler directement à l’aide d’AJAX. L’exemple suivant appelle l’API REST de courrier Outlook pour obtenir le message actuel.
Important
Pour les déploiements Exchange locaux, les demandes côté client utilisant AJAX ou des bibliothèques similaires échouent, car CORS n’est pas pris en charge dans cette configuration du serveur.
JavaScript
functiongetCurrentItem(accessToken) {
// Get the item's REST ID.const itemId = getItemRestId();
// Construct the REST URL to the current item.// Details for formatting the URL can be found at// https://learn.microsoft.com/previous-versions/office/office-365-api/api/version-2.0/mail-rest-operations#get-messages.const getMessageUrl = Office.context.mailbox.restUrl +
'/v2.0/me/messages/' + itemId;
$.ajax({
url: getMessageUrl,
dataType: 'json',
headers: { 'Authorization': 'Bearer ' + accessToken }
}).done(function(item){
// Message is passed in `item`.const subject = item.Subject;
...
}).fail(function(error){
// Handle error.
});
}
Voir aussi
Pour obtenir un exemple qui appelle les API REST à partir d’un complément Outlook, reportez-vous à command-demo sur GitHub.
Les API REST Outlook sont également disponibles via le point de terminaison Microsoft Graph, mais il existe quelques différences clés, notamment sur la façon dont votre complément obtient un jeton d’accès. Pour plus d’informations, reportez-vous à API REST Outlook via Microsoft Graph.
Collaborer avec nous sur GitHub
La source de ce contenu se trouve sur GitHub, où vous pouvez également créer et examiner les problèmes et les demandes de tirage. Pour plus d’informations, consultez notre guide du contributeur.
Commentaires sur Office Add-ins
Office Add-ins est un projet open source. Sélectionnez un lien pour fournir des commentaires :
Démontrez que vous avez les compétences nécessaires pour tirer le meilleur parti d’Outlook 2016 en obtenant une certification MoS (Microsoft Office Specialist).