La API de Hojas de cálculo de Google te permite escribir valores y fórmulas en celdas, rangos, conjuntos de rangos y hojas enteras. En los ejemplos de esta página, se muestra cómo se pueden realizar algunas operaciones de escritura comunes con el recurso spreadsheets.values de la API de Hojas de cálculo.
Ten en cuenta que también es posible escribir valores de celdas con el método spreadsheet.batchUpdate, que puede resultar útil si quieres actualizar simultáneamente el formato de celda y otras propiedades que el recurso spreadsheets.values no afecta. Por ejemplo, si deseas copiar un rango de celdas de una hoja a otra mientras reemplazas la fórmula y el formato de la celda, puedes usar el método UpdateCellsRequest con un spreadsheet.batchUpdate.
Sin embargo, para las escrituras de valores simples, es más fácil usar el método spreadsheets.values.update o el método spreadsheets.values.batchUpdate.
Estos ejemplos se presentan en forma de solicitudes HTTP para que tengan lenguaje neutro. Para aprender a implementar operaciones de escritura en diferentes lenguajes con las bibliotecas cliente de la API de Google, consulta Cómo leer y escribir valores de celdas.
En estos ejemplos, el marcador de posición SPREADSHEET_ID indica dónde se proporciona el ID de la hoja de cálculo, que se puede encontrar en la URL de la hoja de cálculo. Los rangos en los que se debe escribir se especifican con la notación A1. Un rango de ejemplo es Hoja1!A1:D5.
Cómo escribir un solo rango
En la siguiente muestra de código spreadsheets.values.update, se muestra cómo escribir los valores en un rango, comenzando con una nueva hoja de cálculo en blanco. El parámetro de consulta ValueInputOption es obligatorio y determina si se analizan los valores escritos (por ejemplo, si una string se convierte en una fecha).
El cuerpo de la solicitud es un objeto ValueRange que describe los valores de los rangos que se escribirán. El campo majorDimension indica que los arreglos son listas de valores organizados por filas. Se reemplazan los valores existentes en el rango objetivo.
A continuación, se muestra el protocolo de solicitud.
PUT https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D5?valueInputOption=VALUE_INPUT_OPTION
{
"range": "Sheet1!A1:D5",
"majorDimension": "ROWS",
"values": [
["Item", "Cost", "Stocked", "Ship Date"],
["Wheel", "$20.50", "4", "3/1/2016"],
["Door", "$15", "2", "3/15/2016"],
["Engine", "$100", "1", "3/20/2016"],
["Totals", "=SUM(B2:B4)", "=SUM(C2:C4)", "=MAX(D2:D4)"]
],
}
La respuesta consta de un objeto UpdateValuesResponse, como el siguiente:
{
"spreadsheetId": SPREADSHEET_ID,
"updatedRange": "Sheet1!A1:D5",
"updatedRows": 5,
"updatedColumns": 4,
"updatedCells": 20,
}
La hoja resultante se verá de la siguiente manera:
| A | B | C | D | |
| 1 | Elemento | Costo | Almacenado | Fecha de envío |
| 2 | Rueda de la fortuna | USD 20.50 | 4 | 1/3/2016 |
| 3 | Puerta | $15 | 2 | 15/3/2016 |
| 4 | Engine | USD 100 | 1 | 20/3/2016 |
| 5 | Totales | $135.5 | 7 | 20/3/2016 |
Escribir en un rango de forma selectiva
Cuando escribes valores en un rango, es posible evitar la modificación de algunas celdas existentes si estableces los elementos del array correspondientes en null. También es posible borrar una celda si escribes una string vacía ("").
En la siguiente muestra de código spreadsheets.values.update, comenzando con una hoja que contiene los mismos datos producidos en el ejemplo anterior, se muestra cómo escribir los valores en el rango B1:D4, lo que deja algunas celdas sin cambios y borra otras de forma selectiva. El parámetro de consulta ValueInputOption es obligatorio y determina si se analizan los valores escritos (por ejemplo, si una string se convierte en una fecha).
El cuerpo de la solicitud es un objeto ValueRange que describe los valores de los rangos que se escribirán. El campo majorDimension indica que los arreglos son listas de valores organizados por columna.
A continuación, se muestra el protocolo de solicitud.
PUT https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!B1?valueInputOption=VALUE_INPUT_OPTION
{
"range": "Sheet1!B1",
"majorDimension": "COLUMNS",
"values": [
[null,"$1","$2", ""],
[],
[null,"4/1/2016", "4/15/2016", ""]
]
}
El campo values aquí enumera los cambios realizados en cada columna del rango. El primer array indica que B1 no se debe modificar (debido al elemento de array null), mientras que B4 se debe borrar (string vacía). B2 y B3 tienen sus valores actualizados. El tercer arreglo realiza las mismas operaciones en la columna D, mientras que el segundo arreglo vacío indica que la columna C no se debe modificar.
La respuesta consta de un objeto UpdateValuesResponse como el siguiente:
{
"spreadsheetId": SPREADSHEET_ID,
"updatedRange": "Sheet1!B1:D5",
"updatedRows": 3,
"updatedColumns": 2,
"updatedCells": 6,
}
La hoja resultante se verá de la siguiente manera:
| A | B | C | D | |
| 1 | Elemento | Costo | Almacenado | Fecha de envío |
| 2 | Rueda de la fortuna | $1.00 | 4 | 1/4/2016 |
| 3 | Puerta | $2 | 2 | 4/15/2016 |
| 4 | Engine | 1 | ||
| 5 | Totales | $3.00 | 7 | 4/15/2016 |
Ten en cuenta que, si bien esta solicitud no modifica directamente la fila "Totales", sí cambia porque sus celdas contienen fórmulas que dependen de las celdas alteradas.
Escribe en varios rangos
En la siguiente muestra de código spreadsheets.values.batchUpdate, comenzando con una hoja en blanco, se indica cómo escribir los valores en los rangos Sheet1!A1:A4 y Sheet1!B1:D2. Se reemplazan los valores existentes en el rango objetivo. El cuerpo de la solicitud consta de un objeto ValueInputOption que muestra cómo interpretar los datos de entrada y un array de objetos ValueRange correspondientes a cada rango escrito. El campo majorDimension determina si los arreglos incluidos se interpretan como arreglos de columnas o filas.
A continuación, se muestra el protocolo de solicitud.
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values:batchUpdate
{
"valueInputOption": "VALUE_INPUT_OPTION",
"data": [
{
"range": "Sheet1!A1:A4",
"majorDimension": "COLUMNS",
"values": [
["Item", "Wheel", "Door", "Engine"]
]
},
{
"range": "Sheet1!B1:D2",
"majorDimension": "ROWS",
"values": [
["Cost", "Stocked", "Ship Date"],
["$20.50", "4", "3/1/2016"]
]
}
]
}
La respuesta consta de un objeto que enumera las estadísticas de las celdas actualizadas y un arreglo de objetos UpdateValuesResponse, uno para cada rango actualizado. Por ejemplo:
{
"spreadsheetId": SPREADSHEET_ID,
"totalUpdatedRows": 4,
"totalUpdatedColumns": 4,
"totalUpdatedCells": 10,
"totalUpdatedSheets": 1,
"responses": [
{
"spreadsheetId": SPREADSHEET_ID,
"updatedRange": "Sheet1!A1:A4",
"updatedRows": 4,
"updatedColumns": 1,
"updatedCells": 4,
},
{
"spreadsheetId": SPREADSHEET_ID,
"updatedRange": "Sheet1!B1:D2",
"updatedRows": 2,
"updatedColumns": 3,
"updatedCells": 6,
}
],
}
La hoja resultante se verá de la siguiente manera:
| A | B | C | D | |
| 1 | Elemento | Costo | Almacenado | Fecha de envío |
| 2 | Rueda de la fortuna | USD 20.50 | 4 | 1/3/2016 |
| 3 | Puerta | |||
| 4 | Engine | |||
| 5 |
Escribe valores sin analizarlos
En la siguiente muestra de código spreadsheets.values.update, en una hoja en blanco, se indica cómo escribir los valores en el rango Sheet1!A1:E1, pero se usa el parámetro de consulta RAW ValueInputOption para evitar que las cadenas escritas se analicen como fórmulas, valores booleanos o números. Aparecen como cadenas y la alineación del texto se justifica en la hoja.
El cuerpo de la solicitud es un objeto ValueRange que describe los valores de los rangos que se escribirán. El campo majorDimension indica que los arreglos son listas de valores organizados por filas. Se reemplazan los valores existentes en el rango objetivo.
A continuación, se muestra el protocolo de solicitud.
PUT https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:E1?valueInputOption=RAW
{
"range": "Sheet1!A1:E1",
"majorDimension": "ROWS",
"values": [
["Data", 123.45, true, "=MAX(D2:D4)", "10"]
],
}
La respuesta consta de un objeto UpdateValuesResponse como el siguiente:
{
"spreadsheetId": SPREADSHEET_ID,
"updatedRange": "Sheet1!A1:E1",
"updatedRows": 1,
"updatedColumns": 5,
"updatedCells": 5,
}
La hoja resultante se verá de la siguiente manera:
| A | B | C | D | E | |
| 1 | Datos | 123.45 | TRUE | =MAX(D2:D4) | 10 |
| 2 |
Ten en cuenta que "TRUE" está centrado y es un valor booleano, mientras que "123.45" está justificado a la derecha porque es un número, y "10" está justificado a la izquierda porque es una string. La fórmula no se analiza y también aparece como una string.
Agregar valores
Comienza con una hoja como la de la siguiente tabla:
| A | B | C | D | |
| 1 | Elemento | Costo | Almacenado | Fecha de envío |
| 2 | Rueda de la fortuna | USD 20.50 | 4 | 1/3/2016 |
| 3 |
En la siguiente muestra de código de spreadsheets.values.append, se indica cómo agregar dos filas de valores nuevas a partir de la fila 3. El parámetro de consulta ValueInputOption es obligatorio y determina si se analizan los valores escritos (por ejemplo, si una string se convierte en una fecha).
El cuerpo de la solicitud es un objeto ValueRange que describe los valores de los rangos que se escribirán. El campo majorDimension indica que los arreglos son listas de valores organizados por filas.
A continuación, se muestra el protocolo de solicitud.
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:E1:append?valueInputOption=VALUE_INPUT_OPTION
{
"range": "Sheet1!A1:E1",
"majorDimension": "ROWS",
"values": [
["Door", "$15", "2", "3/15/2016"],
["Engine", "$100", "1", "3/20/2016"],
],
}
La respuesta consta de un objeto AppendValuesResponse como el siguiente:
{
"spreadsheetId": SPREADSHEET_ID,
"tableRange": "Sheet1!A1:D2",
"updates": {
"spreadsheetId": SPREADSHEET_ID,
"updatedRange": "Sheet1!A3:D4",
"updatedRows": 2,
"updatedColumns": 4,
"updatedCells": 8,
}
}
La hoja resultante se verá de la siguiente manera:
| A | B | C | D | |
| 1 | Elemento | Costo | Almacenado | Fecha de envío |
| 2 | Rueda de la fortuna | USD 20.50 | 4 | 1/3/2016 |
| 3 | Puerta | $15 | 2 | 15/3/2016 |
| 4 | Engine | USD 100 | 1 | 20/3/2016 |
| 5 |