La API de Hojas de cálculo de Google te permite escribir valores y fórmulas en celdas, rangos, conjuntos de rangos y hojas completas. 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 celda con el método spreadsheet.batchUpdate, lo que puede ser útil si quieres actualizar de forma simultánea el formato de la celda o cualquier otra propiedad que el recurso spreadsheets.values no afecte. Por ejemplo, si deseas copiar un rango de celdas de una hoja a otra y reemplazar tanto la fórmula como 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 los métodos spreadsheets.values.update o spreadsheets.values.batchUpdate.
Estos ejemplos se presentan en forma de solicitudes HTTP para que tengan lenguaje neutro. Para aprender a implementar escrituras en diferentes lenguajes con las bibliotecas cliente de la API de Google, consulta Lee y escribe valores de celda.
En estos ejemplos, el marcador de posición SPREADSHEET_ID indica dónde se debe proporcionar el ID de la hoja de cálculo, que se puede descubrir 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 a partir de 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 cadena se convierte en una fecha).
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 arreglos son listas de valores organizadas 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 de manera selectiva en un rango
Cuando escribes valores en un rango, es posible evitar cambiar algunas celdas existentes si configuras los elementos del array correspondientes en null. También es posible borrar una celda si escribes una cadena vacía ("").
En la siguiente muestra de código de spreadsheets.values.update, se comienza con una hoja que contiene los mismos datos producidos en el ejemplo anterior y se indica cómo escribir los valores en el rango B1:D4, dejando algunas celdas de forma selectiva sin cambios y borrando 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).
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 arreglos son listas de valores organizadas 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 el campo values, se enumeran los cambios realizados en 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 (cadena vacía). B2 y B3 tienen sus valores actualizados. El tercer array realiza las mismas operaciones en la columna D, mientras que el segundo array vacío indica que la columna C no se 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 la fila "Totales", aunque esta solicitud no la modifica directamente, sí cambia porque sus celdas contienen fórmulas que dependen de las celdas modificadas.
Escribir en varios rangos
Comenzando con una hoja en blanco, la siguiente muestra de código spreadsheets.values.batchUpdate indica cómo escribir los valores en los rangos Sheet1!A1:A4 y Sheets1!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.
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 array 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
Comenzando con una hoja en blanco, la siguiente muestra de código spreadsheets.values.update muestra cómo escribir los valores en el rango Sheet1!A1:E1, pero usa el parámetro de búsqueda RAW ValueInputOption para evitar que las strings escritas se analicen como fórmulas, 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 arreglos son listas de valores organizadas 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 | Precio de | 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 cadena. La fórmula no se analiza y también aparece como una cadena.
Agregar valores
Comienza con una hoja como la que se muestra en 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 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).
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 arreglos son listas de valores organizadas 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 |