Operaciones con hojas

La API de Hojas de cálculo de Google te permite crear, borrar, copiar y eliminar hojas, y también controlar sus propiedades. En los ejemplos de esta página, se ilustra cómo puedes realizar algunas operaciones comunes de Hojas de cálculo con la API de Sheets.

Estos ejemplos se presentan en forma de solicitudes HTTP para que sean independientes del lenguaje. Para obtener información sobre cómo implementar una actualización por lotes en diferentes lenguajes con las bibliotecas cliente de las APIs de Google, consulta Actualiza hojas de cálculo.

En estos ejemplos, los marcadores de posición SPREADSHEET_ID y SHEET_ID indican dónde proporcionarías esos IDs. Puedes encontrar el ID de la hoja de cálculo en la URL de la hoja de cálculo. Puedes obtener el ID de la hoja con el spreadsheets.get método. Los rangos se especifican con la notación A1. Un ejemplo de rango es Sheet1!A1:D5.

Cómo agregar una hoja

En el siguiente spreadsheets.batchUpdate ejemplo de código, se muestra cómo usar AddSheetRequest para agregar una hoja a una hoja de cálculo y, al mismo tiempo, establecer el título, el tamaño de la cuadrícula y el color de la pestaña.

La respuesta consta de un AddSheetResponse, que contiene un objeto con las propiedades de la hoja creada (como su SHEET_ID).

A continuación, se muestra el protocolo de solicitud.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate

{
  "requests": [
    {
      "addSheet": {
        "properties": {
          "title": "Deposits",
          "gridProperties": {
            "rowCount": 20,
            "columnCount": 12
          },
          "tabColor": {
            "red": 1.0,
            "green": 0.3,
            "blue": 0.4
          }
        }
      }
    }
  ]
}

Cómo borrar todos los valores de una hoja y conservar los formatos

En el siguiente spreadsheets.batchUpdate ejemplo de código, se muestra cómo usar UpdateCellsRequest para quitar todos los valores de una hoja y dejar el formato sin modificar.

Si se especifica el userEnteredValue campo sin un valor correspondiente, se interpreta como una instrucción para borrar los valores del rango. Esta configuración también se puede usar con otros campos. Por ejemplo, si cambias el valor fields a userEnteredFormat, se quitará todo el formato compatible con la API de Sheets de la hoja, pero los valores de las celdas no se modificarán.

A continuación, se muestra el protocolo de solicitud.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate

{
  "requests": [
    {
      "updateCells": {
        "range": {
          "sheetId": SHEET_ID
        },
        "fields": "userEnteredValue"
      }
    }
  ]
}

Cómo copiar una hoja de una hoja de cálculo a otra

En el siguiente spreadsheet.sheets.copyTo ejemplo de código, se muestra cómo copiar una sola hoja especificada por SHEET_ID de una hoja de cálculo a otra.

La variable TARGET_SPREADSHEET_ID en el cuerpo de la solicitud especifica la hoja de cálculo de destino. La copia conserva todos los valores, el formato, las fórmulas y otras propiedades del original. El título de la hoja copiada se establece en "Copia de [título de la hoja original]".

La respuesta consta de un SheetProperties objeto que describe las propiedades de la hoja creada.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/sheets/SHEET_ID:copyTo

{
  "destinationSpreadsheetId": "TARGET_SPREADSHEET_ID"
}

Cómo borrar una hoja

En el siguiente spreadsheets.batchUpdate ejemplo de código, se muestra cómo usar DeleteSheetRequest para borrar una hoja especificada por SHEET_ID.

A continuación, se muestra el protocolo de solicitud.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate

{
  "requests": [
    {
      "deleteSheet": {
        "sheetId": SHEET_ID
      }
    }
  ]
}

Cómo leer datos de la hoja

En el siguiente spreadsheets.get ejemplo de código se muestra cómo obtener información de las propiedades de la hoja de una hoja de cálculo, especificada por SHEET_ID y SPREADSHEET_ID. Este método se usa con frecuencia para determinar los metadatos de las hojas dentro de una hoja de cálculo específica, de modo que las operaciones adicionales puedan segmentar esas hojas. El parámetro de consulta fields especifica que solo se deben mostrar los datos de las propiedades de la hoja (en lugar de los datos de los valores de las celdas o los datos relacionados con toda la hoja de cálculo).

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID?&fields=sheets.properties

La respuesta consta de un Spreadsheet recurso, que contiene un Sheet objeto con SheetProperties elementos. Si un campo de respuesta determinado se establece en el valor predeterminado, se omite de la respuesta.

{
  "sheets": [
    {
      "properties": {
        "sheetId": SHEET_ID,
        "title": "Sheet1",
        "index": 0,
        "sheetType": "GRID",
        "gridProperties": {
          "rowCount": 100,
          "columnCount": 20,
          "frozenRowCount": 1
        }
        "tabColor": {
          "blue": 1.0
        }
      },
      ...
  ],
}