Verwenden von Outlook-REST-APIs in Outlook-Add-Ins

Der Office.context.mailbox.item-Namespace ermöglicht den Zugriff auf viele allgemeinen Felder von Nachrichten und Terminen. In einigen Szenarien muss ein Add-In jedoch möglicherweise auf Daten zugreifen, die nicht vom Namespace verfügbar gemacht werden. Das Add-In basiert möglicherweise auf benutzerdefinierten Eigenschaften außerhalb der App oder muss im Postfach des Benutzers nach Nachrichten von einem bestimmten Absender suchen. In diesen Fällen wird empfohlen, die Outlook REST APIs-Methode zum Abrufen der Informationen zu verwenden.

Wichtig

Outlook REST v2.0 und Beta-Endpunkte veraltet

Die Outlook REST v2.0- und Beta-Endpunkte sind am 31. März 2024 vollständig veraltet. Privat veröffentlichte und von AppSource gehostete Add-Ins können den REST-Dienst jedoch verwenden, bis der erweiterte Support für Outlook 2019 am 14. Oktober 2025 endet. Datenverkehr von diesen Add-Ins wird automatisch als Ausnahme identifiziert. Diese Ausnahme gilt auch für neue Add-Ins, die nach dem Außerbetriebnahmedatum entwickelt wurden.

Obwohl Add-Ins den REST-Dienst bis 2025 verwenden können, empfehlen wir Ihnen dringend, Ihre Add-Ins zur Verwendung von Microsoft Graph zu migrieren. Eine Anleitung finden Sie unter Vergleichen von Microsoft Graph- und Outlook-REST-API-Endpunkten.

Abrufen eines Zugriffstokens

Die Outlook-REST-APIs erfordern ein Bearertoken im Authorization-Header. In der Regel verwenden Sie OAuth2-Flüsse zum Abrufen eines Tokens. Add-Ins können jedoch ein Token abrufen, ohne OAuth2 zu implementieren, indem sie die neue Office.context.mailbox.getCallbackTokenAsync-Methode verwenden, die im Postfachanforderungssatz 1.5 eingeführt wurde.

Durch Festlegen der isRest-Option auf true können Sie ein Token anfordern, das mit den REST-APIs kompatibel ist.

Add-In-Berechtigungen und Tokenumfang

Es ist wichtig, die Zugriffsebene zu berücksichtigen, die das Add-In über die REST-APIs benötigt. In den meisten Fällen stellt das über getCallbackTokenAsync zurückgegebene Token nur schreibgeschützten Zugriff auf das aktuelle Element bereit. Dies gilt auch, wenn Ihr Add-In die Berechtigungsstufe für Das Lesen/Schreiben von Elementen im Manifest angibt.

Wenn Ihr Add-In Schreibzugriff auf das aktuelle Element oder andere Elemente im Postfach des Benutzers benötigt, muss Ihr Add-In die Berechtigung Postfach lesen/schreiben angeben. level in seinem Manifest. In diesem Fall enthält das zurückgegebene Token Lese-/Schreibzugriff auf Nachrichten, Ereignisse und Kontakte des Benutzers.

Beispiel

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.
  }
});

Abrufen der Element-ID

Um das aktuelle Element über REST abzurufen, benötigt das Add-In die ordnungsgemäß für REST formatierte Element-ID. Diese wird über die Office.context.mailbox.item.itemId-Eigenschaft abgerufen, es sind jedoch einige Überprüfungen erforderlich, um sicherzustellen, dass es sich dabei um eine für REST formatierte ID handelt.

• In Outlook auf mobilen Geräten ist der von Office.context.mailbox.item.itemId zurückgegebene Wert eine REST-formatierte ID und kann unverändert verwendet werden.
• In anderen Outlook-Clients ist der von Office.context.mailbox.item.itemId zurückgegebene Wert eine ID im EWS-Format und muss erst mithilfe der Office.context.mailbox.convertToRestId-Methode konvertiert werden.
• Beachten Sie, dass Sie auch die Anlagen-ID in eine REST-formatierte ID konvertieren müssen, um diese zu verwenden. Die IDs müssen konvertiert werden, weil EWS-IDs sichere Nicht-URL-Werte enthalten können, die Probleme für REST verursachen.

Das Add-In kann bestimmen, welcher Outlook-Client geladen wird, indem die Office.context.mailbox.diagnostics.hostName-Eigenschaft überprüft wird.

Beispiel

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
    );
  }
}

Abrufen der REST-API-URL

Die letzte Angaben, die das Add-In zum Aufrufen der REST-API benötigt, ist der Hostname, der zum Senden von API-Anforderungen verwendet werden soll. Diese Informationen sind in der Office.context.mailbox.restUrl-Eigenschaft enthalten.

Beispiel

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

Aufrufen der API

Sobald das Add-In über das Zugriffstoken, die Element-ID und die REST-API-URL verfügt, kann es diese Informationen entweder an einen Back-End-Dienst übergeben, der die REST-API aufruft, oder sie direkt mithilfe von AJAX verwenden. Im folgenden Beispiel wird die Outlook-E-Mail-REST-API aufgerufen, um die aktuelle Nachricht abzurufen.

Wichtig

Bei lokalen Exchange-Bereitstellungen schlagen clientseitige Anforderungen mit AJAX oder ähnlichen Bibliotheken fehl, da CORS in diesem Serversetup nicht unterstützt wird.

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.
  });
}

Siehe auch

• Ein Beispiel, in dem die REST-APIs im Outlook-Add-In aufgerufen werden, finden Sie unter command-demo auf GitHub.
• Outlook-REST-APIs sind auch über den Microsoft Graph-Endpunkt verfügbar, aber es gibt einige wesentliche Unterschiede, darunter, wie Ihr Add-In ein Zugriffstoken erhält. Weitere Informationen finden Sie unter Outlook-REST API über Microsoft Graph.