A API Google Sheets permite que você crie, limpe, copie e exclua planilhas, além de controlar suas propriedades. Os exemplos nesta página ilustram como é possível 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.
Adicionar uma página
O exemplo de código
spreadsheets.batchUpdate
abaixo mostra como usar o
AddSheetRequest
para adicionar uma página a uma planilha, além de definir 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
}
}
}
}
]
}
Limpar uma página com todos os valores, preservando os formatos
O exemplo de código
spreadsheets.batchUpdate
abaixo mostra como usar o
UpdateCellsRequest
para remover todos os valores de uma página, deixando a formatação inalterada.
Especificar o campo
userEnteredValue
sem um valor correspondente é interpretado como uma instrução para limpar os valores
no intervalo. Essa configuração também pode ser usada com outros campos. Por exemplo,
alterar o valor fields para
userEnteredFormat remove
toda a formatação compatível com a API Sheets
da página, mas deixa os valores das células inalterados.
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 página 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ção, fórmulas e
outras propriedades do 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 página 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 a seguir mostra como receber informações de propriedades da planilha de uma planilha, especificadas por SHEET_ID e SPREADSHEET_ID. Esse método é frequentemente usado para determinar os metadados das páginas de uma planilha específica, de modo que operações adicionais possam segmentar essas páginas. O parâmetro de consulta fields especifica que somente dados de propriedades da página devem ser retornados, e não dados de valores de células ou dados relacionados à planilha inteira.
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 for 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
}
},
...
],
}