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. Los ejemplos de esta página ilustran cómo algunos
operaciones de escritura comunes se pueden lograr con el
spreadsheets.values
de la API de Hojas de cálculo.
Ten en cuenta que también es posible escribir valores de celdas con la
spreadsheet.batchUpdate
que puede ser útil si quieres actualizar simultáneamente el formato de las celdas
u otras propiedades que
spreadsheets.values
recurso no afecta. Por ejemplo, si quieres copiar un rango de celdas de
una hoja a otra mientras se reemplazan la fórmula de celda y la celda
de formato, puedes usar el
UpdateCellsRequest
con un
spreadsheet.batchUpdate
Sin embargo, para escrituras de valores simples, es más fácil usar
spreadsheets.values.update
spreadsheets.values.batchUpdate
.
Estos ejemplos se presentan en forma de solicitudes HTTP como lenguaje neutrales. Para aprender a implementar escrituras en diferentes lenguajes con las bibliotecas cliente de la API de Google, consulta Leer y escribir celda de salida.
En estos ejemplos, el marcador de posición SPREADSHEET_ID
indica
con la que puedes agregar la hoja de cálculo
de la aplicación, que se puede descubrir desde
la URL de la hoja de cálculo. Los rangos en los que se escribirá se especifican con A1
notación estándar. Un rango de ejemplo es Hoja1!A1:D5.
Cómo escribir un solo rango
Comenzando con una nueva hoja de cálculo en blanco, los siguientes elementos
spreadsheets.values.update
de código muestra cómo escribir los valores en un rango. El
Búsqueda ValueInputOption
obligatorio y determina si los valores escritos se analizan (por
ejemplo, si una cadena se convierte en fecha).
El cuerpo de la solicitud es un
ValueRange
que describe los valores de rango que se escribirán. El
Campo majorDimension
indica que los arrays son listas de valores organizadas por filas. 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
UpdateValuesResponse
como el que se muestra a continuación:
{
"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 se escriben valores en un rango, es posible evitar cambiar algunos
celdas estableciendo los elementos correspondientes del array en null
. También es posible
para borrar una celda, escribe una cadena vacía (""
).
Comenzar con una hoja que contenga los mismos datos producidos por el método anterior
ejemplo, las siguientes
spreadsheets.values.update
la muestra de código indica cómo escribir los valores en el rango B1:D4, de forma selectiva
dejando algunas celdas sin modificar y borrando otras. El
Búsqueda ValueInputOption
obligatorio y determina si los valores escritos se analizan (por
ejemplo, si una cadena se convierte en fecha).
El cuerpo de la solicitud es un
ValueRange
que describe los valores de rango que se escribirán. El
Campo majorDimension
indica que los arrays 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 array null
elemento), mientras que se debe borrar B4 (cadena vacía). B2 y B3 tienen sus valores
se actualicen. La tercera matriz realiza las mismas operaciones en la columna D, mientras que la
una segunda matriz vacía indica que la columna C no debe modificarse.
La respuesta consta de un
UpdateValuesResponse
objeto 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 | $3.00 | 7 | 15/4/2016 |
Ten en cuenta que la columna "Totales" si bien esta solicitud no la modifica directamente, cambian porque sus celdas contienen fórmulas que dependen de las celdas alteradas.
Escribir en varios rangos
Comenzando con una hoja en blanco, lo siguiente
spreadsheets.values.batchUpdate
de código muestra cómo escribir los valores en los rangos Hoja1!A1:A4 y
Hoja1!B1:D2. Se reemplazan los valores existentes en el rango objetivo. La solicitud
body consta de un
ValueInputOption
que
muestra cómo interpretar los datos de entrada y un array de
ValueRange
objetos correspondientes a cada rango escrito. El
Campo majorDimension
determina si las matrices incluidas 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 consiste en un objeto que enumera las estadísticas actualizadas de las celdas
y un array de
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, lo siguiente
spreadsheets.values.update
de código muestra cómo escribir los valores en el rango Sheet1!A1:E1, pero utiliza
RAW
ValueInputOption
parámetro de consulta para evitar que las cadenas escritas se analicen como fórmulas,
booleanos o números. Aparecen como cadenas y se justifica la alineación del texto
en la hoja.
El cuerpo de la solicitud es un
ValueRange
que describe los valores de rango que se escribirán. El
Campo majorDimension
indica que los arrays son listas de valores organizadas por filas. 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
UpdateValuesResponse
objeto 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é centrada y es un valor booleano, mientras que "123.45" tiene razón justificado porque es un número, y "10" se justifica a la izquierda porque es un una cadena vacía. 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 |
Lo siguiente
spreadsheets.values.append
de código muestra cómo agregar dos filas de valores nuevas que comienzan con la fila 3. El
Búsqueda ValueInputOption
obligatorio y determina si los valores escritos se analizan (por
ejemplo, si una cadena se convierte en fecha).
El cuerpo de la solicitud es un
ValueRange
que describe los valores de rango que se escribirán. El
Campo majorDimension
indica que los arrays 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
AppendValuesResponse
objeto 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 |