Intervalos protegidos e nomeados

Com a API Google Sheets, você pode criar, modificar e excluir intervalos nomeados ou protegidos. Os exemplos nesta página ilustram como realizar algumas operações comuns do Google Sheets com a API Sheets.

Esses exemplos são apresentados na forma de solicitações HTTP para serem neutros em relação ao idioma. Para saber como implementar uma atualização em lote em diferentes linguagens usando as bibliotecas de cliente da API Google, consulte Atualizar planilhas.

Nesses exemplos, os marcadores de posição SPREADSHEET_ID e SHEET_ID indicam onde você forneceria esses IDs. Você pode encontrar o ID da planilha no URL dela. Você pode conseguir o ID da planilha usando o método spreadsheets.get. Os intervalos são especificados usando a notação A1. Um exemplo de intervalo é "Página1!A1:D5".

Além disso, os marcadores NAMED_RANGE_ID e PROTECTED_RANGE_ID fornecem os IDs dos intervalos nomeados e protegidos. Os namedRangeId e protectedRangeId são usados ao fazer solicitações para atualizar ou excluir os intervalos associados. O ID é retornado na resposta a uma solicitação da API Google Sheets que cria um intervalo nomeado ou protegido. É possível receber os IDs dos intervalos existentes com o método spreadsheets.get no corpo da resposta Spreadsheet.

Adicionar intervalos nomeados ou protegidos

O exemplo de código spreadsheets.batchUpdate a seguir mostra como usar dois objetos de solicitação. O primeiro usa AddNamedRangeRequest para atribuir ao intervalo A1:E3 o nome "Counts". O segundo usa o AddProtectedRangeRequest para anexar uma proteção de nível de aviso ao intervalo A4:E4. Esse nível de proteção ainda permite que as células dentro do intervalo sejam editadas, mas mostra um aviso antes de fazer a mudança.

Essas solicitações retornam um AddNamedRangeResponse e um AddProtectedRangeResponse, que contêm os IDs e as propriedades do intervalo.

O protocolo de solicitação é mostrado abaixo.

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
        }
      }
    }
  ]
}

Excluir intervalos nomeados ou protegidos

O exemplo de código spreadsheets.batchUpdate a seguir mostra como usar dois objetos de solicitação. A primeira usa DeleteNamedRangeRequest para excluir um intervalo nomeado atual, usando o NAMED_RANGE_ID de uma chamada de API anterior. A segunda usa o DeleteProtectedRangeRequest para excluir uma proteção de intervalo atual, usando o PROTECTED_RANGE_ID de uma chamada de API anterior.

O protocolo de solicitação é mostrado abaixo.

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

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

Atualizar intervalos nomeados ou protegidos

O exemplo de código spreadsheets.batchUpdate a seguir mostra como usar dois objetos de solicitação. O primeiro usa o UpdateNamedRangeRequest para atualizar o nome de um intervalo nomeado existente para "InitialCounts", usando o NAMED_RANGE_ID de uma chamada de API anterior. O segundo usa o UpdateProtectedRangeRequest para atualizar um intervalo protegido existente e proteger o mesmo intervalo nomeado. O método Editors permite que apenas os usuários listados editem essas células. Essa solicitação usa o NAMED_RANGE_ID e o PROTECTED_RANGE_ID de chamadas de API anteriores.

O protocolo de solicitação é mostrado abaixo.

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"
      }
    }
  ]
}