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 de la red, disminuyendo las idas y vueltas 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 Hojas de cálculo de Google admite el procesamiento por lotes para que el cliente coloque 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 múltiples subsolicitudes para, por ejemplo, agregar una hoja de cálculo 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, el 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 el siguiente ejemplo, se muestra el uso del procesamiento por lotes con la API de Hojas de cálculo.
Solicitud
En este ejemplo de solicitud por lotes, se muestra cómo hacer lo siguiente:
- Agrega una hoja a una hoja de cálculo existente, con un
sheetIdde 12345, medianteAddSheetRequest. - Agrega datos a la nueva hoja desde la celda A1 mediante
UpdateCellsRequest. - Agrega una
namedRangeo una vista de filtro a la hoja nueva.
Cuando se agrega el ID de la hoja en la solicitud, los usuarios pueden usar el ID de la hoja para otras subsolicitudes en la misma llamada a la API. Esto mejora el rendimiento, ya que evita un ciclo de escritura-lectura-escritura.
Para obtener una lista de los tipos de solicitudes de actualización por lotes, agrupados en diferentes categorías, consulta la tabla en Operaciones de actualización por lotes.
{
"requests":[
{
"addSheet":{
"properties":{
"sheetId":123456
}
}
},
{
"updateCells":{
"start":{
"sheetId":123456
},
"rows":[
{
"values":[
{
"userEnteredValue":{
"stringValue":"hello"
}
}
]
},
{
"values":[
{
"userEnteredValue":{
"stringValue":"world"
}
}
]
}
],
"fields":"userEnteredValue"
}
},
{
"addNamedRange":{
"namedRange":{
"name":"newRange",
"range":{
"sheetId":123456,
"endRowIndex":2
}
}
}
}
]
}
Respuesta
En este ejemplo de respuesta por lotes, se muestra información sobre cómo se aplicó cada subsolicitud dentro de la solicitud por lotes. Ten en cuenta que UpdateCellsRequest no contiene una respuesta, por lo que el valor de índice del array en [1] consta de llaves vacías.
"replies":[
{
"addSheet":{
"properties":{
"sheetId":123456,
"title":"Sheet3",
"index":2,
"sheetType":"GRID",
"gridProperties":{
"rowCount":1000,
"columnCount":26
}
}
}
},
{
},
{
"addNamedRange":{
"namedRange":{
"namedRangeId":"2104325079",
"name":"newRange",
"range":{
"sheetId":123456,
"startRowIndex":0,
"endRowIndex":2,
"startColumnIndex":0,
"endColumnIndex":26
}
}
}
}
]