Com a API Google Sheets, você pode criar, modificar e excluir intervalos nomeados ou protegidos. Os exemplos nesta página ilustram como você pode realizar algumas operações comuns do Planilhas com a API Sheets.
Esses exemplos são apresentados na forma de solicitações HTTP para serem de linguagem neutra. Para saber como implementar uma atualização em lote em diferentes idiomas usando as bibliotecas de cliente da API do Google, consulte Atualizar planilhas.
Nesses exemplos, os marcadores de posição SPREADSHEET_ID e SHEET_ID
indicam onde você forneceria esses IDs. O ID da planilha pode ser encontrado no URL dela. É possível 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 é Sheet1!A1:D5.
Além disso, os marcadores NAMED_RANGE_ID e PROTECTED_RANGE_ID fornecem os IDs dos intervalos nomeados e protegidos. namedRangeId e
protectedRangeId são usados ao fazer solicitações para atualizar ou excluir os
intervalos associados. Ele é retornado na resposta a uma solicitação da API Sheets que cria um intervalo nomeado ou protegido. É possível receber os IDs dos intervalos atuais 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 o
AddNamedRangeRequest
para atribuir o nome "Counts" ao intervalo A1:E3. O segundo usa o
AddProtectedRangeRequest
para anexar uma proteção de nível de aviso ao intervalo A4:E4. Essa proteção de nível
ainda permite que as células no intervalo sejam editadas, mas um aviso é exibido antes
da alteração.
Essas solicitações retornam uma
AddNamedRangeResponse
e uma
AddProtectedRangeResponse,
contendo os IDs e as propriedades do intervalo.
Confira o protocolo da solicitação 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. O primeiro usa o DeleteNamedRangeRequest para excluir um intervalo nomeado existente, utilizando o NAMED_RANGE_ID de uma chamada de API anterior. O segundo usa o DeleteProtectedRangeRequest para excluir uma proteção de intervalo existente, utilizando o PROTECTED_RANGE_ID de uma chamada de API anterior.
Confira o protocolo da solicitação 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. Assim, ele passa a 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.
Confira o protocolo da solicitação 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"
}
}
]
}