Pedidos em lote

Este documento mostra como agrupar chamadas da API para reduzir o número de ligações HTTP que o cliente tem de fazer.

Este documento aborda especificamente a criação de um pedido em lote através do envio de um pedido HTTP. Se, em alternativa, estiver a usar uma biblioteca cliente da Google para fazer um pedido em lote, consulte a documentação da biblioteca cliente.

Vista geral

Cada ligação HTTP que o seu cliente faz resulta numa determinada quantidade de sobrecarga. A API Compute Engine suporta o processamento em lote, o que permite ao cliente colocar várias chamadas API num único pedido HTTP.

Exemplos de situações em que pode querer usar o processamento em lote:

• Acabou de começar a usar a API e tem muitos dados para carregar.
• Um utilizador fez alterações aos dados enquanto a sua aplicação estava offline (sem ligação à Internet), pelo que a aplicação tem de sincronizar os respetivos dados locais com o servidor enviando muitas atualizações e eliminações.

Em cada caso, em vez de enviar cada chamada separadamente, pode agrupá-las numa única solicitação HTTP. Todos os pedidos internos têm de ser enviados para a mesma API Google.

Tem um limite de 1000 chamadas num único pedido em lote. Se tiver de fazer mais chamadas do que isso, use vários pedidos em lote.

Nota: o sistema de processamento em lote da API Compute Engine usa a mesma sintaxe que o sistema de processamento em lote OData, mas a semântica é diferente.

Detalhes do lote

Um pedido em lote consiste em várias chamadas API combinadas num pedido HTTP, que pode ser enviado para o batchPath especificado no documento de descoberta da API. O caminho predefinido é /batch/api_name/api_version. Esta secção descreve a sintaxe de lotes em detalhe. Mais adiante, encontra um exemplo.

Nota: um conjunto de pedidos agrupados conta para o seu limite de utilização como n pedidos e não como um pedido.n O pedido em lote é separado num conjunto de pedidos antes do processamento.

Formato de um pedido em lote

Um pedido em lote é um único pedido HTTP padrão que contém várias chamadas da API Compute Engine, usando o tipo de conteúdo multipart/mixed. Nesse pedido HTTP principal, cada uma das partes contém um pedido HTTP aninhado.

Cada parte começa com o seu próprio cabeçalho HTTP Content-Type: application/http. Também pode ter um cabeçalho Content-ID opcional. No entanto, os cabeçalhos das partes servem apenas para marcar o início da parte e estão separados do pedido aninhado. Depois de o servidor anular a união do pedido em lote em pedidos separados, os cabeçalhos das partes são ignorados.

O corpo de cada parte é um pedido HTTP completo, com o seu próprio verbo, URL, cabeçalhos e corpo. O pedido HTTP só pode conter a parte do caminho do URL. Não são permitidos URLs completos em pedidos em lote.

Os cabeçalhos HTTP do pedido em lote externo, exceto os cabeçalhos Content-, como Content-Type, aplicam-se a todos os pedidos no lote. Se especificar um determinado cabeçalho HTTP no pedido exterior e numa chamada individual, o valor do cabeçalho da chamada individual substitui o valor do cabeçalho do pedido em lote exterior. Os cabeçalhos de uma chamada individual aplicam-se apenas a essa chamada.

Por exemplo, se fornecer um cabeçalho de autorização para uma chamada específica, esse cabeçalho aplica-se apenas a essa chamada. Se fornecer um cabeçalho de autorização para o pedido externo, esse cabeçalho aplica-se a todas as chamadas individuais, a menos que o substituam pelos seus próprios cabeçalhos de autorização.

Quando o servidor recebe o pedido em lote, aplica os parâmetros de consulta e os cabeçalhos do pedido externo (conforme adequado) a cada parte e, em seguida, trata cada parte como se fosse um pedido HTTP separado.

Resposta a um pedido em lote

A resposta do servidor é uma única resposta HTTP padrão com um tipo de conteúdo multipart/mixed. Cada parte é a resposta a um dos pedidos no pedido em lote, na mesma ordem dos pedidos.

Tal como as partes no pedido, cada parte da resposta contém uma resposta HTTP completa, incluindo um código de estado, cabeçalhos e corpo. Tal como as partes no pedido, cada parte da resposta é precedida por um cabeçalho Content-Type que marca o início da parte.

Se uma determinada parte do pedido tiver um cabeçalho Content-ID, a parte correspondente da resposta tem um cabeçalho Content-ID correspondente, com o valor original precedido pela string response-, conforme mostrado no exemplo seguinte.

Nota: o servidor pode executar as suas chamadas por qualquer ordem. Não conte com a execução pela ordem em que as especificou. Se quiser garantir que duas chamadas ocorrem numa determinada ordem, não pode enviá-las num único pedido. Em alternativa, envie a primeira sozinha e, em seguida, aguarde a resposta à primeira antes de enviar a segunda.

Exemplo

O exemplo seguinte mostra a utilização do processamento em lote com uma API de demonstração genérica (fictícia) denominada API Farm. No entanto, os mesmos conceitos aplicam-se à API Compute Engine.

Exemplo de pedido em lote

POST /batch/farm/v1 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:[e-mail]>

GET /farm/v1/animals/pony

--batch_foobarbaz
Content-Type: application/http
Content-ID: <item2:[e-mail]>

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:[e-mail]>

GET /farm/v1/animals
If-None-Match: "etag/animals"

--batch_foobarbaz--

Exemplo de resposta em lote

Esta é a resposta ao pedido de exemplo na secçã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:[e-mail]>

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:[e-mail]>

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:[e-mail]>

HTTP/1.1 304 Not Modified
ETag: "etag/animals"

--batch_foobarbaz--