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 completas. En los ejemplos de esta página, se muestra cómo se pueden lograr algunas operaciones de escritura comunes con el recurso spreadsheets.values de la API de Hojas de cálculo.

Ten en cuenta que también es posible escribir valores de celda con el método spreadsheet.batchUpdate, lo que puede ser útil si deseas actualizar simultáneamente el formato de celda o alguna otra propiedad que no afecte el recurso spreadsheets.values. Por ejemplo, si quieres 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 las operaciones de 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 sean neutrales en cuanto al idioma. Para obtener información sobre cómo implementar operaciones de escritura en diferentes lenguajes con las bibliotecas cliente de la API de Google, 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 a partir de 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.

Cómo escribir 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 este:

{
  "spreadsheetId": SPREADSHEET_ID,
  "updatedRange": "Sheet1!A1:D5",
  "updatedRows": 5,
  "updatedColumns": 4,
  "updatedCells": 20,
}

La hoja resultante se ve de la siguiente manera:

Cómo escribir de forma selectiva en un rango

Cuando se escriben valores en un rango, es posible evitar cambiar algunas celdas existentes si se establecen los elementos del array correspondientes en null. También es posible borrar una celda escribiendo una cadena vacía ("") en ella.

A partir de una hoja que contiene los mismos datos que genera 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", ""]
  ]
}

En el campo values, se enumeran 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 se debe borrar (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 objeto UpdateValuesResponse como este:

{
  "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, si bien esta solicitud no cambia directamente la fila "Totales", sí cambia porque sus celdas contienen fórmulas que dependen de las celdas alteradas.

Cómo escribir en varios rangos

A partir de una hoja en blanco, en el siguiente fragmento de código de spreadsheets.values.batchUpdate, se 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. El cuerpo de la solicitud consiste en 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 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:

Cómo escribir valores sin analizar

A partir de una hoja en blanco, en la siguiente muestra de código spreadsheets.values.update, se muestra cómo escribir los valores en el rango Hoja1!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 este:

{
  "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 “VERDADERO” está centrado y es un valor booleano, mientras que “123.45” está centrado a la derecha porque es un número, y “10” está centrado 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:

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 este:

{
  "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: