Com a API Google Sheets, você pode criar, limpar, copiar e excluir páginas, além de controlar as propriedades delas. Os exemplos nesta página ilustram como realizar algumas operações comuns das Planilhas 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 incluir esses IDs. O ID da planilha pode ser encontrado 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.
Adicionar uma página
O exemplo de código
spreadsheets.batchUpdate
a seguir mostra como usar o
AddSheetRequest
para adicionar uma página a uma planilha, definindo também o título, o tamanho da grade e
a cor da guia.
A resposta consiste em um
AddSheetResponse
,
que contém um objeto com as propriedades da página criada (como a
SHEET_ID
).
Confira o protocolo da solicitação abaixo.
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID
:batchUpdate
{ "requests": [ { "addSheet": { "properties": { "title": "Deposits", "gridProperties": { "rowCount": 20, "columnCount": 12 }, "tabColor": { "red": 1.0, "green": 0.3, "blue": 0.4 } } } } ] }
Limpe todos os valores de uma página preservando as formatações
O exemplo de código
spreadsheets.batchUpdate
a seguir mostra como usar o
UpdateCellsRequest
para remover todos os valores de uma página sem alterar a formatação.
Especificar o campo
userEnteredValue
sem um valor correspondente é interpretado como uma instrução para limpar valores
no intervalo. Essa configuração também pode ser usada com outros campos. Por exemplo,
mudar o valor fields
para
userEnteredFormat
remove
toda a formatação com suporte da API Sheets
da planilha, mas não altera os valores das células.
Confira o protocolo da solicitação abaixo.
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID
:batchUpdate
{
"requests": [
{
"updateCells": {
"range": {
"sheetId": SHEET_ID
},
"fields": "userEnteredValue"
}
}
]
}
Copiar uma página de uma planilha para outra
O exemplo de código
spreadsheet.sheets.copyTo
a seguir mostra como copiar uma única planilha especificada por SHEET_ID
de uma planilha para outra.
A variável TARGET_SPREADSHEET_ID
no corpo da solicitação especifica a
planilha de destino. A cópia mantém todos os valores, formatações, fórmulas e
outras propriedades da original. O título da página copiada é definido como "Cópia de [título da página original]".
A resposta consiste em um objeto
SheetProperties
que descreve as propriedades da página criada.
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID
/sheets/SHEET_ID
:copyTo
{
"destinationSpreadsheetId": "TARGET_SPREADSHEET_ID
"
}
Excluir uma página
O exemplo de código
spreadsheets.batchUpdate
abaixo mostra como usar o
DeleteSheetRequest
para excluir uma planilha especificada por SHEET_ID
.
Confira o protocolo da solicitação abaixo.
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID
:batchUpdate
{
"requests": [
{
"deleteSheet": {
"sheetId": SHEET_ID
}
}
]
}
Ler dados da planilha
O exemplo de código
spreadsheets.get
abaixo
mostra como receber informações da propriedade sheet
de uma planilha, especificada por SHEET_ID
e SPREADSHEET_ID
. Esse método é usado com frequência para determinar os
metadados de páginas em uma planilha específica, para que outras operações possam
ser direcionadas a essas páginas. O parâmetro de consulta fields
especifica que apenas os dados de propriedades da página
devem ser retornados, em vez de dados de valor de célula ou dados relacionados a
toda a planilha.
GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID
?&fields=sheets.properties
A resposta consiste em um recurso
Spreadsheet
, que contém um objeto
Sheet
com elementos
SheetProperties
. Se um determinado campo de resposta estiver definido como o valor padrão, ele será omitido
da resposta.
{
"sheets": [
{
"properties": {
"sheetId": SHEET_ID
,
"title": "Sheet1",
"index": 0,
"sheetType": "GRID",
"gridProperties": {
"rowCount": 100,
"columnCount": 20,
"frozenRowCount": 1
}
"tabColor": {
"blue": 1.0
}
},
...
],
}