Verwenden von Outlook-REST-APIs in Outlook-Add-InsUse the Outlook REST APIs from an Outlook add-in

Der Namespace Office.context.mailbox.item ermöglicht den Zugriff auf viele der allgemeinen Felder von Nachrichten und Terminen. In einigen Fällen muss ein Add-In gegebenenfalls auf Daten zugreifen, die nicht vom Namespace zur Verfügung gestellt werden. Beispielsweise basiert das Add-In 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, zum Abrufen der Informationen die Outlook REST APIs-Methode zu verwenden.The Office.context.mailbox.item namespace provides access to many of the common fields of messages and appointments. However, in some scenarios an add-in may need to access data that is not exposed by the namespace. For example, the add-in may rely on custom properties set by an outside app, or it needs to search the user's mailbox for messages from the same sender. In these scenarios, the Outlook REST APIs is the recommended method to retrieve the information.

Hinweis

Sie können auf Outlook-REST-APIs auch über Microsoft Graph zugreifen, dabei gibt es aber einige wichtige Unterschiede. Weitere Informationen hierzu finden Sie unter Vergleich von Microsoft Graph und Outlook .You can also access Outlook REST APIs via Microsoft Graph but there are some key differences. For more details, please Compare Microsoft Graph and Outlook.

Abrufen eines ZugriffstokensGet an access token

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 allerdings ein Token ohne die Implementierung von OAuth2 abrufen, indem Sie die neue Office.context.mailbox.getCallbackTokenAsync-Methode verwenden, die in der Version des Postfachanforderungssatzes 1.5 hinzugefügt wurde.The Outlook REST APIs require a bearer token in the Authorization header. Typically apps use OAuth2 flows to retrieve a token. However, add-ins can retrieve a token without implementing OAuth2 by using the new Office.context.mailbox.getCallbackTokenAsync method introduced in the Mailbox requirement set 1.5.

Durch Festlegen der isRest-Option auf true können Sie ein Token anfordern, das mit den REST-APIs kompatibel ist.By setting the isRest option to true, you can request a token compatible with the REST APIs.

Add-In-Berechtigungen und TokenumfangAdd-in permissions and token scope

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 das Add-In die ReadWriteItem-Berechtigungsstufe im Manifest angibt.It is important to consider what level of access your add-in will need via the REST APIs. In most cases, the token returned by getCallbackTokenAsync will provide read-only access to the current item only. This is true even if your add-in specifies the ReadWriteItem permission level in its manifest.

Wenn das Add-In Schreibzugriff auf das aktuelle Element oder andere Elemente im Postfach des Benutzers benötigt, muss das Add-In die ReadWriteMailbox-Berechtigungsstufe im Manifest angeben. In diesem Fall enthält das zurückgegebene Token Lese-/Schreibzugriff auf Nachrichten, Ereignisse und Kontakte des Benutzers.If your add-in will require write access to the current item or other items in the user's mailbox, your add-in must specify the ReadWriteMailbox permission level in its manifest. In this case, the token returned will contain read/write access to the user's messages, events, and contacts.

BeispielExample

Office.context.mailbox.getCallbackTokenAsync({isRest: true}, function(result){
  if (result.status === "succeeded") {
    var accessToken = result.value;

    // Use the access token
    getCurrentItem(accessToken);
  } else {
    // Handle the error
  }
});

Abrufen der Element-IDGet the item 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.To retrieve the current item via REST, your add-in will need the item's ID, properly formatted for REST. This is obtained from the Office.context.mailbox.item.itemId property, but some checks should be made to ensure that it is a REST-formatted ID.

  • In Outlook Mobile ist der von Office.context.mailbox.item.itemId zurückgegebene Wert eine ID im REST-Format und kann ohne Weiteres verwendet werden.In Outlook Mobile, the value returned by Office.context.mailbox.item.itemId is a REST-formatted ID and can be used as-is.
  • 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.In other Outlook clients, the value returned by Office.context.mailbox.item.itemId is an EWS-formatted ID, and must be converted using the Office.context.mailbox.convertToRestId method.
  • 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.Note you must also convert Attachment ID to a REST-formatted ID in order to use it. The reason the IDs must be converted is that EWS IDs can contain non-URL safe values which will cause problems for REST.

Das Add-In kann bestimmen, welcher Outlook-Client geladen wird, indem die Office.context.mailbox.diagnostics.hostName-Eigenschaft überprüft wird.Your add-in can determine which Outlook client it is loaded in by checking the Office.context.mailbox.diagnostics.hostName property.

BeispielExample

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-URLGet the REST API URL

Die letzte Angabe, die das Add-In zum Aufrufen der REST-API benötigt, ist der Hostname, der zum Senden von API-Anforderungen verwendet werden soll. Diese Information ist in der Office.context.mailbox.restUrl-Eigenschaft enthalten.The final piece of information your add-in needs to call the REST API is the hostname it should use to send API requests. This information is in the Office.context.mailbox.restUrl property.

BeispielExample

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

Aufrufen der APICall the 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.After your add-in has the access token, item ID, and REST API URL, it can either pass that information to a back-end service which calls the REST API, or it can call it directly using AJAX. The following example calls the Outlook Mail REST API to get the current message.

function getCurrentItem(accessToken) {
  // Get the item's REST ID
  var itemId = getItemRestId();

  // Construct the REST URL to the current item
  // Details for formatting the URL can be found at 
  // https://docs.microsoft.com/previous-versions/office/office-365-api/api/version-2.0/mail-rest-operations#get-a-message-rest
  var 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`
    var subject = item.Subject;
    ...
  }).fail(function(error){
    // Handle error
  });
}

Siehe auchSee also

Ein Beispiel, in dem die REST-APIs im Outlook-Add-In aufgerufen werden, finden Sie unter command-demo auf GitHub.For an example that calls the REST APIs from an Outlook add-in, see command-demo on GitHub.