Utilisation des API REST Outlook d’un complément Outlook

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.

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.

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://video2.skills-academy.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.