Escritura básica

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 una 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 una 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 una 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