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.
| Eigenschaft | Beschreibung |
|---|---|
| id | Erforderlich. Zeichenfolge. Ein Korrelationswert zum Zuordnen einzelner Antworten zu Anforderungen. Dieser Wert ermöglicht es dem Server, Anforderungen im Batch in der effizientesten Reihenfolge zu verarbeiten. Die Groß-/Kleinschreibung wird nicht beachtet. Muss im Batch eindeutig sein. |
| Methode | Erforderlich. Die HTTP-Methode. |
| url | Erforderlich. Die relative Ressourcen-URL für die einzelne Anforderung. Während also die absolute URL https://graph.microsoft.com/v1.0/users ist, ist diese URL /users. |
| Überschriften | Optional, aber erforderlich, wenn der Text angegeben ist. Ein JSON-Objekt mit dem Schlüssel/Wert-Paar für die Header. Wenn beispielsweise der ConsistencyLevel-Header erforderlich ist, wird diese Eigenschaft als "headers": {"ConsistencyLevel": "eventual"}dargestellt. Wenn der Text bereitgestellt wird, muss ein Inhaltstyp-Header enthalten sein. |
| body | Optional. Kann ein JSON-Objekt oder ein Base64-URL-codierter Wert sein, z. B. wenn der Text ein Bild ist. Wenn die Anforderung einen Text enthält, muss das Header-Objekt einen Wert für den Inhaltstyp enthalten. |
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.
Tipp
Der Batch sollte entweder vollständig sequenziell oder vollständig parallel sein.
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.