Solicitações em lote

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Visão geral

Cada conexão HTTP que seu cliente faz resulta em uma certa sobrecarga. A API Compute Engine oferece suporte a lotes para permitir que seu cliente coloque várias chamadas de API em uma única solicitação HTTP.

Exemplos de situações em que você pode querer usar lotes:

• 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 seu aplicativo estava offline (desconectado da Internet); portanto, seu aplicativo precisa sincronizar seus dados locais com o servidor, enviando muitas 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 devem ir para a mesma API do Google.

Você está limitado a 1.000 chamadas em uma única solicitação em lote. Se você precisar fazer mais chamadas do que isso, use diversas solicitações em lote.

Observação : o sistema em 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 para o batchPath especificado no documento de descoberta de API . O caminho padrão é /batch/ api_name / api_version . Esta seção descreve detalhadamente a sintaxe do lote; mais tarde, há um exemplo .

Observação : um conjunto de n solicitações agrupadas conta para seu limite de uso como n solicitações, 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 solicitação HTTP padrão única que contém várias chamadas de API do Compute Engine, 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 Content-Type: application/http HTTP. Também pode ter um cabeçalho Content-ID opcional. Entretanto, os cabeçalhos das peças existem apenas para marcar o início da peça; eles estão separados da solicitação aninhada. Depois que o servidor desembrulha a solicitação em lote em solicitações separadas, os cabeçalhos das partes sã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 deve conter apenas a parte do caminho da URL; URLs completos não são permitidos em solicitações em lote.

Os cabeçalhos HTTP para a solicitação de lote externa, exceto os cabeçalhos Content- como Content-Type , aplicam-se a todas as solicitações do 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 externa em lote. Os cabeçalhos de uma chamada individual aplicam-se somente a essa chamada.

Por exemplo, se você fornecer um cabeçalho Authorization para uma chamada específica, esse cabeçalho se aplicará somente 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 elas o substituam por cabeçalhos de autorização próprios.

Quando o servidor recebe a solicitação em lote, ele aplica os parâmetros de consulta e cabeçalhos da solicitação externa (conforme apropriado) a cada parte e, em seguida, 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 da solicitação em lote, na mesma ordem das solicitações.

Assim como as partes da solicitação, cada parte da resposta contém uma resposta HTTP completa, incluindo um código de status, cabeçalhos e corpo. E como as partes da 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.

Nota : O servidor pode realizar suas chamadas em qualquer ordem. Não conte com a execução deles na ordem em que você os especificou. 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 o primeiro sozinho e aguarde a resposta do primeiro antes de enviar o segundo.

Exemplo

O exemplo a seguir mostra o uso de lote com uma API de demonstração genérica (fictícia) chamada Farm API. No entanto, os mesmos conceitos se aplicam à API Compute Engine.

Exemplo de solicitação 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: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--

Exemplo de resposta em lote

Esta é a resposta à solicitação de exemplo na 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--