Mantenha tudo organizado com as coleções
Salve e categorize o conteúdo com base nas suas preferências.
Este documento mostra como reunir chamadas à API em lote para reduzir o número de conexões HTTP que seu cliente tem que fazer.
Neste documento, falamos especificamente sobre como fazer uma solicitação em lote enviando uma solicitação HTTP. Se, em vez disso, você estiver usando uma biblioteca de cliente do Google para fazer uma solicitação em lote, consulte a documentação da biblioteca de cliente (em inglês).
Visão geral
Cada conexão HTTP feita pelo cliente resulta em certa quantidade de overhead. A API Compute Engine é compatível com operações em lote. Isso permite que o cliente faça várias chamadas à API em uma única solicitação HTTP.
Estes são exemplos de situações em que você pode usar as operações em lote:
Você acabou de começar a usar a API e tem muitos dados para fazer upload.
Um usuário fez alterações nos dados enquanto eu aplicativo estava off-line (desconectado da Internet), então seu aplicativo precisa sincronizar os dados locais com o servidor enviando várias atualizações e exclusões.
Em cada caso, em vez de enviar cada chamada separadamente, você pode agrupá-las em uma única solicitação HTTP. Todas as solicitações internas precisam ser encaminhadas para a mesma API do Google.
O limite é de 1.000 chamadas em uma única solicitação em lote. Se precisar fazer mais chamadas, use várias solicitações em lote.
Observação: o sistema de lote da API Compute Engine usa a mesma sintaxe do sistema de processamento em lote OData, mas a semântica é diferente.
Detalhes do lote
Uma solicitação em lote consiste em várias chamadas de API combinadas em uma solicitação HTTP, que pode ser enviada ao batchPath especificado no documento de descoberta de API (em inglês). O caminho padrão é /batch/api_name/api_version. Nesta seção, você verá a descrição em detalhes da sintaxe do lote e, em seguida, um exemplo.
Observação: um conjunto de n solicitações em lote é contabilizado no seu limite de uso, como n solicitações, e não como uma única solicitação. A solicitação em lote é separada em um conjunto de solicitações antes do processamento.
Formato de uma solicitação em lote
Uma solicitação em lote é uma única solicitação HTTP padrão que contém várias chamadas da API Compute Engine usando o tipo de conteúdo multipart/mixed. Dentro dessa solicitação HTTP principal, cada parte contém uma solicitação HTTP aninhada.
Cada parte começa com seu próprio cabeçalho HTTP Content-Type: application/http. Também é possível ter um cabeçalho Content-ID opcional. No entanto, os cabeçalhos das partes estão lá apenas para marcar o início da parte. Eles são separados da solicitação aninhada. Depois que o servidor desencapsular a solicitação em solicitações separadas, os cabeçalhos das partes serão ignorados.
O corpo de cada parte é uma solicitação HTTP completa, com o próprio verbo, URL, cabeçalhos e corpo. A solicitação HTTP precisa conter apenas a parte do caminho do URL. URLs completos não são permitidos em solicitações em lote.
Os cabeçalhos HTTP da solicitação em lote externa, exceto os cabeçalhos Content-, como Content-Type, aplicam-se a todas as solicitações no lote. Se você especificar um determinado cabeçalho HTTP na solicitação externa e em uma chamada individual, o valor do cabeçalho da chamada individual substituirá o valor do cabeçalho da solicitação em lote externa. Os cabeçalhos de uma chamada individual aplicam-se somente a ela.
Por exemplo, se você fornecer um cabeçalho de autorização para uma chamada específica, esse cabeçalho só se aplicará a essa chamada. Se você fornecer um cabeçalho de autorização para a solicitação externa, esse cabeçalho se aplicará a todas as chamadas individuais, a menos que ele seja substituído por cabeçalhos de autorização próprios.
Ao receber a solicitação em lote, o servidor aplica os parâmetros e os cabeçalhos de consulta da solicitação externa (conforme apropriado) a cada parte e trata cada parte como se fosse uma solicitação HTTP separada.
Resposta a uma solicitação em lote
A resposta do servidor é uma única resposta HTTP padrão com um tipo de conteúdo multipart/mixed. Cada parte refere-se à resposta a uma das solicitações na solicitação em lote, na mesma ordem das solicitações.
Assim como as partes na solicitação, cada parte da resposta contém uma resposta HTTP completa, inclusive código de status, cabeçalhos e corpo. E da mesma forma que as partes na solicitação, cada parte da resposta é precedida por um cabeçalho Content-Type que marca o início da parte.
Se uma determinada parte da solicitação tiver um cabeçalho Content-ID, a parte correspondente da resposta terá um cabeçalho Content-ID correspondente, com o valor original precedido pela string response-, conforme mostrado no exemplo a seguir.
Observação: o servidor pode realizar as chamadas em qualquer ordem. Não conte com a execução delas na ordem especificada. Se quiser garantir que duas chamadas ocorram em uma determinada ordem, não as envie em uma única solicitação. Em vez disso, envie a primeira e aguarde a resposta antes de enviar a segunda.
Exemplo
O exemplo a seguir mostra o uso de lotes com uma API de demonstração genérica (fictícia), chamada de API Farm. No entanto, os mesmos conceitos se aplicam à API Compute Engine.
[[["Fácil de entender","easyToUnderstand","thumb-up"],["Meu problema foi resolvido","solvedMyProblem","thumb-up"],["Outro","otherUp","thumb-up"]],[["Difícil de entender","hardToUnderstand","thumb-down"],["Informações incorretas ou exemplo de código","incorrectInformationOrSampleCode","thumb-down"],["Não contém as informações/amostras de que eu preciso","missingTheInformationSamplesINeed","thumb-down"],["Problema na tradução","translationIssue","thumb-down"],["Outro","otherDown","thumb-down"]],["Última atualização 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```"]]
