Organizar solicitudes por lotes

Información general

Las conexiones HTTP que hace tu cliente generan un determinado volumen de sobrecarga. La API Compute Engine admite el procesamiento por lotes, lo que permite que tu cliente incluya varias llamadas a la API en una sola solicitud HTTP.

Ejemplos de situaciones en las que puede ser útil usar el procesamiento por lotes:

• Acabas de empezar a usar la API y tienes muchos datos que subir.
• Un usuario ha modificado los datos mientras tu aplicación estaba sin conexión a Internet, por lo que tu aplicación debe sincronizar sus datos locales con el servidor enviando muchas actualizaciones y eliminaciones.

En cada caso, en lugar de enviar cada llamada por separado, puedes agruparlas en una sola solicitud HTTP. Todas las solicitudes internas deben dirigirse a la misma API de Google.

Tienes un límite de 1000 llamadas en una sola solicitud en lote. Si necesitas hacer más llamadas, usa varias solicitudes por lotes.

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

Detalles del lote

Una solicitud por lotes consta de varias llamadas a la API combinadas en una solicitud HTTP, que puede enviarse a la batchPath especificada en el documento de detección de la API. La ruta predeterminada es /batch/api_name/api_version. En esta sección se ofrece una descripción detallada de la sintaxis del lote y más adelante se incluye un ejemplo.

Nota: Un conjunto de n solicitudes agrupadas en un lote contabiliza de cara al límite de uso como n solicitudes, no como una única. La solicitud por lotes se divide en un conjunto de solicitudes antes de procesarse.

Formato de una solicitud en lote

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

Cada parte empieza con su propio encabezado HTTP Content-Type: application/http. También puede tener un Content-IDencabezado opcional. No obstante, la única finalidad de los encabezados de las partes es marcar el comienzo de cada una y separarla de la solicitud anidada. Después de que el servidor desglose la solicitud por lotes en solicitudes independientes, se ignoran los encabezados de las partes.

El cuerpo de cada parte es una solicitud HTTP completa, con su propio verbo, URL, encabezados y cuerpo. La solicitud HTTP solo debe contener la parte de la ruta de la URL. No se permiten URLs completas en las solicitudes en lote.

Los encabezados HTTP de la solicitud en lote 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 externa por lotes. Los encabezados de una llamada concreta solo se aplican a esa llamada.

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

Cuando el servidor recibe la solicitud agrupada, aplica los parámetros de consulta y las cabeceras de la solicitud externa (según corresponda) a cada parte y, a continuación, trata cada parte como si fuera una solicitud HTTP independiente.

Respuesta a una solicitud en lote

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 un cuerpo. Al igual que las partes de la solicitud, cada parte de la respuesta va precedida de un encabezado Content-Type que marca el inicio de la parte.

Si una parte de la solicitud tenía un encabezado Content-ID, 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 ejemplo siguiente.

Nota: El servidor puede realizar las llamadas en cualquier orden. y no en el que las has especificado. Si quieres asegurarte de que dos llamadas se realicen en un orden determinado, no puedes enviarlas en una sola solicitud. En su lugar, envía la primera por sí sola y, a continuación, espera la respuesta antes de enviar la segunda.

Ejemplo

En el siguiente ejemplo se muestra el uso de la creación de lotes con una API de demostración genérica (ficticia) llamada Farm API. Sin embargo, se pueden aplicar los mismos conceptos 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--