Kombinieren mehrerer HTTP-Anforderungen mithilfe von JSON-Batchverarbeitung
Mithilfe der JSON-Batchverarbeitung können Clients mehrere Anforderungen in einem einzelnen JSON-Objekt und einem einzelnen HTTP-Aufruf kombinieren, wodurch Netzwerkroundtrips reduziert und die Effizienz verbessert wird. Microsoft Graph unterstützt die Batchverarbeitung von bis zu 20 Anforderungen in das JSON-Objekt.
In diesem Artikel untersuchen wir die Grundlagen der JSON-Batchverarbeitung, wie es funktioniert und wie Sie es verwenden können, um Ihre Anwendungen zu optimieren.
Hinweis
Microsoft Graph implementiert das $batchOData-URL-Pfadsegment , um die JSON-Batchverarbeitung zu unterstützen.
Beispielszenario
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.
Erstellen einer Batchanforderung
So erstellen Sie eine Batchanforderung:
Geben Sie die HTTP-Anforderungsmethode als POST an.
Geben Sie den URL-Endpunkt an, unabhängig davon, ob er auf die
v1.0Version oderbetavon Microsoft Graph abzielt, und fügen Sie das$batchSegment an die URL an. Dies ist .https://graph.microsoft.com/v1.0/$batchDefinieren Sie den Batchanforderungstext wie folgt:
- Ein JSON-Batchanforderungstext besteht aus einem einzelnen JSON-Objekt mit einer erforderlichen Eigenschaft: anforderungen. Diese 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, andernfalls schlägt die Batchanforderung mit einem Fehlercode fehl 400.Methode Erforderlich. Die http-Methode, die für die in url angegebene Anforderung unterstützt wird. url Erforderlich. Die relative Ressourcen-URL für die einzelne Anforderung. Während also die absolute URL https://graph.microsoft.com/v1.0/usersist, 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 einer JSON-Batchanforderung
In diesem Beispielszenario erstellen Sie die JSON-Batchanforderung. Die einzelnen Anforderungen sind 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/memberOf"
},
{
"id": "2",
"method": "GET",
"url": "/me/planner/tasks"
},
{
"id": "3",
"method": "DELETE",
"url": "/groups/0e226165-c685-41ce-8bfc-df8360ab325d"
},
{
"id": "4",
"url": "/users/161ab652-cdbc-490d-82a4-0ada1f0db247/getPasswordSingleSignOnCredentials",
"method": "POST",
"body": {},
"headers": {"Content-Type": "application/json"}
},
{
"id": "5",
"url": "users?$select=id,displayName,userPrincipalName&$filter=city eq null&$count=true",
"method": "GET",
"headers": {
"ConsistencyLevel": "eventual"
}
}
]
}
Verarbeiten der JSON-Batchantwort
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. Die id-Eigenschaft kann verwendet werden, um einzelne Anforderungen und Antworten zu korrelieren.
- Anstelle von Methode und URL verfügen einzelne Antworten über eine status-Eigenschaft. Der Wert von status ist der HTTP-status Code.
- 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 4xx. Wenn die Batchanforderung selbst falsch formatiert ist, lautet der Statuscode 400. Wenn die Batchanforderung analysierbar ist, lautet der Statuscode 200. Ein 200 status Code 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 status Code.
Beispiel für JSON-Batchantwort
Gehen Sie für das vorherige Beispiel von der folgenden Antwort aus:
HTTP/1.1 200 OK
Content-Type: application/json
{
"responses": [
{
"id": "1",
"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/beta/$metadata#directoryObjects",
"@odata.nextLink": "https://graph.microsoft.com/beta/me/memberOf?$top=1&$skiptoken=RFNwdAoAAQAAAAAAAAAAFAAAAI45VMy0CO9Ei1L3Lr1q95UBAAAAAAAAAAAAAAAAAAAXMS4yLjg0MC4xMTM1NTYuMS40LjIzMzEGAAAAAAABURXWGePFEEGbudEn3SOTuQEDAQAAAQAAAAA",
"value": [
{
"@odata.type": "#microsoft.graph.directoryRole",
"id": "21004afc-7bb2-4fe6-a1e1-074ebd3e52c1",
"deletedDateTime": null,
"description": "Can manage all aspects of users and groups, including resetting passwords for limited admins.",
"displayName": "User Administrator",
"roleTemplateId": "fe930be7-5e62-47db-91af-98c3a49a38b1"
}
]
}
},
{
"id": "2",
"status": 403,
"headers": {
"Cache-Control": "no-cache",
"X-ProxyCluster": "wus-001.tasks.osi.office.net",
"X-OfficeCluster": "wus-001.tasks.osi.office.net",
"X-Tasks-CorrelationId": "18a8e521-78a4-4129-9b6b-d678116464e7",
"Content-Type": "application/json"
},
"body": {
"error": {
"code": "",
"message": "You do not have the required permissions to access this item.",
"innerError": {
"date": "2025-02-13T10:17:05",
"request-id": "93b6f17e-c05d-4f45-ad2a-6665c708d8a0",
"client-request-id": "e70c5c1b-8b47-68c0-3171-3d22f5e0bd54"
}
}
}
},
{
"id": "3",
"status": 403,
"headers": {
"Cache-Control": "no-cache",
"x-ms-resource-unit": "1",
"Content-Type": "application/json"
},
"body": {
"error": {
"code": "Authorization_RequestDenied",
"message": "Insufficient privileges to complete the operation.",
"innerError": {
"date": "2025-02-13T10:17:06",
"request-id": "93b6f17e-c05d-4f45-ad2a-6665c708d8a0",
"client-request-id": "e70c5c1b-8b47-68c0-3171-3d22f5e0bd54"
}
}
}
},
{
"id": "4",
"status": 405,
"headers": {
"Cache-Control": "no-cache",
"x-ms-resource-unit": "1",
"Content-Type": "application/json"
},
"body": {
"error": {
"code": "Request_BadRequest",
"message": "Specified HTTP method is not allowed for the request target.",
"innerError": {
"date": "2025-02-13T10:21:18",
"request-id": "3a3b1bf7-3596-4493-8264-de81e028071f",
"client-request-id": "e5f9a304-2796-b7e8-ccce-dd989953ebc4"
}
}
}
},
{
"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/beta/$metadata#users(id,displayName,userPrincipalName)",
"@odata.count": 36,
"value": [
{
"id": "10a1d484-cd1a-4162-a5a4-832370bac356",
"displayName": "Lynne Robbins",
"userPrincipalName": "LynneR@contoso.com"
}
]
}
}
]
}
Erläuterung einzelner Antworten in der Beispielbatchantwort
- Die Anforderungen 1 und 5 waren erfolgreich, wie im
200status Code gezeigt. - Die Anforderungen 2 und 3 sind mit einem
403status Code fehlgeschlagen, da der Aufrufer nicht über die erforderlichen Berechtigungen verfügte. - Fehler bei Anforderung 4 mit einem
405status Code, da sich der in der url-Eigenschaft der Anforderung angegebene Endpunkt derzeit nur inbetabefindet, während die Anforderungs-URL auf denv1.0Endpunkt von Microsoft Graph abzielt. Obwohl die Ziel-URL keinen Anforderungstext erfordert, müssen Sie dennoch die Header und Textkörperparemeter angeben, wobei nur body ein leeres Objekt sein kann.
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, und wenn eine Anforderung die Grenzwerte überschreitet, schlägt sie mit dem status fehl
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.