Este documento mostra como agrupar chamadas à API em lote para reduzir o número de conexões HTTP que o cliente precisa fazer.
Este documento é 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 em questão.
Visão geral
Cada conexão HTTP feita pelo cliente acarreta uma determinada sobrecarga. A Google Cloud Deployment Manager V2 API aceita operações em lote para permitir que o cliente faça diversas chamadas à API em uma única solicitação HTTP.
Exemplos de situações nas quais convém usar operações em lote:
- Você começou a usar API e tem muitos dados para fazer upload.
- Um usuário fez alterações nos dados enquanto o aplicativo estava off-line (desconectado da Internet), o que obriga o aplicativo a 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. Você pode até mesmo agrupar solicitações para vários usuários ou várias APIs do Google.
Existe a limitação 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 em lote da Google Cloud Deployment Manager V2 API 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 à API combinadas em uma única solicitação HTTP. Esta seção descreve detalhadamente a sintaxe do lote. Mais à frente, haverá um exemplo.
Observação: um conjunto de n solicitações em lote é contabilizado em relação ao limite de uso como n solicitações, e não como uma solicitação. A solicitação em lote é feita separadamente 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 contendo várias chamadas à Google Cloud Deployment Manager V2 API, usando o tipo de conteúdo multipart/mixed
. Dentro dessa solicitação HTTP principal, cada uma das partes contém uma solicitação HTTP aninhada.
Cada parte começa com seu próprio cabeçalho HTTP Content-Type: application/http
. Ela também pode 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 verbo, URL, cabeçalhos e corpo próprios. 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 só se aplicam a essa chamada.
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, ele se aplicará a todas as chamadas individuais, a menos que 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 resposta HTTP padrão única com um tipo de conteúdo multipart/mixed
. Cada parte é a 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 assim como 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, você não poderá enviá-las 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 Farm API. No entanto, os mesmos conceitos se aplicam à Google Cloud Deployment Manager V2 API.
Solicitação em lote de exemplo
POST /batch HTTP/1.1 Authorization: Bearer your_auth_token Host: www.googleapis.com Content-Type: multipart/mixed; boundary=batch_foobarbaz Content-Length: total_content_length --batch_foobarbaz Content-Type: application/http Content-ID: <item1:12930812@barnyard.example.com> GET /farm/v1/animals/pony --batch_foobarbaz Content-Type: application/http Content-ID: <item2:12930812@barnyard.example.com> PUT /farm/v1/animals/sheep Content-Type: application/json Content-Length: part_content_length If-Match: "etag/sheep" { "animalName": "sheep", "animalAge": "5" "peltColor": "green", } --batch_foobarbaz Content-Type: application/http Content-ID: <item3:12930812@barnyard.example.com> GET /farm/v1/animals If-None-Match: "etag/animals" --batch_foobarbaz--
Resposta em lote de exemplo
Esta é a resposta à solicitação de exemplo da seção anterior.
HTTP/1.1 200 Content-Length: response_total_content_length Content-Type: multipart/mixed; boundary=batch_foobarbaz --batch_foobarbaz Content-Type: application/http Content-ID: <response-item1:12930812@barnyard.example.com> HTTP/1.1 200 OK Content-Type application/json Content-Length: response_part_1_content_length ETag: "etag/pony" { "kind": "farm#animal", "etag": "etag/pony", "selfLink": "/farm/v1/animals/pony", "animalName": "pony", "animalAge": 34, "peltColor": "white" } --batch_foobarbaz Content-Type: application/http Content-ID: <response-item2:12930812@barnyard.example.com> HTTP/1.1 200 OK Content-Type: application/json Content-Length: response_part_2_content_length ETag: "etag/sheep" { "kind": "farm#animal", "etag": "etag/sheep", "selfLink": "/farm/v1/animals/sheep", "animalName": "sheep", "animalAge": 5, "peltColor": "green" } --batch_foobarbaz Content-Type: application/http Content-ID: <response-item3:12930812@barnyard.example.com> HTTP/1.1 304 Not Modified ETag: "etag/animals" --batch_foobarbaz--