Batchanfragen
Mit Sammlungen den Überblick behalten
Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.
In diesem Dokument erfahren Sie, wie API-Aufrufe in einem Batch zusammengefasst werden, um die Anzahl von HTTP-Verbindungen für den Client zu reduzieren.
In diesem Dokument wird ausschließlich das Erstellen einer Batchanfrage durch Senden einer HTTP-Anfrage behandelt. Wenn Sie stattdessen eine Google-Clientbibliothek für die Batchanfrage verwenden, lesen Sie die Informationen in der Dokumentation der Clientbibliothek.
Übersicht
Jede HTTP-Verbindung, die der Client erstellt, führt zu einem bestimmten Overhead. Die People API unterstützt Batchanfragen, damit der Client mehrere API-Aufrufe in einer einzelnen HTTP-Anfrage zusammenfassen kann.
Fallbeispiele für den Einsatz von Batchanfragen:
- Sie haben gerade mit der Verwendung der API begonnen und müssen viele Daten hochladen.
- Ein Nutzer hat Änderungen an Daten vorgenommen, während Ihre Anwendung offline (nicht mit dem Internet verbunden) war, sodass Ihre Anwendung die lokalen Daten mit dem Server synchronisieren und dazu viele Aktualisierungs- und Löschvorgänge senden muss.
In jedem Fall können Sie, anstatt jeden Aufruf einzeln zu senden, mehrere Aufrufe in einer einzigen HTTP-Anfrage zusammenfassen. Alle internen Anfragen müssen an dieselbe Google API gesendet werden.
Jede Batchanfrage ist auf maximal 1.000 Aufrufe begrenzt. Bei einer höheren Anzahl an Aufrufen erstellen Sie mehrere Batchanfragen.
Hinweis: Das Batchsystem der People API verwendet dieselbe Syntax wie das Batchverarbeitungssystem von OData, aber mit einer anderen Semantik.
Batchdetails
Eine Batchanfrage besteht aus mehreren, in einer HTTP-Anfrage zusammengefassten API-Aufrufen. Sie kann an den im Discovery-Dokument der API angegebenen batchPath gesendet werden. Der Standardpfad ist /batch/api_name/api_version. In diesem Abschnitt wird die Batchsyntax im Detail beschrieben. Anschließend finden Sie ein Beispiel.
Hinweis: Wenn n Anfragen zu einem Batch zusammengefasst sind, werden auch n Anfragen auf Ihr Nutzungskontingent angerechnet, nicht nur eine einzige Anfrage. Die Batchanfrage wird vor der Verarbeitung in eine Reihe von Anfragen aufgeteilt.
Eine Batchanfrage ist eine einzelne Standard-HTTP-Anfrage, die mehrere People API-Aufrufe enthält. Dabei wird der Inhaltstyp multipart/mixed verwendet. Jeder Teil der HTTP-Hauptanfrage enthält eine verschachtelte HTTP-Anfrage.
Jeder Teil beginnt mit seinem eigenen HTTP-Header Content-Type: application/http. Er kann auch einen optionalen Content-ID-Header haben. Die Header der einzelnen Teile sollen jedoch nur den Anfang des Teils markieren. Sie sind von der verschachtelten Anfrage getrennt. Nachdem der Server die Batchanfrage in separate Anfragen aufgeteilt hat, werden die Header der einzelnen Teile ignoriert.
Der Text jedes Teils ist an sich eine vollständige HTTP-Anfrage mit eigenem Verb, eigener URL, eigenen Headern und eigenem Text. Die HTTP-Anfrage darf nur den Pfadteil der URL enthalten; vollständige URLs sind in Batchanfragen nicht zulässig.
Die HTTP-Header für die äußere Batchanfrage gelten für jede Anfrage in dem Batch, ausgenommen Content--Header wie Content-Type. Wenn Sie einen bestimmten HTTP-Header sowohl in der äußeren Anfrage als auch in einem individuellen Aufruf verwenden, überschreibt der Wert des individuellen Aufrufheaders den Wert des Headers der äußeren Stapelanfrage. Die Header für einen individuellen Aufruf gelten nur für diesen Aufruf.
Beispiel: Wenn Sie einen Autorisierungsheader für einen bestimmten Aufruf angeben, gilt dieser Header nur für diesen Aufruf. Wenn Sie einen Autorisierungsheader für die äußere Anfrage angeben, gilt dieser Header für alle einzelnen Aufrufe, es sei denn, diese überschreiben ihn mit eigenen Autorisierungsheadern.
Wenn der Server die Stapelanfrage empfängt, wendet er (nach Bedarf) die Abfrageparameter und Header der äußeren Anfrage für jeden Teil an, und behandelt jeden Teil dann so, als wäre er eine separate HTTP-Anfrage.
Antwort auf eine Batchanfrage
Die Antwort des Servers ist eine einzelne Standard-HTTP-Antwort mit einem Inhaltstyp multipart/mixed. Jeder Teil ist die Antwort auf eine der Anfragen in der Batchanfrage in derselben Reihenfolge wie die einzelnen Anfragen.
Wie die Teile in der Anfrage enthält jeder Antwortteil eine vollständige HTTP-Antwort, einschließlich Statuscode, Headern und Text. Wie auch bei den Teilen in der Anfrage ist jedem Antwortteil ein Content-Type-Header vorangestellt, der den Beginn des Teils markiert.
Wenn ein bestimmter Teil einer Anfrage einen Content-ID-Header enthielt, enthält der entsprechende Teil der Antwort einen übereinstimmenden Content-ID-Header, wobei dem ursprünglichen Wert der String response- vorangestellt ist, wie im folgenden Beispiel dargestellt.
Hinweis: Der Server kann die Aufrufe in beliebiger Reihenfolge ausführen. Die Aufrufe werden nicht unbedingt in der Reihenfolge ausgeführt, in der Sie sie angegeben haben. Wenn Sie sicherstellen möchten, dass zwei Aufrufe in einer bestimmten Reihenfolge ausgeführt werden, können Sie sie nicht in einer einzelnen Anfrage senden. Senden Sie stattdessen den ersten Aufruf für sich alleine und warten Sie auf die Antwort auf den ersten Aufruf, bevor Sie den zweiten Aufruf senden.
Beispiel
Das folgende Beispiel zeigt die Verwendung der Batchverarbeitung mit der People API.
Beispiel-Batchanfrage
POST /batch HTTP/1.1
accept-encoding: gzip, deflate
Authorization: Bearer your_auth_token
Content-Type: multipart/mixed; boundary="batch_people"
Content-Length: total_content_length
--batch_people
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID: 1
POST /v1/people:createContact HTTP/1.1
Content-Type: application/json
Content-Length: part_content_length
Accept: application/json
{
"names": [{ "givenName": "John", "familyName": "Doe" }]
}
--batch_people
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID: 2
GET /v1/people/c123456789012345?personFields=emailAddresses HTTP/1.1
Accept: application/json
--batch_people--
Beispiel für eine Stapelantwort
Dies ist die Antwort auf die Beispielanfrage im vorherigen Abschnitt.
HTTP/1.1 200 OK
Content-Type: multipart/mixed; boundary=batch_GOMozbDceUiJkwfCeHo28pGmhwRG5o50
Date: Tue, 22 Jan 2020 18:56:00 GMT
Expires: Tue, 22 Jan 2020 18:56:00 GMT
Cache-Control: private
--batch_GOMozbDceUiJkwfCeHo28pGmhwRG5o50
Content-Type: application/http
Content-ID: response-1
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"resourceName": "people/c11111111111111",
"etag": "1111",
"names": [{ "givenName": "John", "familyName": "Doe" }]
}
--batch_GOMozbDceUiJkwfCeHo28pGmhwRG5o50
Content-Type: application/http
Content-ID: response-2
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"resourceName": "people/c123456789012345",
"etag": "1234",
"emailAddresses": [{ "value": "jane.doe@gmail.com" }]
}
--batch_GOMozbDceUiJkwfCeHo28pGmhwRG5o50--
Sofern nicht anders angegeben, sind die Inhalte dieser Seite unter der Creative Commons Attribution 4.0 License und Codebeispiele unter der Apache 2.0 License lizenziert. Weitere Informationen finden Sie in den Websiterichtlinien von Google Developers. Java ist eine eingetragene Marke von Oracle und/oder seinen Partnern.
Zuletzt aktualisiert: 2025-08-29 (UTC).
[[["Leicht verständlich","easyToUnderstand","thumb-up"],["Mein Problem wurde gelöst","solvedMyProblem","thumb-up"],["Sonstiges","otherUp","thumb-up"]],[["Benötigte Informationen nicht gefunden","missingTheInformationINeed","thumb-down"],["Zu umständlich/zu viele Schritte","tooComplicatedTooManySteps","thumb-down"],["Nicht mehr aktuell","outOfDate","thumb-down"],["Problem mit der Übersetzung","translationIssue","thumb-down"],["Problem mit Beispielen/Code","samplesCodeIssue","thumb-down"],["Sonstiges","otherDown","thumb-down"]],["Zuletzt aktualisiert: 2025-08-29 (UTC)."],[[["\u003cp\u003eBatching in the People API allows combining multiple API calls into a single HTTP request to reduce overhead.\u003c/p\u003e\n"],["\u003cp\u003eUse batching for scenarios like initial data uploads or synchronizing offline changes.\u003c/p\u003e\n"],["\u003cp\u003eA batch request uses the \u003ccode\u003emultipart/mixed\u003c/code\u003e content type and nests individual API calls as parts.\u003c/p\u003e\n"],["\u003cp\u003eThe server processes each part of the batch request as a separate HTTP request, but the order of execution isn't guaranteed.\u003c/p\u003e\n"],["\u003cp\u003eThe batch response is also \u003ccode\u003emultipart/mixed\u003c/code\u003e, with each part corresponding to the response of an individual call in the request.\u003c/p\u003e\n"]]],["Batching API calls consolidates multiple requests into a single HTTP request, reducing overhead. This method is useful for initial data uploads or synchronizing offline data. A batch request, limited to 1000 calls, uses `multipart/mixed` and contains nested HTTP requests. Each part has `Content-Type: application/http` header, with the body as a complete HTTP request (path portion only). The server returns a `multipart/mixed` response with individual HTTP responses. Outer request headers apply to all, but individual call headers can override them.\n"],null,["# Batching Requests\n\nThis document shows how to batch API calls together to reduce the number of HTTP connections\nyour client has to make.\n\nThis document is specifically about making a batch request by sending an\nHTTP request. If, instead, you're using a Google client library to make a batch request, see the [client library's documentation](https://developers.google.com/api-client-library/).\n\nOverview\n--------\n\nEach HTTP connection your client makes results in a certain amount of overhead. The People API supports batching, to allow your client to put several API calls into a single HTTP request.\n\nExamples of situations when you might want to use batching:\n\n- You've just started using the API and you have a lot of data to upload.\n- A user made changes to data while your application was offline (disconnected from the Internet), so your application needs to synchronize its local data with the server by sending a lot of updates and deletes.\n\nIn each case, instead of sending each call separately, you can group them together into a single HTTP request. All the inner requests must go to the same Google API.\n\nYou're limited to 1000 calls in a single batch request. If you must make more calls than that, use multiple batch requests.\n\n**Note** : The batch system for the People API uses the same syntax as the [OData batch processing](http://www.odata.org/documentation/odata-version-3-0/batch-processing/) system, but the semantics differ.\n\n\nBatch details\n-------------\n\nA batch request consists of multiple API calls combined into one HTTP request, which can be sent to the `batchPath` specified in the [API discovery document](https://developers.google.com/discovery/v1/reference/apis). The default path is `/batch/`\u003cvar translate=\"no\"\u003eapi_name\u003c/var\u003e`/`\u003cvar translate=\"no\"\u003eapi_version\u003c/var\u003e. This section describes the batch syntax in detail; later, there's an [example](#example).\n\n**Note** : A set of \u003cvar translate=\"no\"\u003en\u003c/var\u003e requests batched together counts toward your usage limit as \u003cvar translate=\"no\"\u003en\u003c/var\u003e requests, not as one request. The batch request is separated into a set of requests before processing.\n\n### Format of a batch request\n\nA batch request is a single standard HTTP request containing multiple People API calls, using the `multipart/mixed` content type. Within that main HTTP request, each of the parts contains a nested HTTP request.\n\nEach part begins with its own `Content-Type: application/http` HTTP header. It can also have an optional `Content-ID` header. However, the part headers are just there to mark the beginning of the part; they're separate from the nested request. After the server unwraps the batch request into separate requests, the part headers are ignored.\n\nThe body of each part is a complete HTTP request, with its own verb, URL, headers, and body. The HTTP request must only contain the path portion of the URL; full URLs are not allowed in batch requests.\n\nThe HTTP headers for the outer batch request, except for the `Content-` headers such as `Content-Type`, apply to every request in the batch. If you specify a given HTTP header in both the outer request and an individual call, then the individual call header's value overrides the outer batch request header's value. The headers for an individual call apply only to that call.\n\nFor example, if you provide an Authorization header for a specific call, then that header applies only to that call. If you provide an Authorization header for the outer request, then that header applies to all of the individual calls unless they override it with Authorization headers of their own.\n\nWhen the server receives the batched request, it applies the outer request's query parameters and headers (as appropriate) to each part, and then treats each part as if it were a separate HTTP request.\n\n### Response to a batch request\n\nThe server's response is a single standard HTTP response with a `multipart/mixed` content type; each part is the response to one of the requests in the batched request, in the same order as the requests.\n\nLike the parts in the request, each response part contains a complete HTTP response, including a status code, headers, and body. And like the parts in the request, each response part is preceded by a `Content-Type` header that marks the beginning of the part.\n\nIf a given part of the request had a `Content-ID` header, then the corresponding part of the response has a matching `Content-ID` header, with the original value preceded by the string `response-`, as shown in the following example.\n\n**Note**: The server might perform your calls in any order. Don't count on their being executed in the order in which you specified them. If you want to ensure that two calls occur in a given order, you can't send them in a single request; instead, send the first one by itself, then wait for the response to the first one before sending the second one.\n\nExample\n-------\n\nThe following example shows the use of batching with the People API.\n\n### Example batch request\n\n```\nPOST /batch HTTP/1.1\naccept-encoding: gzip, deflate\nAuthorization: Bearer your_auth_token\nContent-Type: multipart/mixed; boundary=\"batch_people\"\nContent-Length: total_content_length\n\n--batch_people\nContent-Type: application/http\nContent-Transfer-Encoding: binary\nContent-ID: 1\n\nPOST /v1/people:createContact HTTP/1.1\nContent-Type: application/json\nContent-Length: \u003cvar translate=\"no\"\u003epart_content_length\u003c/var\u003e\nAccept: application/json\n{\n \"names\": [{ \"givenName\": \"John\", \"familyName\": \"Doe\" }]\n}\n\n--batch_people\nContent-Type: application/http\nContent-Transfer-Encoding: binary\nContent-ID: 2\n\nGET /v1/people/c123456789012345?personFields=emailAddresses HTTP/1.1\nAccept: application/json\n--batch_people--\n\n```\n\n### Example batch response\n\nThis is the response to the example request in the previous section. \n\n```\nHTTP/1.1 200 OK\nContent-Type: multipart/mixed; boundary=batch_GOMozbDceUiJkwfCeHo28pGmhwRG5o50\nDate: Tue, 22 Jan 2020 18:56:00 GMT\nExpires: Tue, 22 Jan 2020 18:56:00 GMT\nCache-Control: private\n\n--batch_GOMozbDceUiJkwfCeHo28pGmhwRG5o50\nContent-Type: application/http\nContent-ID: response-1\n\nHTTP/1.1 200 OK\nContent-Type: application/json; charset=UTF-8\n{\n \"resourceName\": \"people/c11111111111111\",\n \"etag\": \"1111\",\n \"names\": [{ \"givenName\": \"John\", \"familyName\": \"Doe\" }]\n}\n\n--batch_GOMozbDceUiJkwfCeHo28pGmhwRG5o50\nContent-Type: application/http\nContent-ID: response-2\n\nHTTP/1.1 200 OK\nContent-Type: application/json; charset=UTF-8\n{\n \"resourceName\": \"people/c123456789012345\",\n \"etag\": \"1234\",\n \"emailAddresses\": [{ \"value\": \"jane.doe@gmail.com\" }]\n}\n--batch_GOMozbDceUiJkwfCeHo28pGmhwRG5o50--\n\n```"]]
