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 la forma de realizar algunas operaciones comunes de escritura con el recurso spreadsheets.values de la API de Hojas de cálculo.
Ten en cuenta que también es posible escribir valores en celdas con el método spreadsheet.batchUpdate, que puede resultar útil si quieres actualizar, al mismo tiempo, el formato de la celda o otras propiedades que no afecta el recurso spreadsheets.values. Por ejemplo, si deseas copiar un rango de celdas de una hoja a otra y, al mismo tiempo, reemplazar la fórmula y el formato de la celda, puedes usar el método UpdateCellsRequest con un spreadsheet.batchUpdate.
Sin embargo, para la escritura 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 distintos lenguajes con las bibliotecas cliente de la Google API, consulta Cómo leer y escribir valores de celda.
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 descubrir en la URL de la hoja de cálculo. Los rangos en los que se realizará la escritura se especifican con la notación A1. Un ejemplo de rango es Hoja1!A1:D5.
Cómo escribir en un solo rango
A partir de una hoja de cálculo nueva en blanco, en la siguiente muestra de código de spreadsheets.values.update, se muestra 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).
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. Los valores existentes en el rango objetivo se reemplazan.
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 | En stock | 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 |
Cómo escribir de forma selectiva en un rango
Cuando escribas valores en un rango, es posible evitar la modificación de algunas celdas existentes si estableces los elementos correspondientes de la matriz en null. También es posible borrar una celda si se escribe una cadena vacía ("") en ella.
A partir de una hoja que contiene los mismos datos que se generaron en el ejemplo anterior, en la siguiente muestra de código spreadsheets.values.update, se muestra cómo escribir los valores en el rango B1:D4, dejando de forma selectiva algunas celdas 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 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", ""]
]
}
Aquí, el campo values enumera los cambios que se realizaron a cada columna en el rango. La primera matriz indica que B1 no se debe modificar (debido al elemento de la matriz null), mientras que B4 se debe borrar (cadena vacía). Se actualizan los valores de B2 y B3. La tercera matriz realiza las mismas operaciones en la columna D, mientras que la segunda matriz vacía 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 ve de la siguiente manera:
| A | B | C | D | |
| 1 | Elemento | Costo | En stock | 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 | $3.00 | 7 | 15/4/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.
Cómo escribir en varios rangos
En una hoja en blanco, el siguiente ejemplo de código spreadsheets.values.batchUpdate muestra cómo escribir los valores en los rangos Sheet1!A1:A4 y Sheet1!B1:D2. Si en el rango indicado existen valores, se sobrescribirán. 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.
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 una matriz 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 | En stock | Fecha de envío |
| 2 | Rueda de la fortuna | USD 20.50 | 4 | 1/3/2016 |
| 3 | Puerta | |||
| 4 | Motor | |||
| 5 |
Cómo escribir valores sin analizarlos
En una hoja en blanco, en la siguiente muestra de código spreadsheets.values.update, se muestra 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, números o valores booleanos. 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. Los valores existentes en el rango objetivo se reemplazan.
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 “VERDADERO” 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.
Cómo agregar valores
Comienza con una hoja como la siguiente tabla:
| A | B | C | D | |
| 1 | Elemento | Costo | En stock | 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 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 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 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 | En stock | 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 |