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 é 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 a linguagem neutra. Para saber como implementar uma atualização em lote em linguagens diferentes usando as bibliotecas de cliente das APIs do Google, consulte Atualizar planilhas.
Nesses exemplos, os marcadores SPREADSHEET_ID
e SHEET_ID
indicam onde você fornece esses IDs. Você pode encontrar o ID da planilha no URL da planilha. Consiga 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 a
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
SHEET_ID
).
O protocolo da solicitação é mostrado 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
a seguir mostra como usar a
UpdateCellsRequest
para remover todos os valores de uma página sem alterar a formatação.
A especificação do campo
userEnteredValue
sem um valor correspondente é interpretada como uma instrução para limpar 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, mas deixa os valores das células inalterados.
O protocolo da solicitação é mostrado 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
Veja no exemplo de código spreadsheet.sheets.copyTo
a seguir 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
a seguir mostra como usar a
DeleteSheetRequest
para excluir uma página especificada por SHEET_ID
.
O protocolo da solicitação é mostrado 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 da propriedade da planilha de uma planilha, especificada por SHEET_ID
e SPREADSHEET_ID
. Esse método é frequentemente usado para determinar os metadados de páginas dentro de uma planilha específica. Portanto, operações adicionais podem segmentar essas páginas. O parâmetro de consulta fields
especifica que apenas os dados de propriedade da página precisam ser retornados, e não os 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 com 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
}
},
...
],
}