Mantieni tutto organizzato con le raccolte
Salva e classifica i contenuti in base alle tue preferenze.
Questo documento mostra come effettuare chiamate API in batch per ridurre il numero di connessioni HTTP
che il tuo client deve effettuare.
Questo documento riguarda nello specifico l'invio di una richiesta batch inviando una
richiesta HTTP. Se invece utilizzi una libreria client Google per inviare una richiesta batch, consulta la documentazione della libreria client.
Panoramica
Ogni connessione HTTP stabilita dal client comporta un determinato overhead. L'API Compute Engine supporta il raggruppamento in batch per consentire al client di inserire più chiamate API in una singola richiesta HTTP.
Esempi di situazioni in cui potresti voler utilizzare il raggruppamento in batch:
Hai appena iniziato a utilizzare l'API e hai molti dati da caricare.
Un utente ha apportato modifiche ai dati mentre la tua applicazione era offline (disconnessa da internet), quindi l'applicazione deve sincronizzare i dati locali con il server inviando molti aggiornamenti ed eliminazioni.
In ogni caso, anziché inviare ogni chiamata separatamente, puoi raggrupparle in un'unica richiesta HTTP. Tutte le richieste interne devono essere indirizzate alla stessa API di Google.
Hai un limite di 1000 chiamate in una singola richiesta batch. Se devi effettuare più chiamate, utilizza più richieste batch.
Nota: il sistema batch per l'API Compute Engine utilizza la stessa sintassi del sistema di elaborazione batch OData, ma la semantica è diversa.
Dettagli batch
Una richiesta batch è composta da più chiamate API combinate in un'unica richiesta HTTP, che può essere inviata al batchPath specificato nel documento di rilevamento API. Il percorso predefinito è /batch/api_name/api_version. Questa sezione descrive la sintassi batch in dettaglio; di seguito è riportato un esempio.
Nota: un insieme di n richieste raggruppate in batch viene conteggiato ai fini del limite di utilizzo come n richieste, non come una singola richiesta. La richiesta batch viene suddivisa in un insieme di richieste prima dell'elaborazione.
Formato di una richiesta batch
Una richiesta batch è una singola richiesta HTTP standard contenente più chiamate all'API Compute Engine, che utilizza il tipo di contenuto multipart/mixed. All'interno di questa richiesta HTTP principale, ciascuna delle parti contiene una richiesta HTTP nidificata.
Ogni parte inizia con la propria intestazione HTTP Content-Type: application/http. Può anche avere un'intestazione Content-ID facoltativa. Tuttavia, le intestazioni della parte servono solo a contrassegnare l'inizio della parte e sono separate dalla richiesta nidificata. Dopo che il server ha scomposto la richiesta batch in richieste separate, le intestazioni delle parti vengono ignorate.
Il corpo di ogni parte è una richiesta HTTP completa, con verbo, URL, intestazioni e corpo. La richiesta HTTP deve contenere solo la parte di percorso dell'URL; gli URL completi non sono consentiti nelle richieste batch.
Le intestazioni HTTP per la richiesta batch esterna, ad eccezione delle intestazioni Content- come Content-Type, si applicano a ogni richiesta del batch. Se specifichi una determinata intestazione HTTP sia nella richiesta esterna che in una singola chiamata, il valore dell'intestazione della singola chiamata esegue l'override del valore dell'intestazione della richiesta batch esterna. Le intestazioni di una singola chiamata si applicano solo a quella chiamata.
Ad esempio, se fornisci un'intestazione Autorizzazione per una chiamata specifica, questa intestazione si applica solo a quella chiamata. Se fornisci un'intestazione Autorizzazione per la richiesta esterna, questa intestazione si applica a tutte le singole chiamate, a meno che non eseguano l'override con intestazioni Autorizzazione proprie.
Quando il server riceve la richiesta raggruppata in batch, applica i parametri di query e le intestazioni della richiesta esterna (se opportuno) a ogni parte e poi tratta ogni parte come se fosse una richiesta HTTP separata.
Risposta a una richiesta batch
La risposta del server è una singola risposta HTTP standard con un tipo di contenuto multipart/mixed; ogni parte è la risposta a una delle richieste nella richiesta raggruppata in batch, nello stesso ordine delle richieste.
Come le parti della richiesta, ogni parte della risposta contiene una risposta HTTP completa, inclusi un codice di stato, le intestazioni e il corpo. Come le parti della richiesta, ogni parte della risposta è preceduta da un'intestazione Content-Type che ne indica l'inizio.
Se una determinata parte della richiesta aveva un'intestazione Content-ID, la parte corrispondente della risposta ha un'intestazione Content-ID corrispondente, con il valore originale preceduto dalla stringa response-, come mostrato nell'esempio seguente.
Nota: il server potrebbe eseguire le chiamate in qualsiasi ordine. Non aspettarti che vengano eseguite nell'ordine in cui le hai specificate. Se vuoi assicurarti che due chiamate vengano eseguite in un determinato ordine, non puoi inviarle in una singola richiesta; invia invece la prima da sola, quindi attendi la risposta prima di inviare la seconda.
Esempio
L'esempio seguente mostra l'utilizzo del raggruppamento in batch con un'API demo generica (fittizia) chiamata API Farm. Tuttavia, gli stessi concetti si applicano all'API Compute Engine.
[[["Facile da capire","easyToUnderstand","thumb-up"],["Il problema è stato risolto","solvedMyProblem","thumb-up"],["Altra","otherUp","thumb-up"]],[["Difficile da capire","hardToUnderstand","thumb-down"],["Informazioni o codice di esempio errati","incorrectInformationOrSampleCode","thumb-down"],["Mancano le informazioni o gli esempi di cui ho bisogno","missingTheInformationSamplesINeed","thumb-down"],["Problema di traduzione","translationIssue","thumb-down"],["Altra","otherDown","thumb-down"]],["Ultimo aggiornamento 2025-09-03 UTC."],[[["\u003cp\u003eBatching API calls reduces the number of HTTP connections needed by grouping multiple API calls into a single HTTP request, which is ideal for uploading large amounts of data or synchronizing local data with the server.\u003c/p\u003e\n"],["\u003cp\u003eBatch requests consist of multiple API calls sent to the same Google API, limited to a maximum of 1000 calls per batch, using the \u003ccode\u003emultipart/mixed\u003c/code\u003e content type to contain nested HTTP requests.\u003c/p\u003e\n"],["\u003cp\u003eThe headers of the outer batch request generally apply to all inner requests, but individual call headers can override these outer headers for specific parts.\u003c/p\u003e\n"],["\u003cp\u003eThe server's response to a batch request is also a single HTTP response with a \u003ccode\u003emultipart/mixed\u003c/code\u003e content type, containing responses to each batched request in the same order, where each part includes its own status code, headers, and body.\u003c/p\u003e\n"],["\u003cp\u003eThe order of execution of calls within a batch request is not guaranteed, so if a specific order of operations is required, you must send the calls in separate requests.\u003c/p\u003e\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 Compute Engine 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 Compute Engine 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 Compute Engine 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 a generic (fictional) demo API called the Farm API. However, the same concepts apply to the Compute Engine API.\n\n### Example batch request\n\n```\nPOST /batch/farm/v1 HTTP/1.1\nAuthorization: Bearer your_auth_token\nHost: www.googleapis.com\nContent-Type: multipart/mixed; boundary=batch_foobarbaz\nContent-Length: total_content_length\n\n--batch_foobarbaz\nContent-Type: application/http\nContent-ID: \u003citem1:12930812@barnyard.example.com\u003e\n\nGET /farm/v1/animals/pony\n\n--batch_foobarbaz\nContent-Type: application/http\nContent-ID: \u003citem2:12930812@barnyard.example.com\u003e\n\nPUT /farm/v1/animals/sheep\nContent-Type: application/json\nContent-Length: part_content_length\nIf-Match: \"etag/sheep\"\n\n{\n \"animalName\": \"sheep\",\n \"animalAge\": \"5\"\n \"peltColor\": \"green\",\n}\n\n--batch_foobarbaz\nContent-Type: application/http\nContent-ID: \u003citem3:12930812@barnyard.example.com\u003e\n\nGET /farm/v1/animals\nIf-None-Match: \"etag/animals\"\n\n--batch_foobarbaz--\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\nContent-Length: response_total_content_length\nContent-Type: multipart/mixed; boundary=batch_foobarbaz\n\n--batch_foobarbaz\nContent-Type: application/http\nContent-ID: \u003cresponse-item1:12930812@barnyard.example.com\u003e\n\nHTTP/1.1 200 OK\nContent-Type application/json\nContent-Length: response_part_1_content_length\nETag: \"etag/pony\"\n\n{\n \"kind\": \"farm#animal\",\n \"etag\": \"etag/pony\",\n \"selfLink\": \"/farm/v1/animals/pony\",\n \"animalName\": \"pony\",\n \"animalAge\": 34,\n \"peltColor\": \"white\"\n}\n\n--batch_foobarbaz\nContent-Type: application/http\nContent-ID: \u003cresponse-item2:12930812@barnyard.example.com\u003e\n\nHTTP/1.1 200 OK\nContent-Type: application/json\nContent-Length: response_part_2_content_length\nETag: \"etag/sheep\"\n\n{\n \"kind\": \"farm#animal\",\n \"etag\": \"etag/sheep\",\n \"selfLink\": \"/farm/v1/animals/sheep\",\n \"animalName\": \"sheep\",\n \"animalAge\": 5,\n \"peltColor\": \"green\"\n}\n\n--batch_foobarbaz\nContent-Type: application/http\nContent-ID: \u003cresponse-item3:12930812@barnyard.example.com\u003e\n\nHTTP/1.1 304 Not Modified\nETag: \"etag/animals\"\n\n--batch_foobarbaz--\n```"]]
