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 ilustra cómo se pueden lograr algunas operaciones de escritura comunes con el recurso spreadsheets.values de la API de Sheets.
Ten en cuenta que también es posible escribir valores de celdas con el método spreadsheet.batchUpdate, que puede ser útil si deseas actualizar simultáneamente el formato de las celdas o cualquier otra propiedad que no afecte el recurso spreadsheets.values. Por ejemplo, si deseas copiar un rango de celdas de una hoja a otra y sobrescribir la fórmula y el formato de las celdas, 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 sean independientes del idioma. Para obtener información sobre cómo implementar escrituras en diferentes lenguajes con las bibliotecas cliente de las APIs de Google, consulta Cómo leer y escribir valores de celdas.
En estos ejemplos, el marcador de posición SPREADSHEET_ID indica dónde debes proporcionar 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 escribirá se especifican con la notación A1. Un ejemplo de rango es Hoja1!A1:D5.
Escribe un solo rango
Comenzando con una hoja de cálculo nueva y en blanco, la siguiente muestra de código de spreadsheets.values.update muestra cómo escribir los valores en un rango. El parámetro de consulta ValueInputOption es obligatorio y determina si los valores escritos se analizan (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 arrays 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 ve de la siguiente manera:
| A | B | C | D | |
| 1 | Elemento | Costo | Surtido | 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 |
Escribe de forma selectiva en un rango
Cuando se escriben valores en un rango, es posible evitar el cambio de algunas celdas existentes si se configuran los elementos del array correspondientes en null. También es posible borrar una celda escribiendo una cadena vacía ("") en ella.
Comenzando con una hoja que contiene los mismos datos que produjo el ejemplo anterior, la siguiente muestra de código de spreadsheets.values.update muestra cómo escribir los valores en el rango B1:D4, dejando algunas celdas sin cambios y borrando otras de forma selectiva. El parámetro de consulta ValueInputOption es obligatorio y determina si los valores escritos se analizan (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 arrays 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 debe cambiar (debido al elemento del array null), mientras que B4 debe borrarse (cadena vacía). Los valores de B2 y B3 se actualizan. El tercer array realiza las mismas operaciones en la columna D, mientras que el segundo array vacío indica que la columna C debe permanecer sin cambios.
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 ve de la siguiente manera:
| A | B | C | D | |
| 1 | Elemento | Costo | Surtido | Fecha de envío |
| 2 | Rueda de la fortuna | $1.00 | 4 | 1/4/2016 |
| 3 | Puerta | $2 | 2 | 15/4/2016 |
| 4 | Motor | 1 | ||
| 5 | Totales | $3.00 | 7 | 15/4/2016 |
Ten en cuenta que la fila "Totales", si bien no se modifica directamente con esta solicitud, sí cambia porque sus celdas contienen fórmulas que dependen de las celdas alteradas.
Escribe en varios rangos
Comenzando con una hoja en blanco, el siguiente ejemplo de código de spreadsheets.values.batchUpdate muestra cómo escribir los valores en los rangos Sheet1!A1:A4 y Sheet1!B1:D2. Se reemplazarán los valores existentes en el rango de destino. 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 que corresponden 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 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 ve de la siguiente manera:
| A | B | C | D | |
| 1 | Elemento | Costo | Surtido | 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 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 está justificada 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.
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 ve 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 cadena. La fórmula no se analiza y también aparece como una cadena.
Valores agregados
Comienza con una hoja como la siguiente tabla:
| A | B | C | D | |
| 1 | Elemento | Costo | Surtido | Fecha de envío |
| 2 | Rueda de la fortuna | USD 20.50 | 4 | 1/3/2016 |
| 3 |
En el siguiente ejemplo de código de spreadsheets.values.append, se muestra 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 los valores escritos se analizan (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 arrays 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 ve de la siguiente manera:
| A | B | C | D | |
| 1 | Elemento | Costo | Surtido | 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 |