Este documento muestra cómo agrupar llamadas a la API para reducir la cantidad de conexiones que debe establecer el cliente. La agrupación en lotes puede mejorar el rendimiento la eficiencia de la red reduciendo la cantidad de ida y vuelta de la red y aumentando la capacidad de procesamiento.
Descripción general
Cada conexión que realiza tu cliente da como resultado una cierta cantidad de sobrecarga. La API de Documentos de Google admite el procesamiento por lotes para que el cliente pueda colocar varias Objetos Request, cada uno especifica un solo tipo de solicitud para realizar, en una única solicitud por lotes. Una solicitud por lotes puede mejorar el rendimiento combinando múltiples subsolicitudes en una única llamada al servidor, recuperando ni una sola respuesta.
Recomendamos a los usuarios que siempre agrupen varias solicitudes. Estos son algunos ejemplos ejemplos de situaciones en las que puedes usar el procesamiento por lotes:
- Acabas de empezar a usar la API y tienes muchos datos para subir.
- Debes actualizar metadatos o propiedades, como el formato, en varios objetos.
- Debes borrar muchos objetos.
Límites, autorización y consideraciones de dependencia
Esta es una lista de otros elementos que debes tener en cuenta cuando se emplea la actualización por lotes:
- Cada solicitud por lotes, incluidas todas las subsolicitudes, se cuenta como una API. para tu límite de uso.
- Una solicitud por lotes se autentica una vez. Esta autenticación única se aplica a todos los objetos de actualización por lotes de la solicitud.
- El servidor procesa las subsolicitudes en el mismo orden en que aparecen en la por lotes. Las últimas subsolicitudes pueden depender de las acciones realizadas durante las subsolicitudes anteriores. Por ejemplo, en la misma solicitud por lotes, los usuarios pueden insertar texto en un documento existente y darle estilo.
Detalles del lote
Una solicitud por lotes consta de una llamada al método batchUpdate
con varias solicitudes secundarias, por ejemplo, para agregar un documento y darle formato.
Cada solicitud se valida antes de aplicarse. Todas las subsolicitudes del lote update se aplican de forma atómica. Es decir, si alguna solicitud no es válida, la actualización no se realiza de forma correcta y ninguna de las (posiblemente dependientes) de que se apliquen los cambios.
Algunas solicitudes proporcionan respuestas con información sobre las solicitudes aplicadas. Por ejemplo, todas las solicitudes de actualización por lotes para agregar objetos devuelven respuestas Puedes acceder a los metadatos del objeto agregado recientemente, como el ID o título.
Con este enfoque, puedes crear todo un documento de Google usando una API. una solicitud de actualización por lotes con varias solicitudes secundarias.
Formato de una solicitud por lotes
Una solicitud es una solicitud JSON única que contiene múltiples,
subsolicitudes anidadas con una propiedad obligatoria: requests
. El
Las solicitudes se construyen en un array de solicitudes individuales. Cada solicitud utiliza
JSON para representar el objeto de solicitud y contener sus propiedades.
Formato de una respuesta por lotes
El formato de respuesta para una solicitud por lotes es similar al el formato de la solicitud. La respuesta del servidor contiene una respuesta completa del único objeto de respuesta.
La propiedad principal del objeto JSON se llama replies
. Las respuestas
se muestran en un array, y cada respuesta a una de las solicitudes ocupa
el mismo orden de índice que la solicitud correspondiente. Algunas solicitudes no tienen
respuestas y la respuesta en el índice
del array está vacía.
Ejemplo
En la siguiente muestra de código, se puede apreciar cómo usar la agrupación en lotes con la API de Documentos.
Solicitud
En este ejemplo de solicitud por lotes, se muestra cómo hacer lo siguiente:
Insertar “Hello World” texto en el inicio de un documento existente, con una índice
location
de1
mediante elInsertTextRequest
Actualizar la palabra “Hola” con el
UpdateTextStyleRequest
startIndex
yendIndex
definen larange
del texto con formato dentro segmento.Con
textStyle
, establece el estilo de fuente en negrita y el color en azul solo la palabra “Hello”.Con
WriteControl
puedes controlar cómo se ejecutan las solicitudes de escritura. Para ver más consulta Establece coherencia de estado con WriteControl.
{ "requests":[ { "insertText":{ "location":{ "index":1, "tabId":TAB_ID }, "text":"Hello World" } }, { "updateTextStyle":{ "range":{ "startIndex":1, "endIndex":6 }, "textStyle":{ "bold":true, "foregroundColor":{ "color":{ "rgbColor":{ "blue":1 } } } }, "fields":"bold,foreground_color" } } ], "writeControl": { "requiredRevisionId": "REQUIRED_REVISION_ID" } }
Reemplaza TAB_ID y REQUIRED_REVISION_ID por el ID de la pestaña y el ID de revisión, respectivamente, del documento en el que se encuentra la solicitud de escritura a la que se aplica el filtro.
Respuesta
Este ejemplo de respuesta por lotes muestra información sobre cómo cada subsolicitud en
se aplicó la solicitud por lotes. Ni
InsertTextRequest
o el
UpdateTextStyleRequest
contienen una respuesta, por lo que los valores de índice del array en [0] y [1] coinciden
de llaves vacías. La solicitud por lotes muestra el objeto WriteControl
.
que muestra cómo se ejecutaron las solicitudes.
{ "replies":[ {}, {} ], "writeControl":{ "requiredRevisionId":`REQUIRED_REVISION_ID` }, "documentId":`DOCUMENT_ID` }