Freigeben über

Senden von Outlook-REST-Anforderungen in Batches (Version 2.0)

  • Artikel

Gilt für: Exchange Online | Office 365 | Hotmail.com | Live.com | MSN.com | Outlook.com | Passport.com

Die Batchverarbeitung ermöglicht es Ihnen, mehrere Outlook REST-Anforderungen in einer einzigen HTTP-Batch-Anforderung zusammenzufassen, wodurch die Anzahl der HTTP-Verbindungen und der Mehraufwand reduziert werden. Die Anforderungen in einem Batch greifen auf die Daten des angemeldeten Benutzers zu, die durch Azure Active Directory in Office 365 oder in einem Microsoft-Konto (Hotmail.com, Live.com, MSN.com, Outlook.com oder Passport.com) gesichert sind.

Hinweis

Zur Vereinfachung des Verweises verwendet der Rest dieses Artikels Outlook.com, um diese Microsoft-Kontodomänen einzuschließen.

Kein Interesse an v2.0 der API? Wechseln Sie im Inhaltsverzeichnis auf der linken Seite zu Office 365 REST API-Verweis und wählen Sie die gewünschte Version aus.

Übersicht

Eine REST-Anforderung erfordert eine HTTP-Verbindung zwischen Client und Server, die einen gewissen Mehraufwand verursacht. Mit der Batchverarbeitung können Sie den Verbindungsmehraufwand reduzieren, indem Sie mehrere REST-API-Aufrufe für denselben Kontext in einer einzigen HTTP-POST-Anforderung an den Endpunkt $batch kombinieren.

Beispielsweise können Sie API-Aufrufe für den Kontext me so kombinieren:

POST https://outlook.office.com/api/v2.0/me/$batch

Eine Batch-Anforderung kann bis zu 20 einzelne REST-API-Aufrufe enthalten, die Datenabfragen (z.B. GET) oder Änderungsoperationen (z.B. POST) sein können. Sie können einen Prefer-Header angeben, damit der Batch fortgesetzt wird, auch wenn ein oder mehrere REST-Aufrufe fehlschlagen.

Die Batchverarbeitung ist besonders nützlich bei der Synchronisation großer Datenmengen. API-Aufrufe im selben Batch können auf verschiedene Ressourcen wie Nachrichten und Ereignisse zugreifen, die zum selben Postfach gehören.

Wenn Sie mehr als 20 Aufrufe tätigen müssen, oder wenn die Reihenfolge des Abschlusses von Aufrufen wichtig ist, verwenden Sie mehrere Batch-Anforderungen.

Beispiel

Ein einfaches Beispiel illustriert die Batchverarbeitung am besten. Die folgende Batch-Anforderung stellt 2 Outlook REST-API-Aufrufe in einem einzigen Batch für den Kontext me dar:

  1. Alle Ereignisse des angemeldeten Benutzers abrufen (GET)
  2. POST und senden Sie eine Nachricht.

Batch-Anforderung

POST https://outlook.office.com/api/v2.0/me/$batch HTTP/1.1

Authorization: Bearer aGFwcHlnQGRr==
Host: outlook.office.com
Content-Type: multipart/mixed; boundary=batch_myBatchId


--batch_myBatchId
Content-Type: application/http
Content-Transfer-Encoding: binary

GET /api/v2.0/me/events?$select=subject,organizer HTTP/1.1

--batch_myBatchId
Content-Type: application/http
Content-Transfer-Encoding: binary

POST /api/v2.0/me/sendmail HTTP/1.1
Content-Type: application/json

{
  "Message": {
    "Subject": "Meet for lunch?",
    "Body": {
      "ContentType": "Text",
      "Content": "The new cafeteria is open."
    },
    "ToRecipients": [
      {
        "EmailAddress": {
          "Address": "rufus@contoso.com"
        }
      }
    ]
  }
}
 
--batch_myBatchId--

Hinweis

Im vorhergehenden Beispiel, das eine POST-Operation am Ende des Batches hat, wird gerade nach dem allerletzten Batch-Trennzeichen --batch_{batchId}-- eine neue Zeile benötigt. Erfahren Sie mehr zu Formatierungshinweisen für Batch-Anforderungstexte.

Batch-Antwort

Die Batch-Antwort enthält separate Antwortcodes und -Texte, sofern zutreffend, für die Batch-Anforderung und einzelne Aufrufe.

HTTP/1.1 200 OK
Content-Type: multipart/mixed; boundary=batchresponse_caad32b6-3fa6-4346-94d0-ee98e067318a
Content-Length: 786

--batchresponse_caad32b6-3fa6-4346-94d0-ee98e067318a
Content-Type: application/http
Content-Transfer-Encoding: binary

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

{
    "@odata.context":"https://outlook.office.com/api/v2.0/$metadata#Me/Events(Subject,Organizer)",
    "value":[
        {
            "@odata.id":"https://outlook.office.com/api/v2.0/Users('cd209b0b-3f83-4c35-82d2-d88a61820480@8b5d41d8-b1af-495e-b871-8bbd867ba67a')/Events('AAMkAGI1AAAt9AHkAAA=')",
            "@odata.etag":"W/\"ZlnW4RIAV06KYYwlrfNZvQAALfZeSA==\"",
            "Id":"AAMkAGI1AAAt9AHkAAA=",
            "Subject":"Let's go for lunch",
            "Organizer":{
                "EmailAddress":{
                    "Name":"Dana Swope",
                    "Address":"danas@contoso.onmicrosoft.com"
                }
            }
        },
        {
            "@odata.id":"https://outlook.office.com/api/v2.0/Users('cd209b0b-3f83-4c35-82d2-d88a61820480@8b5d41d8-b1af-495e-b871-8bbd867ba67a')/Events('AAMkAGI1AAAtCq6LAAA=')",
            "@odata.etag":"W/\"ZlnW4RIAV06KYYwlrfNZvQAALQzodA==\"",
            "Id":"AAMkAGI1AAAtCq6LAAA=",
            "Subject":"Prep for customer visit",
            "Organizer":{
                "EmailAddress":{
                    "Name":"Dana Swope",
                    "Address":"danas@contoso.onmicrosoft.com"
                }
            }
        }
    ]
}
--batchresponse_caad32b6-3fa6-4346-94d0-ee98e067318a
Content-Type: application/http
Content-Transfer-Encoding: binary

HTTP/1.1 202 Accepted

--batchresponse_caad32b6-3fa6-4346-94d0-ee98e067318a--

Endpunkt-URL

Sie können einen POST-Befehl im $batch-Endpunkt für einen von 2 Kontexten durchführen:

  • Für den angemeldeten Benutzer me:

    POST https://outlook.office.com/api/v2.0/me/$batch HTTP/1.1

  • Für einen bestimmten Benutzer, wobei user_id eine Benutzer-ID oder Benutzer-E-Mail-Adresse sein kann:

    POST https://outlook.office.com/api/v2.0/users('{user_id}')/$batch

Nachdem Sie den Kontext in der POST-Anforderung an den Endpunkt $batch festgelegt haben, müssen alle REST-API-Aufrufe, die in derselben Batch-Anforderung enthalten sind, für denselben Kontext gelten.

Wichtig

  • Wenn Ihre Batch-Anforderung für einen bestimmten Benutzer bestimmt ist, stellen Sie sicher, dass Sie auf den Benutzer über die gesamte Menge der Batch-Anforderungen hinweg konsistent verweisen. Das heißt, verwenden Sie nur .../users('{user_id}') oder .../users/'{user_id}', aber nicht beides.
  • Wenn Sie die Stamm-URL https://outlook.office.com verwenden, fügen Sie einen x-AnchorMailbox-Header hinzu und stellen Sie ihn für die E-Mail-Adresse des Benutzers ein.
  • Behandeln Sie auch den Fall, in dem das Postfach eines Outlook.com-Benutzers noch nicht für die Outlook-REST-API aktiviert wurde - suchen Sie nach den Fehlercodes MailboxNotEnabledForRESTAPI und MailboxNotSupportedForRESTAPI. Mehr erfahren Sie hier.

