Rangos con nombre y protegidos

La API de Google Sheets te permite crear, modificar y borrar rangos con nombre o protegidos. En los ejemplos de esta página, se ilustra cómo puedes lograr 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 la API 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 rango de ejemplo es Sheet1!A1:D5.

Además, los marcadores de posición NAMED_RANGE_ID y PROTECTED_RANGE_ID proporcionan los IDs de los rangos con nombre y protegidos. Se usan namedRangeId y protectedRangeId cuando se realizan solicitudes para actualizar o borrar los rangos asociados. El ID se muestra en la respuesta a una solicitud de la API de Sheets que crea un rango con nombre o protegido. Puedes obtener los IDs de los rangos existentes con el spreadsheets.get método, en el Spreadsheet cuerpo de la respuesta.

Cómo agregar rangos con nombre o protegidos

En la siguiente spreadsheets.batchUpdate muestra de código, se muestra cómo usar 2 objetos de solicitud. El primero usa el AddNamedRangeRequest para asignar el nombre "Counts" al rango A1:E3. El segundo usa AddProtectedRangeRequest para adjuntar una protección de nivel de advertencia al rango A4:E4. Este nivel de protección aún permite editar las celdas dentro del rango, pero muestra una advertencia antes de realizar el cambio.

Estas solicitudes muestran un AddNamedRangeResponse y un AddProtectedRangeResponse, que contienen los IDs y las propiedades del rango.

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

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

{
  "requests": [
    {
      "addNamedRange": {
        "namedRange": {
          "name": "Counts",
          "range": {
            "sheetId": SHEET_ID,
            "startRowIndex": 0,
            "endRowIndex": 3,
            "startColumnIndex": 0,
            "endColumnIndex": 5,
          },
        }
      }
    },
    {
      "addProtectedRange": {
        "protectedRange": {
          "range": {
            "sheetId": SHEET_ID,
            "startRowIndex": 3,
            "endRowIndex": 4,
            "startColumnIndex": 0,
            "endColumnIndex": 5,
          },
          "description": "Protecting total row",
          "warningOnly": true
        }
      }
    }
  ]
}

Cómo borrar rangos con nombre o protegidos

En la siguiente spreadsheets.batchUpdate muestra de código, se muestra cómo usar 2 objetos de solicitud. El primero usa el DeleteNamedRangeRequest para borrar un rango con nombre existente, con el NAMED_RANGE_ID de una llamada anterior a la API. El segundo usa DeleteProtectedRangeRequest para borrar una protección de rango existente, con el PROTECTED_RANGE_ID de una llamada anterior a la API.

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

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

{
  "requests": [
    {
      "deleteNamedRange": {
          "namedRangeId": "NAMED_RANGE_ID",
      }
    },
    {
      "deleteProtectedRange": {
        "protectedRangeId": PROTECTED_RANGE_ID,
      }
    }
  ]
}

Cómo actualizar rangos con nombre o protegidos

En la siguiente spreadsheets.batchUpdate muestra de código, se muestra cómo usar 2 objetos de solicitud. El primero usa UpdateNamedRangeRequest para actualizar el nombre de un rango con nombre existente a "InitialCounts", con el NAMED_RANGE_ID de una llamada anterior a la API. El segundo usa el UpdateProtectedRangeRequest para actualizar un rango protegido existente de modo que ahora proteja el mismo rango con nombre. El Editors método permite que solo los usuarios enumerados editen esas celdas. Esta solicitud usa el NAMED_RANGE_ID y el PROTECTED_RANGE_ID de llamadas anteriores a la API.

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

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

{
  "requests": [
    {
      "updateNamedRange": {
        "namedRange": {
          "namedRangeId": NAMED_RANGE_ID,
          "name": "InitialCounts",
        },
        "fields": "name",
      }
    },
    {
      "updateProtectedRange": {
        "protectedRange": {
          "protectedRangeId": PROTECTED_RANGE_ID,
          "namedRangeId": NAMED_RANGE_ID,
          "warningOnly": false,
          "editors": {
            "users": [
              "charlie@example.com",
              "sasha@example.com"
            ]
          }
        },
        "fields": "namedRangeId,warningOnly,editors"
      }
    }
  ]
}