Übersicht über die Verwendung der Outlook-REST-APIsOverview of using the Outlook REST APIs

Tipp

Probieren Sie REST-Beispielaufrufe in unserem Graph-Tester aus. Sie können Ihr eigenes Konto oder eines unserer Testkonten verwenden. Kehren Sie, sobald Sie mit dem Testen der API fertig sind, hierher zurück, und wählen Sie Ihre bevorzugte Plattform auf der linken Seite aus. Sie werden durch die Schritte zum Schreiben einer einfachen Anwendung zum Abrufen von Nachrichten aus Ihrem Posteingang geführt.Try out sample REST calls in the Graph Explorer. You can use your own account, or one of our test accounts. Once you're done exploring the API, come back here and select your favorite platform on the left. We'll guide you through the steps to write a simple application to retrieve messages from your inbox.

Wenn Ihre bevorzugte Plattform nicht aufgeführt ist, fahren Sie mit dem Lesen dieser Seite fort. Hier werden die gleichen Schritte unter Verwendung von unformatierten HTTP-Anforderungen beschrieben.If your preferred platform isn't listed yet, continue reading on this page. We'll go through the same set of steps using raw HTTP requests.

In diesem Leitfaden werden Sie schrittweise durch den Prozess des Aufrufs der Outlook-Mail-API zum Abrufen von Nachrichten in Office 365 und Outlook.com geführt. Im Gegensatz zu den plattformspezifischen Erste-Schritte-Anleitungen liegt in diesem Leitfaden der Fokus auf OAuth- und REST-Anforderungen und -Antworten. Es wird die Abfolge der Anforderungen und Antworten behandelt, die eine App zum Authentifizieren und Abrufen von Nachrichten verwendet.The purpose of this guide is to walk through the process of calling the Outlook Mail API to retrieve messages in Office 365 and Outlook.com. Unlike the platform-specific getting started guides, this guide focuses on the OAuth and REST requests and responses. It will cover the sequence of requests and responses that an app uses to authenticate and retrieve messages.

