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

Les points de terminaison de l’API REST Outlook v2.0 sont déconseillés. Pour le développement de nouveaux compléments, utilisez plutôt l’API REST de Microsoft Graph . Cet article décrit l’approche de l’API REST pour les compléments existants qui n’ont pas encore migré vers Microsoft Graph.

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 pour la boîte aux lettres 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. Ceci est vrai même si votre complément spécifie le niveau d’autorisation de lecture/écriture de l’élément 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, il doit spécifier le niveau d’autorisation lecture/écriture de la boîte aux lettres 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. Ceci est obtenu à partir de la itemId propriété (MessageRead, AppointmentRead), mais certaines vérifications doivent être effectué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://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

• Utiliser l’API REST Microsoft Graph à partir d’un complément Outlook
• Authentification et autorisation dans les compléments Outlook
• Activer l’authentification unique dans un complément Office à l’aide de l’authentification d’application imbriquée