En este documento, se muestra cómo agrupar llamadas a la API para reducir la cantidad de conexiones que debe hacer el cliente. La agrupación en lotes puede mejorar la eficiencia de una aplicación, ya que disminuye los viajes de ida y vuelta de la red y aumenta la capacidad de procesamiento.
Descripción general
Cada conexión que realiza tu cliente genera una cierta cantidad de sobrecarga. La API de Hojas de cálculo de Google admite el procesamiento por lotes para permitir que tu cliente coloque varios objetos de solicitud, cada uno de los cuales especifica un solo tipo de solicitud para realizar, en una sola solicitud por lotes. Una solicitud por lotes puede mejorar el rendimiento, ya que combina varias subsolicitudes en una sola llamada al servidor y recupera una sola respuesta.
Recomendamos a los usuarios que siempre agrupen varias solicitudes. Estos son algunos ejemplos de situaciones en las que puedes usar el procesamiento por lotes:
- Recién empiezas a utilizar la API y tienes muchos datos para cargar.
- Necesitas actualizar los metadatos o las propiedades, como el formato, en varios objetos.
- Necesitas borrar muchos objetos.
Consideraciones sobre límites, autorización y dependencias
A continuación, se incluye una lista de otros elementos que debes tener en cuenta cuando utilices la actualización por lotes:
- Cada solicitud por lotes, incluidas todas las solicitudes secundarias, se considera como una solicitud a la API para tu límite de uso.
- Una solicitud por lotes se autentica una vez. Esta única autenticación se aplica a todos los objetos de actualización por lotes de la solicitud.
- El servidor procesa las solicitudes secundarias en el mismo orden en que aparecen en la solicitud por lotes. Las solicitudes secundarias posteriores pueden depender de las acciones que se realicen durante las solicitudes secundarias anteriores. Por ejemplo, en la misma solicitud por lotes, los usuarios pueden insertar texto en un documento existente y, luego, aplicarle un estilo.
Detalles del lote
Una solicitud por lotes consiste en una llamada al método batchUpdate con varias solicitudes secundarias para, por ejemplo, agregar y, luego, dar formato a una hoja de cálculo.
Cada solicitud se valida antes de aplicarse. Todas las solicitudes secundarias en la actualización por lotes se aplican de forma atómica. Es decir, si alguna solicitud no es válida, toda la actualización no se realizará correctamente y no se aplicará ninguno de los cambios (que podrían ser dependientes).
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 para que puedas acceder a los metadatos del objeto recién agregado, como el ID o el título.
Con este enfoque, puedes compilar un documento de Google completo con una solicitud de actualización por lotes de la API que incluya varias solicitudes secundarias.
Formato de una solicitud por lotes
Una solicitud es una sola solicitud JSON que contiene varias subsolicitudes anidadas con una propiedad obligatoria: requests. Las solicitudes se construyen en un array de solicitudes individuales. Cada solicitud usa JSON para representar el objeto de solicitud y contener sus propiedades.
Formato de una respuesta por lotes
El formato de la respuesta para una solicitud por lotes es similar al formato de la solicitud. La respuesta del servidor contiene una respuesta completa del objeto de respuesta único.
La propiedad del objeto JSON principal se llama replies. Las respuestas se muestran en un array, en el que 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 ese índice del array está vacía.
Ejemplo
En el siguiente ejemplo, se muestra el uso del procesamiento por lotes con la API de Sheets.
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, usandoAddSheetRequest. - Agrega datos a la hoja nueva, comenzando con la celda A1, usando
UpdateCellsRequest. - Agrega una
namedRangeo una vista de filtro a la hoja nueva.
Si agregas el ID de la hoja en la solicitud, los usuarios pueden usarlo 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 del í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
}
}
}
}
]