Escritura básica

La API de Google Sheets 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 lograr algunas operaciones de escritura comunes con el spreadsheets.values recurso de la API de Sheets.

Ten en cuenta que también es posible escribir valores de celdas con el spreadsheet.batchUpdate método, 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 reemplazar la fórmula y el formato de las celdas, puedes usar el UpdateCellsRequest método con un spreadsheet.batchUpdate.

Sin embargo, para escrituras de valores simples, es más fácil usar el spreadsheets.values.update método o el spreadsheets.values.batchUpdate método.

Estos ejemplos se presentan en forma de solicitudes HTTP para que sean independientes del lenguaje. Para obtener información sobre cómo implementar escrituras en diferentes lenguajes con las bibliotecas cliente de las APIs de Google, consulta Lee y escribe valores de celdas.

En estos ejemplos, el marcador de posición SPREADSHEET_ID indica dónde proporcionarías 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 escribirá se especifican con la notación A1. Un rango de ejemplo es Sheet1!A1:D5.

Escribe un solo rango

Comenzando con una hoja de cálculo nueva y en blanco, en el siguiente spreadsheets.values.update ejemplo de código, se muestra cómo escribir los valores en un rango. El ValueInputOption parámetro de consulta 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 ValueRange objeto que describe los valores de rango que se escribirán. El majorDimension campo indica que los arrays son listas de valores organizados por filas. Los valores existentes en el rango de destino 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 UpdateValuesResponse objeto, 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:

Escribe de forma 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 ella.

Comenzando con una hoja que contiene los mismos datos que produjo el ejemplo anterior, en la siguiente spreadsheets.values.update muestra de código, se muestra cómo escribir los valores en el rango B1:D4, dejando algunas celdas sin cambios y borrando otras de forma selectiva. El ValueInputOption parámetro de consulta 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 ValueRange objeto que describe los valores de rango que se escribirán. El majorDimension campo 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 modificarse (debido al elemento del array null), mientras que B4 debe borrarse (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 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 ve de la siguiente manera:

Ten en cuenta que la fila "Totales", aunque no se cambia directamente con esta solicitud, sí lo hace porque sus celdas contienen fórmulas que dependen de las celdas modificadas.

Escribe en varios rangos

Comenzando con una hoja en blanco, en la siguiente spreadsheets.values.batchUpdate muestra de código, se muestra cómo escribir los valores en los rangos Sheet1!A1:A4 y Sheet1!B1:D2. Los valores existentes en el rango de destino se reemplazan. El cuerpo de la solicitud consta de un ValueInputOptionobjeto que muestra cómo interpretar los datos de entrada y un array de ValueRange objetos correspondientes a cada rango escrito. El majorDimension campo 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 celdas actualizadas y un array de UpdateValuesResponse objetos, 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:

Escribe valores sin analizarlos

Comenzando con una hoja en blanco, en la siguiente spreadsheets.values.update muestra de código, 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, valores 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 ValueRange objeto que describe los valores de rango que se escribirán. El majorDimension campo indica que los arrays son listas de valores organizados por filas. Los valores existentes en el rango de destino 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 UpdateValuesResponse objeto 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:

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.

Agrega valores

Comienza con una hoja como la siguiente tabla:

En el siguiente spreadsheets.values.append muestra de código, se muestra cómo agregar dos filas nuevas de valores a partir de la fila 3. El ValueInputOption parámetro de consulta 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 ValueRange objeto que describe los valores de rango que se escribirán. El majorDimension campo 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 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 ve de la siguiente manera: