En este documento, se describen los conceptos básicos del uso del
spreadsheets.batchUpdate
método en el
spreadsheets recurso.
Además de los datos de valor que contienen sus celdas, una hoja de cálculo incluye muchos otros tipos de datos, como los siguientes:
- Dimensiones
- Formatos y bordes de celdas
- Rangos con nombre
- Rangos protegidos
- Formato condicional
Estos son algunos de los muchos tipos de datos que controlan la apariencia y el funcionamiento de una hoja de cálculo. El método spreadsheets.batchUpdate te permite actualizar cualquiera de estos detalles de la hoja de cálculo. Los cambios se agrupan en un lote, de modo que, si una solicitud no se realiza correctamente, no se escriben los demás cambios (que podrían ser dependientes).
Si necesitas leer y escribir datos de valores de celdas, también puedes usar el
spreadsheets.values
recurso como se describe en Lee y escribe valores de celdas.
Tipos de operación
Las operaciones particulares admitidas por el método spreadsheets.batchUpdate se pueden agrupar en los siguientes tipos de operaciones generales:
| Categoría | Descripción |
|---|---|
| Agregar (y Duplicar) | Agrega objetos nuevos (a veces, basados en objetos antiguos, como en las solicitudes de duplicación). |
| Actualizar (y Establecer) | Actualiza ciertas propiedades de un objeto y, por lo general, deja las propiedades antiguas sin cambios (mientras que una solicitud de establecimiento reemplaza los datos anteriores). |
| Borrar | Quita objetos. |
Estas categorías se usan en la siguiente sección para describir el comportamiento de operaciones específicas.
Operaciones de actualización por lotes
El método spreadsheets.batchUpdate funciona tomando uno o más
Request
objetos, cada uno de los cuales especifica un solo tipo de solicitud para realizar. En la siguiente tabla, se enumeran los tipos de solicitudes de actualización por lotes, agrupados por objeto de recurso y tipo de operación:
Solicitudes de manipulación de datos
También hay algunas solicitudes adicionales que imitan las acciones del usuario para manipular datos:
| Solicitud | Descripción |
|---|---|
AutoFillRequest |
Completa automáticamente más datos en función de los datos existentes. |
CopyPasteRequest |
Copia datos de un área y los pega en otra. |
CutPasteRequest |
Corta datos de un área y los pega en otra. |
DeleteDuplicatesRequest |
Quita las filas que contienen valores duplicados en las columnas especificadas de un rango de celdas. |
FindReplaceRequest |
Busca y reemplaza las instancias de un texto por otro. |
PasteDataRequest |
Pega datos (HTML o delimitados) en una hoja. |
RandomizeRangeRequest |
Aleatoriza el orden de las filas en un rango. |
SortRangeRequest |
Ordena los datos en un rango. |
TextToColumnsRequest |
Convierte una columna de texto en muchas columnas de texto. |
TrimWhitespaceRequest |
Recorta las celdas de espacios en blanco (como espacios, tabulaciones o líneas nuevas). |
Para obtener más información sobre los límites de celdas y filas en Hojas de cálculo de Google, consulta Archivos que puedes almacenar en Google Drive.
Usa máscaras de campo para actualizar campos específicos
Muchas solicitudes de actualización requieren un FieldMask. Una máscara de campo es una lista de campos delimitada por comas que se usa para indicar qué campos de un objeto se deben actualizar, mientras que todos los demás campos permanecen sin cambios. El uso de una máscara de campo evita el reemplazo accidental de campos que no se especifican en la solicitud.
Para obtener más información sobre las máscaras de campo, consulta Actualiza con una máscara de campo.
En el siguiente ejemplo de código, se muestra cómo usar
UpdateSpreadsheetPropertiesRequest
para actualizar solo el título de una hoja de cálculo:
Solicitud
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
Cuerpo de la solicitud
{
"requests": [{
"updateSpreadsheetProperties": {
"properties": {"title": "TITLE"},
"fields": "title"
}
}]
}Reemplaza TITLE por el nuevo título de la hoja de cálculo.
Respuestas de actualización por lotes
Cuando actualizas una hoja de cálculo, algunos tipos de solicitudes pueden mostrar respuestas. Estas se muestran en un array, y cada respuesta ocupa el mismo índice que la solicitud correspondiente. Algunas solicitudes no tienen respuestas y, para esas, la respuesta está vacía.
Por lo general, las solicitudes de "agregar" tienen respuestas que muestran información, como el ID del objeto agregado. Para obtener la lista de respuestas admitidas, consulta
Responses.
Muestra de código: Actualización por lotes de una hoja de cálculo
En el siguiente ejemplo de muestra de código, se muestra cómo realizar estas acciones:
- Actualiza el título de la hoja de cálculo con la variable
title. - Busca y reemplaza los valores de las celdas en la hoja de cálculo con las variables
findyreplacement.