Partager via

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.

Importante

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.

Bien que les compléments puissent utiliser le service REST jusqu’en 2025, nous vous encourageons vivement à migrer vos compléments pour utiliser Microsoft Graph. Pour obtenir des conseils, consultez Comparer les points de terminaison de l’API REST Microsoft Graph et Outlook.

Obtenir un jeton d’accès

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

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.

Votre complément peut déterminer dans quel client Outlook il est chargé en consultant la propriété Office.context.mailbox.diagnostics.hostName.

Exemple

function getItemRestId() {
  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.

Exemple

// Example: https://outlook.office.com
const restHost = Office.context.mailbox.restUrl;

Appel de l’API

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.

Importante

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.

function getCurrentItem(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.