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 das Planilhas Google com a API Sheets.
Esses exemplos são apresentados na forma de solicitações HTTP para serem neutros em termos de linguagem. Para saber como implementar uma atualização em lote em diferentes idiomas usando as bibliotecas do cliente da Google API, consulte Atualizar planilhas.
Nesses exemplos, os marcadores de posição SPREADSHEET_ID e SHEET_ID
indicam onde você deve fornecer esses IDs. Você pode encontrar o ID da planilha no URL dela. Você pode conferir 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 de posição NAMED_RANGE_ID e PROTECTED_RANGE_ID
fornecem os IDs dos intervalos nomeados e protegidos. O namedRangeId e o protectedRangeId são usados ao fazer solicitações para atualizar ou excluir os intervalos associados. O ID é retornado na resposta de uma solicitação da API Sheets
que cria um intervalo nomeado ou protegido. É possível receber os IDs de 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
abaixo mostra como usar dois objetos de solicitação. A primeira usa o
AddNamedRangeRequest
para atribuir o nome "Contagens" 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 do intervalo sejam editadas, mas exibe um aviso antes
de fazer a alteração.
Essas solicitações retornam um
AddNamedRangeResponse
e um
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
abaixo mostra como usar dois objetos de solicitação. O primeiro usa o
DeleteNamedRangeRequest
para excluir um intervalo nomeado, usando o NAMED_RANGE_ID de uma
chamada de API anterior. A segunda usa o
DeleteProtectedRangeRequest
para excluir uma proteção de intervalo existente, usando 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
abaixo mostra como usar dois objetos de solicitação. O primeiro usa o
UpdateNamedRangeRequest
para atualizar o nome de um intervalo nomeado para "InitialCounts", usando o NAMED_RANGE_ID
de uma chamada de API anterior. O segundo usa o
UpdateProtectedRangeRequest
para atualizar um intervalo protegido existente, de modo que ele passe 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 NAMED_RANGE_ID
e 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"
}
}
]
}