In diesem Lernprogramm wird Microsoft Graph zum Aufrufen der Mail-API verwendet. Microsoft empfiehlt die Verwendung von Microsoft Graph für den Zugriff auf Outlook-Mail, -Kalender und -Kontakte. Verwenden Sie die Outlook-APIs nur dann direkt (über https://outlook.office.com/api), wenn Sie ein Feature benötigen, das in den Graph-Endpunkten nicht verfügbar ist.This tutorial will use Microsoft Graph to call the Mail API. Microsoft recommends using Microsoft Graph to access Outlook mail, calendar, and contacts. You should use the Outlook APIs directly (via https://outlook.office.com/api) only if you require a feature that is not available on the Graph endpoints.

Mit den Informationen in diesem Leitfaden können Sie dies in einem beliebigen Sprache oder Plattform implementieren, die HTTP-Anforderungen senden kann.With the information in this guide, you can implement this in any language or platform capable of sending HTTP requests.

Authentifizieren mit OAuth2Use OAuth2 to authenticate

Um die Mail-API aufzurufen, benötigt die App ein Zugriffstoken von Azure Active Directory. Zu diesem Zweck implementiert die App einen der unterstützten OAuth-Flüsse im Azure v2.0-Endpunkt. Damit dies funktioniert, muss die App jedoch im App-Registrierungsportal registriert werden.In order to call the Mail API, the app requires an access token from Azure Active Directory. In order to do that, the app implements one of the supported OAuth flows in the Azure v2.0 endpoint. However, before this will work, the app must be registered in the Application Registration Portal.

Registrieren einer AppRegistering an app

Hinweis

In diesem Beispielszenario wird der Autorisierungscodefluss verwendet.This example scenario will use the authorization code flow. Die einzelnen Schritte für den impliziten Fluss bzw. den Clientanmeldeinformationen-Fluss sind leicht unterschiedlich.The steps for the implicit flow or client credentials flow will be slightly different.

Sie können das App-Registrierungsportal zum schnellen Registrieren einer App verwenden, die eine der Outlook-APIs nutzt.You can use the Application Registration Portal to quickly register an app that uses any of the Outlook APIs.

Wichtig

Neue App-Registrierungen sollten im Anwendungsregistrierungsportal erstellt und verwaltet werden, damit sie mit Outlook.com kompatibel sind. Erstellen Sie neue App-Registrierungen nur dann im Azure-Verwaltungsportal Folgendes auf Ihre App zutrifft:New app registrations should be created and managed in the new Application Registration Portal to be compatible with Outlook.com. Only create new app registrations in the Azure Management Portal if your app:

  • Sie verwendet den OAuth2 Client Credentials Grant-Fluss oderUses the OAuth2 Client Credentials Grant Flow, or
  • Sie muss neben Outlook auf andere Office 365-Arbeitslasten zugreifen (z. B. OneDrive for Business oder SharePoint)Needs to access other Office 365 workloads besides Outlook (such as OneDrive for Business or SharePoint)

Beachten Sie, dass mithilfe des Azure-Verwaltungsportals registrierte Apps nicht mit Outlook.com kompatibel sind und dass Berechtigungsbereiche nicht dynamisch angefordert werden können.Bear in mind that apps registered using the Azure Management Portal will not be compatible with Outlook.com, and will not be able to dynamically request permissions scopes. Vorhandene App-Registrierungen, die im Azure-Verwaltungsportal erstellt wurden, funktionieren weiterhin nur für Office 365.Existing app registrations that were created in the Azure Management Portal will continue to work for Office 365 only. Diese Registrierungen werden nicht im Anwendungsregistrierungsportal angezeigt und müssen im Azure-Verwaltungsportal verwaltet werden.These registrations do not show up in the Application Registration Portal and must be managed in the Azure Management Portal.

KontoanforderungenAccount requirements

Um das Anwendungsregistrierungsportal zu verwenden, benötigen Sie entweder ein Office 365-Geschäfts- oder Schulkonto oder ein Microsoft-Konto. Wenn Sie nicht über eines dieser Konten verfügen, haben Sie verschiedene Möglichkeiten:In order to use the Application Registration Portal, you need either an Office 365 work or school account, or a Microsoft account. If you don't have either of these, you have a number of options:

  • Registrieren Sie sich hier für ein neues Microsoft-Konto.Sign up for a new Microsoft account here.
  • Sie haben mehrere Möglichkeiten, ein Office 365-Abonnement zu erhalten:You can obtain an Office 365 subscription in a couple of different ways:

REST-API-VerfügbarkeitREST API availability

Die REST-API ist derzeit auf allen Office 365-Konten, die über Exchange Online verfügen, sowie auf allen Outlook.com-Konten aktiviert.The REST API is currently enabled on all Office 365 accounts that have Exchange Online, and all Outlook.com accounts.

Nachdem Sie die App registriert haben, verfügen Sie über eine Client-ID und ein Geheimnis. Diese werden im Autorisierungscodefluss verwendet.Once you register the app, you will have a client ID and secret. These are used in the authorization code flow.

Abrufen eines AutorisierungscodesGetting an authorization code

Im ersten Schritt des Autorisierungscodeflusses wird ein Autorisierungscode abgerufen. Dieser Code wird von Azure an die App zurückgegeben, wenn der Benutzer sich anmeldet und der Zugriffsstufe zustimmt, die die App erfordert.The first step in the authorization code flow is to get an authorization code. That code is returned to the app by Azure when the user logs on and consents to the level of access the app requires.

Die App generiert zunächst eine Anmelde-URL für den Benutzer. Diese URL muss in einem Browser geöffnet werden, damit der Benutzer sich anmelden und seine Zustimmung erteilen kann.First the app constructs a logon URL for the user. This URL must be opened in a browser so that the user can login and provide consent.

Die Basis-URL für die Anmeldung sieht wie folgt aus:The base URL for logon looks like:

https://login.microsoftonline.com/common/oauth2/v2.0/authorize

Die App fügt Abfrageparameter an diese Basis-URL an, um Azure mitzuteilen, welche App die Anmeldung anfordert und welche Berechtigungen angefordert werden.The app appends query parameters to this base URL to let Azure know what app is requesting the logon, and what permissions it is requesting.

  • client_id: Die beim Registrieren der App generierte Client-ID. Anhand dieser erkennt Azure, welche App die Anmeldung anfordert.client_id: the client ID generated by registering the app. This lets Azure know which app is requesting the logon.
  • redirect_uri: Der Ort, zu dem Azure umleitet, nachdem der Benutzer seine Zustimmung für die App erteilt hat. Dieser Wert muss mit dem Wert des beim Registrieren der App verwendeten Umleitungs-URI übereinstimmen.redirect_uri: the location that Azure will redirect to once the user has granted consent to the app. This value must correspond to the value of Redirect URI used when registering the app.
  • response_type: Der Antworttyp, den die App erwartet. Für den Autorisierungscodefluss muss der Wert immer code lauten.response_type: the type of response the app is expecting. For the Authorization Grant Flow, this should always be code.
  • scope: Eine mit Leerzeichen getrennte Liste von Zugriffsbereichen, die Ihre App benötigt. Eine vollständige Liste der Outlook-Bereiche in Microsoft Graph finden Sie unter Microsoft Graph-Berechtigungsbereiche.scope: a space-delimited list of access scopes that your app requires. For a full list of Outlook scopes in Microsoft Graph, see Microsoft Graph permission scopes.

Eine Anwendung, die Lesezugriff auf E-Mails benötigt, würde z. B. alle die Parameter zusammenstellen, um eine Anforderungs-URL wie die folgende zu generieren:For example, an application that requires read access to mail would put all of those together to generate a request URL like the following:

AutorisierungscodeanforderungAuthorization code request

GET https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=<CLIENT ID>&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F&response_type=code&scope=openid+Mail.Read

Es wird ein Anmeldefenster mit dem Namen der App angezeigt. Wenn der Benutzer die App zum ersten Mal verwendet, wird nach dem Anmelden eine Liste der App-Berechtigungen angezeigt, die die App benötigt, und der Benutzer wird aufgefordert, diesen zuzustimmen oder sie zu verweigern. Wenn Benutzer dem erforderlichen Zugriff zustimmen, erfolgt im Browser eine Umleitung an den Umleitungs-URI, der in der ursprünglichen Anforderung angegeben wurde.The user will be presented with a sign in screen that displays the name of the app. Once they sign in, if it is their first time using the app, the user will be presented with a list of the app permissions the app requires and asked to allow or deny. Assuming they allow the required access, the browser will be redirected to the redirect URI specified in the initial request.

Umleitungsanforderung nach erfolgreicher AnmeldungRedirect request after successful sign in

GET  HTTP/1.1 302 Found
Location: http://localhost/myapp/?code= AwABAAAA...cZZ6IgAA&session_state=7B29111D-C220-4263-99AB-6F6E135D75EF&state=D79E5777-702E-4260-9A62-37F75FF22CCE

Den Wert des Abfrageparameters code in der URL ist der Autorisierungscode. Im nächsten Schritt wird dieser Code gegen ein Zugriffstoken eingetauscht.The value of the code query parameter in the URL is the authorization code. The next step is to exchange that code for an access token.

Abrufen eines ZugriffstokensGetting an access token

Zum Abrufen eines Zugriffstokens sendet die App fomularcodierte Parameter an die Tokenanforderungs-URL, die immer wie folgt lautet:To get an access token, the app posts form-encoded parameters to the token request URL, which is always:

https://login.microsoftonline.com/common/oauth2/v2.0/token

Die App verwendet die folgenden Parameter.The app includes the following parameters.

  • client_id: Die beim Registrieren der App generierte Client-ID.client_id: the client ID generated by registering the app.
  • client_secret: Das beim Registrieren der App generierte Clientgeheimnis.client_secret: the client secret generated by registering the app.
  • code: Der im vorherigen Schritt abgerufene Autorisierungscode.code: the authorization code obtained in the prior step.
  • redirect_uri: Dieser Wert muss mit dem in der Autorisierungscodeanforderung verwendeten Wert übereinstimmen.redirect_uri: this value must be the same as the value used in the authorization code request.
  • grant_type: Der von der App verwendete Gewährungstyp. Für den Autorisierungscodefluss muss der Wert immer authorization_code lauten.grant_type: the type of grant the app is using. For the Authorization Grant Flow, this should always be authorization_code.

Diese Parameter werden in den Inhaltstyp application/x-www-form-urlencoded codiert und an die Tokenanforderungs-URL gesendet.These parameters are encoded to the application/x-www-form-urlencoded content type and sent to the token request URL.

ZugriffstokenanforderungAccess token request

POST https://login.microsoftonline.com/common/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=AwABAAAA...cZZ6IgAA&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F&client_id=<CLIENT ID>&client_secret=<CLIENT SECRET>

Azure antwortet mit einer JSON-Nutzlast, die das Zugriffstoken enthält.Azure responds with a JSON payload which includes the access token.

ZugriffstokenantwortAccess token response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "token_type":"Bearer",
  "expires_in":"3600",
  "access_token":"eyJ0eXAi...b66LoPVA",
  "scope":"Mail.Read",
}

