A API Google Sheets permite criar, modificar e excluir intervalos nomeados ou protegidos. Os exemplos nesta página ilustram como realizar algumas operações comuns do 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 SPREADSHEET_ID e SHEET_ID
indicam onde você forneceria esses IDs. É possível encontrar o ID
da planilha no URL dela. Para receber
o ID da página, use o
spreadsheets.get método. 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. 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 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 a seguir
spreadsheets.batchUpdate
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 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 a seguir
spreadsheets.batchUpdate
mostra como usar dois objetos de solicitação. O primeiro usa o
DeleteNamedRangeRequest
para excluir um intervalo nomeado atual, usando o NAMED_RANGE_ID de uma
chamada de API anterior. O segundo 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 a seguir
spreadsheets.batchUpdate
mostra como usar dois objetos de solicitação. O primeiro usa o
UpdateNamedRangeRequest
para atualizar o nome de um intervalo nomeado atual para "InitialCounts", usando o NAMED_RANGE_ID
de uma chamada de API anterior. O segundo usa o
UpdateProtectedRangeRequest
para atualizar um intervalo protegido atual para que ele proteja o mesmo
intervalo nomeado. O
Editors método
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" } } ] }