Solicitudes por lotes

Organízate con las colecciones Guarda y clasifica el contenido según tus preferencias.

Descripción general

Cada conexión HTTP que realiza su cliente genera una cierta cantidad de gastos generales. La API de Compute Engine admite el procesamiento por lotes, para permitir que tu cliente coloque varias llamadas a la API en una sola solicitud HTTP.

Ejemplos de situaciones en las que es posible que desee utilizar el procesamiento por lotes:

• Acabas de empezar a utilizar la API y tienes muchos datos que cargar.
• Un usuario realizó cambios en los datos mientras su aplicación estaba fuera de línea (desconectada de Internet), por lo que su aplicación necesita sincronizar sus datos locales con el servidor enviando muchas actualizaciones y eliminaciones.

En cada caso, en lugar de enviar cada llamada por separado, puede agruparlas en una única solicitud HTTP. Todas las solicitudes internas deben ir a la misma API de Google.

Está limitado a 1000 llamadas en una sola solicitud por lotes. Si debe realizar más llamadas, utilice varias solicitudes por lotes.

Nota : El sistema por lotes para la API de Compute Engine usa la misma sintaxis que el sistema de procesamiento por lotes OData , pero la semántica difiere.

Detalles del lote

Una solicitud por lotes consta de varias llamadas API combinadas en una solicitud HTTP, que se puede enviar a la batchPath especificada en el documento de descubrimiento de API . La ruta predeterminada es /batch/ api_name / api_version . Esta sección describe la sintaxis por lotes en detalle; Más adelante, hay un ejemplo .

Nota : Un conjunto de n solicitudes agrupadas juntas cuentan para su límite de uso como n solicitudes, no como una sola solicitud. La solicitud por lotes se separa en un conjunto de solicitudes antes de procesarse.

Formato de una solicitud por lotes

Una solicitud por lotes es una única solicitud HTTP estándar que contiene varias llamadas a la API de Compute Engine y utiliza el tipo de contenido multipart/mixed . Dentro de esa solicitud HTTP principal, cada una de las partes contiene una solicitud HTTP anidada.

Cada parte comienza con su propio Content-Type: application/http . También puede tener un encabezado Content-ID opcional. Sin embargo, los encabezados de las partes sólo están ahí para marcar el comienzo de la parte; están separados de la solicitud anidada. Después de que el servidor descompone la solicitud por lotes en solicitudes separadas, los encabezados de las partes se ignoran.

El cuerpo de cada parte es una solicitud HTTP completa, con su propio verbo, URL, encabezados y cuerpo. La solicitud HTTP sólo debe contener la parte de la ruta de la URL; No se permiten URL completas en solicitudes por lotes.

Los encabezados HTTP para la solicitud por lotes externa, excepto los encabezados Content- como Content-Type , se aplican a todas las solicitudes del lote. Si especifica un encabezado HTTP determinado tanto en la solicitud externa como en una llamada individual, el valor del encabezado de la llamada individual anula el valor del encabezado de la solicitud por lotes externa. Los encabezados de una llamada individual se aplican únicamente a esa llamada.

Por ejemplo, si proporciona un encabezado de Autorización para una llamada específica, ese encabezado se aplica solo a esa llamada. Si proporciona un encabezado de Autorización para la solicitud externa, ese encabezado se aplica a todas las llamadas individuales a menos que lo anulen con sus propios encabezados de Autorización.

Cuando el servidor recibe la solicitud por lotes, aplica los parámetros de consulta y los encabezados de la solicitud externa (según corresponda) a cada parte y luego trata cada parte como si fuera una solicitud HTTP separada.

Respuesta a una solicitud por lotes

La respuesta del servidor es una única respuesta HTTP estándar con un tipo de contenido multipart/mixed ; cada parte es la respuesta a una de las solicitudes de la solicitud por lotes, en el mismo orden que las solicitudes.

Al igual que las partes de la solicitud, cada parte de la respuesta contiene una respuesta HTTP completa, incluido un código de estado, encabezados y cuerpo. Y al igual que las partes de la solicitud, cada parte de la respuesta está precedida por un encabezado Content-Type que marca el comienzo de la parte.

Si una parte determinada de la solicitud tenía un encabezado Content-ID , entonces la parte correspondiente de la respuesta tiene un encabezado Content-ID coincidente, con el valor original precedido por la cadena response- , como se muestra en el siguiente ejemplo.

Nota : el servidor puede realizar sus llamadas en cualquier orden. No cuente con que se ejecuten en el orden en que los especificó. Si desea asegurarse de que se realicen dos llamadas en un orden determinado, no puede enviarlas en una sola solicitud; en su lugar, envíe el primero solo y luego espere la respuesta al primero antes de enviar el segundo.

Ejemplo

El siguiente ejemplo muestra el uso de procesamiento por lotes con una API de demostración genérica (ficticia) llamada Farm API. Sin embargo, los mismos conceptos se aplican a la API de Compute Engine.

Ejemplo de solicitud por lotes

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--

Ejemplo de respuesta por lotes

Esta es la respuesta a la solicitud de ejemplo de la sección 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--