Kombinieren mehrerer HTTP-Anforderungen mithilfe von JSON-Batchverarbeitung

Mithilfe der JSON-Batchverarbeitung können Sie Ihre Anwendung optimieren, indem Sie mehrere Anforderungen (bis zu 20) in einem einzelnen JSON-Objekt kombinieren.

Stellen Sie sich einen Client vor, der eine Ansicht der folgenden nicht verknüpften Daten erstellen möchte:

• Ein in OneDrive gespeichertes Bild
• Eine Liste von Planner-Aufgaben
• Der Kalender für eine Gruppe

Indem Sie diese drei einzelnen Anforderungen in einer einzigen Batchanforderung kombinieren, können Sie die Netzwerklatenz der Anwendung erheblich reduzieren.

Microsoft Graph implementiert das $batchOData-URL-Pfadsegment , um die JSON-Batchverarbeitung zu unterstützen.

Beispiel: Erste JSON-Batchanforderung

Zunächst erstellen Sie die JSON-Batchanforderung für das Beispielszenario. In diesem Szenario sind die einzelnen Anforderungen nicht voneinander abhängig und können daher in beliebiger Reihenfolge in die Batchanforderung eingefügt werden.

POST https://graph.microsoft.com/v1.0/$batch
Accept: application/json
Content-Type: application/json

{
  "requests": [
    {
      "id": "1",
      "method": "GET",
      "url": "/me/drive/root:/{file}:/content"
    },
    {
      "id": "2",
      "method": "GET",
      "url": "/me/planner/tasks"
    },
    {
      "id": "3",
      "method": "GET",
      "url": "/groups/{id}/events"
    },
    {
      "id": "4",
      "url": "/me",
      "method": "PATCH",
      "body": {
        "city" : "Redmond"
      },
      "headers": {
        "Content-Type": "application/json"
      }
    },
    {
      "id": "5",
      "url": "users?$select=id,displayName,userPrincipalName&$filter=city eq null&$count=true",
      "method": "GET",
      "headers": {
        "ConsistencyLevel": "eventual"
      }
    }
  ]
}

Erläuterung eines Batchanforderungsformats

Stapelanforderungen werden immer mit einem POST an den /$batch-Endpunkt gesendet.

Ein JSON-Batchanforderungstext besteht aus einem einzelnen JSON-Objekt mit einer erforderlichen Eigenschaft: anforderungen. Die requests-Eigenschaft ist eine Auflistung einzelner Anforderungen. Für jede einzelne Anforderung können die folgenden Eigenschaften übergeben werden.

Beispiel: Erste JSON-Batchantwort

Antworten auf die zum Batch zusammengefassten Anforderungen werden möglicherweise in einer anderen Reihenfolge angezeigt. Die id-Eigenschaft kann verwendet werden, um einzelne Anforderungen und Antworten zu korrelieren.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "responses": [
    {
      "id": "1",
      "status": 302,
      "headers": {
        "location": "https://b0mpua-by3301.files.1drv.com/y23vmagahszhxzlcvhasdhasghasodfi"
      }
    },
    {
      "id": "3",
      "status": 401,
      "body": {
        "error": {
          "code": "Forbidden",
          "message": "..."
        }
      }
    },
    {
      "id": "5",
      "status": 200,
      "headers": {
        "Cache-Control": "no-cache",
        "x-ms-resource-unit": "1",
        "OData-Version": "4.0",
        "Content-Type": "application/json;odata.metadata=minimal;odata.streaming=true;IEEE754Compatible=false;charset=utf-8"
      },
      "body": {
        "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(id,displayName,userPrincipalName)",
        "@odata.count": 12,
        "value": [
          {
            "id": "071cc716-8147-4397-a5ba-b2105951cc0b",
            "displayName": "Adele Vance",
            "userPrincipalName": "AdeleV@Contoso.com"
          }
        ]
      }
    },
    {
      "id": "2",
      "status": 200,
      "body": {
        "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(microsoft.graph.plannerTask)",
        "value": []
      }
    },
    {
      "id": "4",
      "status": 204,
      "body": null
    }
  ]
}

Erläuterung eines Batchantwortformats