Hinweis

Hinweise für Entwickler in China

  • Wenn Sie Anwendungen für Office 365 in China entwickeln, sollten Sie weiterhin die API-Endpunkte von Office 365 für China verwenden.
  • Wenn Sie Apps für Outlook.com in China erstellen, müssen Sie die v2 App-Modellvorschau und den folgenden Outlook REST-Endpunkt verwenden: https://outlook.office.com/api/{version}

Version der API

Diese API wurde von der Vorschauversion auf den Status Allgemeine Verfügbarkeit (GA) befördert. Sie wird in den v2.0 und Beta-Versionen der Outlook-REST-API unterstützt.

In der Batch-Anforderung müssen Sie den gleichen Host und die gleiche Version angeben wie bei den REST-Aufrufen im Batch.

Ziel-Benutzer

Sie können Outlook REST-API-Aufrufe für dasselbe Postfach in einem Batch gruppieren. Das Postfach kann auf Office 365 oder Outlook.com sein. Der Versuch, in einer Reihe von Batch-Anforderungen auf mehr als ein Postfach zuzugreifen, führt zu einer Ausnahme.

Authentifizierung

Ähnlich wie beim Senden von Outlook-REST-API Aufrufen als individuelle Anforderungen, sollten Sie ein gültiges Zugriffstoken in einen Autorisierungs-Anforderungs-Header einfügen. Wenn Sie diesen Header für die Batch-Anforderung angeben, sollte das Zugriffstoken die erforderliche Berechtigung für alle Aufrufe in diesem Batch bereitstellen. Optional können Sie ein Zugriffstoken für einen bestimmten Aufruf im Batch angeben, wenn dieser Aufruf ein anderes Zugriffstoken erfordert.

Um ein Zugriffstoken zu erhalten, müssen Sie sich registriert und Ihre App identifiziert und die entsprechende Autorisierung erhalten haben. Sie können mehr über einige optimierte Registrierungs- und Autorisierungsoptionen für Sie herausfinden. Denken Sie daran, wenn Sie mehr über die Batchverarbeitung von Anforderungen erfahren.

Batch-Anforderungsheader

Fügen Sie die folgenden Header für jede Batch-Anforderung ein:

Host: outlook.office.com
Content-Type: multipart/mixed; boundary=batch_<batchId>

wobei {batchId} ein Batch identifiziert und zum Abgrenzen von Anforderungen innerhalb des Batches verwendet wird. Es kann eine GUID oder eine beliebige Zeichenfolge zur Unterscheidung sein.

Sie können ggf. weitere Header mit einschließen. Mit Ausnahme von inhaltsbezogenen Headern wie Content-Type gelten die Header in der Batch-Anforderung generell für jeden Vorgang im Batch. Wenn Sie sowohl in der Batch-Anforderung als auch in einem bestimmten Vorgang des Batches einen Header angeben, hat dieser Vorrang und gilt für diese Operation.

Batch-Anforderungstext

Starten Sie jeden Vorgang innerhalb eines Batches mit den folgenden Headerzeilen:

--batch_{batchId} 
Content-Type: application/http 
Content-Transfer-Encoding: binary

Beenden Sie die letzte Operation des Batches wie folgt:

--batch_{batchId}--

Formatierung eines Batch-Anforderungstexts

Beachten Sie die folgenden Formatierungserfordernisse, andernfalls kann Ihre Batch-Anforderung fehlschlagen oder die erwarteten Antworten nicht zurückgeben:

  • Stellen Sie sicher, dass Sie eine zusätzliche neue Zeile vor einem Batch-Begrenzungstrennzeichen haben, wie im folgenden Anforderungstext dargestellt, der 2 Batch-GET-Operationen hat.
  • Insbesondere, wenn Sie eine POST-Anfrage am Ende des Batches haben, ähnlich wie beim ersten Batch-Anforderungs-Beispiel, stellen Sie sicher, dass sich eine neue Zeile nach den allerletzten Batch-Trennzeichen befindet--batch_{batchId}--.

