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

Die Outlook-REST-API v2.0-Endpunkte sind veraltet. Verwenden Sie für die Entwicklung neuer Add-Ins stattdessen die Microsoft Graph-REST-API . In diesem Artikel wird der REST-API-Ansatz für vorhandene Add-Ins behandelt, die noch nicht zu Microsoft Graph migriert wurden.

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 Lese-/Schreibberechtigungsstufe des Postfachs in seinem Manifest angeben. 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. Dies wird von der itemId -Eigenschaft (MessageRead, AppointmentRead) abgerufen, aber es sollten einige Überprüfungen durchgeführt werden, um sicherzustellen, dass es sich um eine 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.

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

• Verwenden der Microsoft Graph-REST-API aus einem Outlook-Add-In
• Authentifizierung und Autorisierung in Outlook-Add-Ins
• Aktivieren des einmaligen Anmeldens in einem Office-Add-In mit geschachtelter App-Authentifizierung
• Beispiel für Add-In-Befehl