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 spreadsheets.values.batchUpdate.
Estos ejemplos se presentan en forma de solicitudes HTTP para que tengan lenguaje neutral. Para aprender a implementar escrituras 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 descubrir desde la URL de la hoja de cálculo. Los rangos en los que se escribirá se especifican con la notación A1. Un rango de ejemplo es Hoja1!A1:D5.
Escribe un solo rango
En la siguiente muestra de código spreadsheets.values.update, empezando con una nueva hoja de cálculo en blanco, se indica cómo escribir los valores en un rango. El parámetro de consulta ValueInputOption es obligatorio y determina si se analizan los valores escritos (por ejemplo, si una cadena se convierte en una fecha o no).
El cuerpo de la solicitud es un objeto ValueRange que describe los valores de rango que se escribirán. El campo majorDimension indica que los arrays son listas de valores organizados por filas. Se reemplazan los valores existentes en el rango objetivo.
El protocolo de solicitud se muestra a continuación.
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 | Motor | USD 100 | 1 | 20/3/2016 |
| 5 | Totales | USD 135.5 | 7 | 20/3/2016 |
Escribir en un rango de manera selectiva
Cuando escribas valores en un rango, es posible evitar cambiar algunas celdas existentes si estableces los elementos correspondientes del array en null. También puedes borrar una celda si escribes una cadena vacía ("").
En la siguiente muestra de código de spreadsheets.values.update, comenzando por una que contiene los mismos datos producidos en el ejemplo anterior, se indica cómo escribir los valores en el rango B1:D4, lo que deja en forma selectiva algunas celdas sin modificar y borra otras. El parámetro de consulta ValueInputOption es obligatorio y determina si se analizan los valores escritos (por ejemplo, si una cadena se convierte en una fecha o no).
El cuerpo de la solicitud es un objeto ValueRange que describe los valores de rango que se escribirán. El campo majorDimension indica que los arrays son listas de valores organizados por columna.
El protocolo de solicitud se muestra a continuación.
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", ""]
]
}
En este campo, el campo values enumera los cambios que se hicieron a cada columna del rango. El primer array indica que B1 no se debe modificar (debido al elemento del array null), mientras que B4 se debe borrar (string vacía). Se actualizaron los valores de B2 y B3. 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 | USD 1.00 | 4 | 1/4/2016 |
| 3 | Puerta | $2 | 2 | 15/4/2016 |
| 4 | Motor | 1 | ||
| 5 | Totales | USD 3.00 | 7 | 15/4/2016 |
Ten en cuenta que, si bien esta solicitud no modifica directamente la fila "Totals", sí cambia porque sus celdas contienen fórmulas que dependen de las celdas alteradas.
Cómo escribir 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 arrays incluidos se interpretan como arrays de columnas o filas.
El protocolo de solicitud se muestra a continuación.
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 | Motor | |||
| 5 |
Escribe valores sin analizarlos
En la siguiente muestra de código spreadsheets.values.update, comenzando con una hoja en blanco, se indica cómo escribir los valores en el rango Sheet1!A1:E1, pero 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 rango que se escribirán. El campo majorDimension indica que los arrays son listas de valores organizados por filas. Se reemplazan los valores existentes en el rango objetivo.
El protocolo de solicitud se muestra a continuación.
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" se justifica a la izquierda porque es una cadena. 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 spreadsheets.values.append, se indica cómo agregar dos filas nuevas de valores 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 cadena se convierte en una fecha o no).
El cuerpo de la solicitud es un objeto ValueRange que describe los valores de rango que se escribirán. El campo majorDimension indica que los arrays son listas de valores organizados por filas.
El protocolo de solicitud se muestra a continuación.
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 | Motor | USD 100 | 1 | 20/3/2016 |
| 5 |