Weitere Beispiele für Batch-Anforderungstexte finden Sie unter Batchverarbeitung (OData Version 3.0).


--batch_{batchId} 
Content-Type: application/http 
Content-Transfer-Encoding: binary 

GET  /api/v2.0/me/messages    HTTP/1.1

--batch_{batchId} 
Content-Type: application/http 
Content-Transfer-Encoding: binary 

GET  /api/v2.0/me/events    HTTP/1.1

--batch_{batchId}--

Operationen in einem Batch

Sie können bis zu 20 Operationen in einer Batch-Anforderung angeben.

Eine Operation in einem Batch kann eine Datenabfrage, Änderung, Aktion oder ein Funktionsaufruf sein. Während Sie nicht alle URLs wiederholen und alle Header für jede Operation im Batch angeben müssen, stellen Sie sicher, dass Sie bestimmte Header und Anforderungstexte angeben, wenn diese für eine Operation benötigt werden.

Unterstützte Formate von Anforderungen in einem Batch

Wie oben erwähnt, müssen der Host, die Version und der Kontext während einer Reihe von Batch-Anforderungen konsistent bleiben. Anforderungen, die im selben Batch enthalten sind, können eine Mischung aus den folgenden 3 Formaten sein. Für die folgenden Beispiele gehen wir davon aus, dass die POST-Anforderung an den Endpunkt $batch wie folgt aussieht:

POST https://outlook.office.com/api/v2.0/me/$batch HTTP/1.1

Absolute URL

Nehmen Sie Host, Version und Kontext in die URL auf. Beispiel:

GET https://outlook.office.com/api/v2.0/me/messages?$select=subject,sender HTTP/1.1

URL relativ zum Host

Fügen Sie eine URL relativ zu dem in der Batch-Anforderung angegebenen Host ein. Während Sie den Host nicht in jeder Batch-Anforderung wiederholen, beziehen Sie die Version und den Kontext mit ein. Beispiel:

GET /api/v2.0/me/messages?$select=subject,sender HTTP/1.1

URL relativ zum Batch

In diesem Format wiederholen Sie den Host, die Version und den Kontext nicht in der Batch-Anforderung. Beispiel:

GET messages?$select=subject,sender HTTP/1.1

Verarbeitung einer Batch-Anforderung

Eine Batch-Anforderung wird allein als eine Anforderung verarbeitet und gibt einen eigenen Antwortcode zurück. Eine wohlgeformte Batch-Anforderung mit korrekten Headern liefert HTTP 200 OK. Dies bedeutet jedoch nicht, dass alle Anforderungen im Batch erfolgreich waren.

Jede Anforderung im Batch-Anforderungstext wird wiederum separat verarbeitet und liefert einen eigenen Antwortcode sowie einen beliebigen Antworttext und eine Fehlermeldung zurück.

Der Server kann Operationen innerhalb eines Batches in beliebiger Reihenfolge durchführen. Wenn Sie Vorgänge in einer bestimmten Reihenfolge ausführen lassen müssen, sollten Sie sie nicht in dieselbe Batch-Anforderung aufnehmen. Senden Sie stattdessen eine Operation selbst, warten Sie auf die Antwort, bevor Sie die nächste senden.

Standardmäßig stoppt die Verarbeitung bei der ersten Operation, die einen Fehler zurückgibt. Sie können den folgenden Header angeben, damit die Verarbeitung den Fehler ignoriert und mit dem nächsten Vorgang im Batch fortfahren kann:

Prefer: odata.continue-on-error

Nächste Schritte

Egal, ob Sie bereit sind, eine App zu erstellen oder einfach nur mehr darüber erfahren möchten, wir haben alles im Griff.

Oder erfahren Sie mehr über die Verwendung der Office 365-Plattform: