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 à linguagem. 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 de posição 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 "Contagens". 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 NAMED_RANGE_ID e 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"
      }
    }
  ]
}