Das Zugriffstoken befindet sich im Feld access_token der JSON-Nutzlast. Die App verwendet diesen Wert zum Festlegen des Authorization-Headers beim Senden von REST-Aufrufen an die API.The access token is found in the access_token field of the JSON payload. The app uses this value to set the Authorization header when making REST calls to the API.

Aufrufen der Mail-APICalling the Mail API

Wenn die App über ein Zugriffstoken verfügt, kann die Mail-API aufgerufen werden. Die Mail-API-Referenz enthält umfassende Informationen. Da diese App Nachrichten abruft, verwendet sie eine HTTP-GET-Anforderung für die https://graph.microsoft.com/v1.0/me/mailfolders/inbox/messages-URL. Hierdurch wird Nachrichten aus dem Posteingang abgerufen.Once the app has an access token, it's ready to call the Mail API. The Mail API Reference has all of the details. Since the app is retrieving messages, it will use an HTTP GET request to the https://graph.microsoft.com/v1.0/me/mailfolders/inbox/messages URL. This will retrieve messages from the inbox.

Optimieren der AnforderungRefining the request

Apps können das Verhalten von GET-Anforderungen mithilfe von OData-Abfrageparametern steuern. Diese Parameter sollten von den Apps verwendet werden, um die Anzahl der zurückgegebenen Ergebnisse und der für jedes Element zurückgegebenen Felder einzuschränken. Hier ist ein Beispiel.Apps can control the behavior of GET requests by using OData query parameters. It is recommended that apps use these parameters to limit the number of results that are returned and to limit the fields that are returned for each item. Let's look at an example.