Das Antwortformat für JSON-Batchanforderungen unterscheidet sich wie folgt vom Anforderungsformat:

• Die Eigenschaft im Haupt-JSON-Objekt heißt Antworten im Gegensatz zu Anfragen.
• Einzelne Antworten werden möglicherweise in einer anderen Reihenfolge angezeigt als die Anforderungen.
• Anstelle von Methode und URL verfügen einzelne Antworten über eine Statuseigenschaft . Der Wert von status ist der HTTP-Statuscode.
• DieHeader Eigenschaft in jeder einzelnen Antwort stellt die vom Server zurückgegebenen Header dar, zum Beispiel,die Cache-Control und Content-Type Header.

Der Statuscode einer Batchantwort lautet in der Regel 200 oder 400. Wenn die Batchanforderung selbst falsch formatiert ist, lautet der Statuscode 400. Wenn die Batchanforderung analysierbar ist, lautet der Statuscode 200. Ein 200 Statuscode für die Batchantwortheader gibt nicht an, dass die einzelnen Anforderungen innerhalb des Batches erfolgreich waren. Aus diesem Grund verfügt jede einzelne Antwort in der Response-Eigenschaft über einen Statuscode.

Sequenzieren von Anforderungen mit der dependsOn-Eigenschaft

Sie können die Anforderungen im Batch angeben, die in einer angegebenen Reihenfolge ausgeführt werden sollen, indem Sie die dependsOn-Eigenschaft verwenden. Diese Eigenschaft ist ein Array von Zeichenfolgen, das auf die ID einer anderen einzelnen Anforderung verweist. In der folgenden Anforderung gibt der Client beispielsweise an, dass Anforderungen in der Reihenfolge der Anforderung 1, dann der Anforderung 2, der Anforderung 4 und der Anforderung 3 ausgeführt werden sollen.

{
  "requests": [
    {
      "id": "1",
      "method": "GET",
      "url": "..."
    },
    {
      "id": "2",
      "dependsOn": [ "1" ],
      "method": "GET",
      "url": "..."
    },
    {
      "id": "4",
      "dependsOn": [ "2" ],
      "method": "GET",
      "url": "..."
    },
    {
      "id": "3",
      "dependsOn": [ "4" ],
      "method": "GET",
      "url": "..."
    }
  ]
}

Wenn beim Ausführen einer einzelnen Anforderung ein Fehler auftritt, tritt bei allen Anforderungen, die von der betreffenden Anforderung abhängen, ein Fehler mit dem Statuscode 424 (Abhängigkeitsfehler) auf.

Umgehen von URL-Längenbeschränkungen durch Batchverarbeitung

Ein weiterer Anwendungsfall für die JSON-Batchverarbeitung ist die Umgehung von URL-Längenbeschränkungen. In Fällen, in denen die Filterklausel komplex ist, kann die URL-Länge die in Browsern oder anderen HTTP-Clients integrierten Einschränkungen überschreiten. Sie können die JSON-Batchverarbeitung als Problemumgehung für die Ausführung dieser Anforderungen verwenden, da die langwierige URL einfach Teil der Anforderungsnutzlast wird.

Einschränkungen der Batchgröße

• JSON-Batchanforderungen sind derzeit auf 20 einzelne Anforderungen beschränkt.
• Abhängig von den APIs, die Teil der Batchanforderung sind, legen die zugrunde liegenden Dienste eigene Drosselungsgrenzwerte fest, die sich auf Anwendungen auswirken, die Microsoft Graph für den Zugriff darauf verwenden.
• Anforderungen in einem Batch werden einzeln anhand der geltenden Drosselungsgrenzwerte ausgewertet. Wenn eine Anforderung die Grenzwerte überschreitet, tritt ein Fehler mit dem Status auf 429.

Weitere Informationen finden Sie unter Drosselung und Batchverarbeitung.

Bekannte Probleme

Eine Liste von aktuellen Beschränkungen im Zusammenhang mit der Batchverarbeitung finden Sie unter bekannte Probleme.

Verwandte Inhalte

• Verwenden der Microsoft Graph SDKs zum Batchen von Anforderungen