Betrachten Sie eine App, die Nachrichten in einer Tabelle anzeigt. Die Tabelle enthält nur Betreff, Absender sowie Datum und Zeit den Nachrichtenempfangs. In der Tabelle werden maximal 25 Zeilen angezeigt, und sie sollte so sortiert sein, dass zuletzt empfangene Nachrichten oben aufgeführt werden.Consider an app that displays messages in a table. The table only displays the subject, sender, and the date and time the message was received. The table displays a maximum of 25 rows, and should be sorted so that the most recently received message is at the top.

Um dies zu erreichen, verwendet die App die folgenden Abfrageparameter.To achieve this, the app uses the following query parameters:

  • Der $select-Parameter wird verwendet, um nur die Felder subject, from und receivedDateTime anzugeben.The $select parameter is used to specify only the subject, from, and receivedDateTime fields.
  • Der $top-Parameter wird zum Festlegen der maximalen Anzahl von 25 Elementen verwendet.The $top parameter is used to specify a maximum of 25 items.
  • Der Parameter $orderby wird zum Sortieren der Ergebnisse nach dem Feld receivedDateTime verwendet.The $orderby parameter is used to sort the results by the receivedDateTime field.

Das Ergebnis ist die folgende Anforderung.This results in the following request.

Mail-API-Anforderung für Nachrichten im PosteingangMail API request for messages in the inbox

GET https://graph.microsoft.com/v1.0/me/mailfolders/inbox/messages?$select=subject,from,receivedDateTime&$top=25&$orderby=receivedDateTime%20DESC

Accept: application/json
Authorization: Bearer eyJ0eXAi...b66LoPVA
X-AnchorMailbox: jason@contoso.onmicrosoft.com

Mail-API-AntwortMail API Response

HTTP/1.1 200 OK
Content-Type: application/json;odata.metadata=minimal;odata.streaming=true;IEEE754Compatible=false;charset=utf-8

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(...)/mailfolders('inbox')messages(subject,from,receivedDateTime)",
  "value": [
    {
      "@odata.etag": "W/\"CQAAABYAAAAoPBSqxXQOT6tuE0pxCMrtAABufX4i\"",
      "id": "AAMkADRmMDExYzhjLWYyNGMtNDZmMC1iZDU4LTRkMjk4YTdjMjU5OABGAAAAAABp4MZ-5xP3TJnNAPmjsRslBwAoPBSqxXQOT6tuE0pxCMrtAAAAAAEMAAAoPBSqxXQOT6tuE0pxCMrtAABufW1UAAA=",
      "subject": "Ruby on Rails tutorial",
      "from": {
        "emailAddress": {
          "address": "jason@contoso.onmicrosoft.com",
          "name": "Jason Johnston"
        }
      },
      "receivedDateTime": "2015-01-29T20:44:53Z"
    },
    {
      "@odata.etag": "W/\"CQAAABYAAAAoPBSqxXQOT6tuE0pxCMrtAABSzmz4\"",
      "id": "AAMkADRmMDExYzhjLWYyNGMtNDZmMC1iZDU4LTRkMjk4YTdjMjU5OABGAAAAAABp4MZ-5xP3TJnNAPmjsRslBwAoPBSqxXQOT6tuE0pxCMrtAAAAAAEMAAAoPBSqxXQOT6tuE0pxCMrtAABMirSeAAA=",
      "subject": "Trip Information",
      "from": {
        "emailAddress": {
          "address": "jason@contoso.onmicrosoft.com",
          "name": "Jason Johnston"
        }
      },
      "receivedDateTime": "2014-12-09T21:55:41Z"
    },
    {
      "@odata.etag": "W/\"CQAAABYAAAAoPBSqxXQOT6tuE0pxCMrtAABzxiLG\"",
      "id": "AAMkADRmMDExYzhjLWYyNGMtNDZmMC1iZDU4LTRkMjk4YTdjMjU5OABGAAAAAABp4MZ-5xP3TJnNAPmjsRslBwAoPBSqxXQOT6tuE0pxCMrtAAAAAAEMAAAoPBSqxXQOT6tuE0pxCMrtAABAblZoAAA=",
      "subject": "Multiple attachments",
      "from": {
        "emailAddress": {
          "address": "jason@contoso.onmicrosoft.com",
          "name": "Jason Johnston"
        }
      },
      "receivedDateTime": "2014-11-19T20:35:59Z"
    },
    {
      "@odata.etag": "W/\"CQAAABYAAAAoPBSqxXQOT6tuE0pxCMrtAAA9yBBa\"",
      "id": "AAMkADRmMDExYzhjLWYyNGMtNDZmMC1iZDU4LTRkMjk4YTdjMjU5OABGAAAAAABp4MZ-5xP3TJnNAPmjsRslBwAoPBSqxXQOT6tuE0pxCMrtAAAAAAEMAAAoPBSqxXQOT6tuE0pxCMrtAAA9x_8YAAA=",
      "subject": "Attachments",
      "from": {
        "emailAddress": {
          "address": "jason@contoso.onmicrosoft.com",
          "name": "Jason Johnston"
        }
      },
      "receivedDateTime": "2014-11-18T20:38:43Z"
    }
  ]
}

Nachdem Sie nun gelernt haben, wie Aufrufe an die Mail-API gesendet werden, können Sie anhand der API-Referenz beliebige Arten von Aufrufen erstellen, die für Ihre App erforderlich sind. Denken Sie jedoch daran, dass entsprechende Berechtigungen für die App bei der App-Registrierung für die Aufrufe konfiguriert werden müssen.Now that you've seen how to make calls to the Mail API, you can use the API reference to construct any other kinds of calls your app needs to make. However, bear in mind that your app needs to have the appropriate permissions configured on the app registration for the calls it makes.