Com a API Google Sheets, você pode criar e atualizar gráficos em planilhas conforme necessário. Nos exemplos desta página, ilustramos como realizar algumas operações de gráfico comuns 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.
Além disso, o marcador CHART_ID indica o ID de um determinado gráfico. Você pode definir esse ID ao criar um gráfico com a API Sheets ou permitir que essa API gere um para você. Você pode conseguir os IDs de gráficos existentes com o método spreadsheets.get.
Por fim, o marcador SOURCE_SHEET_ID indica sua página com os dados de origem. Nesses exemplos, esta é a tabela listada em Dados de origem do gráfico.
Dados de origem do gráfico
Para esses exemplos, suponha que a planilha usada tenha os seguintes dados de origem na primeira página ("Sheet1"). As strings na primeira linha são rótulos para as colunas individuais. Para ver exemplos de como ler outras páginas na sua planilha, consulte Notação A1.
| R | B | C | D | E | |
| 1 | Número do modelo | Vendas - janeiro | Vendas – Fev | Vendas – março | Total de vendas |
| 2 | D-01X | 68 | 74 | 60 | 202 |
| 3 | FR-0B1 | 97 | 76 | 88 | 261 |
| 4 | P-034 | 27 | 49 | 32 | 108 |
| 5 | P-105 | 46 | 44 | 67 | 157 |
| 6 | W-11 | 75 | 68 | 87 | 230 |
| 7 | W-24 | 74 | 52 | 62 | 188 |
Adicionar um gráfico de colunas
O exemplo de código spreadsheets.batchUpdate a seguir mostra como usar AddChartRequest para criar um gráfico de colunas a partir dos dados de origem, colocando-os em uma nova planilha. A solicitação faz o seguinte para configurar o gráfico:
- Define o tipo de gráfico como um gráfico de colunas.
- Adiciona uma legenda à parte inferior do gráfico.
- Define os títulos do gráfico e do eixo.
- Configura três séries de dados, representando as vendas por três meses diferentes, usando a formatação e as cores padrão.
Confira o protocolo da solicitação abaixo.
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
"requests": [
{
"addChart": {
"chart": {
"spec": {
"title": "Model Q1 Sales",
"basicChart": {
"chartType": "COLUMN",
"legendPosition": "BOTTOM_LEGEND",
"axis": [
{
"position": "BOTTOM_AXIS",
"title": "Model Numbers"
},
{
"position": "LEFT_AXIS",
"title": "Sales"
}
],
"domains": [
{
"domain": {
"sourceRange": {
"sources": [
{
"sheetId": SOURCE_SHEET_ID,
"startRowIndex": 0,
"endRowIndex": 7,
"startColumnIndex": 0,
"endColumnIndex": 1
}
]
}
}
}
],
"series": [
{
"series": {
"sourceRange": {
"sources": [
{
"sheetId": SOURCE_SHEET_ID,
"startRowIndex": 0,
"endRowIndex": 7,
"startColumnIndex": 1,
"endColumnIndex": 2
}
]
}
},
"targetAxis": "LEFT_AXIS"
},
{
"series": {
"sourceRange": {
"sources": [
{
"sheetId": SOURCE_SHEET_ID,
"startRowIndex": 0,
"endRowIndex": 7,
"startColumnIndex": 2,
"endColumnIndex": 3
}
]
}
},
"targetAxis": "LEFT_AXIS"
},
{
"series": {
"sourceRange": {
"sources": [
{
"sheetId": SOURCE_SHEET_ID,
"startRowIndex": 0,
"endRowIndex": 7,
"startColumnIndex": 3,
"endColumnIndex": 4
}
]
}
},
"targetAxis": "LEFT_AXIS"
}
],
"headerCount": 1
}
},
"position": {
"newSheet": true
}
}
}
}
]
}
A solicitação cria um gráfico em uma nova planilha como este:
Adicionar um gráfico de pizza
O exemplo de código
spreadsheets.batchUpdate
a seguir mostra como usar o
AddChartRequest
para criar um gráfico de pizza 3D com base nos dados de origem. A solicitação faz o seguinte para configurar o gráfico:
- Define o título do gráfico.
- Adiciona uma legenda à direita do gráfico.
- Define o gráfico como um gráfico de pizza em 3D. Os gráficos de pizza em 3D não podem ter um "buraco de rosca" no centro, da mesma forma que os gráficos de pizza planos.
- Define a série de dados do gráfico como o total de vendas de cada número de modelo.
- Ancora o gráfico na célula C3 da planilha especificada por SHEET_ID, com um deslocamento de 50 pixels nas direções X e Y.
Confira o protocolo da solicitação abaixo.
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
"requests": [
{
"addChart": {
"chart": {
"spec": {
"title": "Model Q1 Total Sales",
"pieChart": {
"legendPosition": "RIGHT_LEGEND",
"threeDimensional": true,
"domain": {
"sourceRange": {
"sources": [
{
"sheetId": SOURCE_SHEET_ID,
"startRowIndex": 0,
"endRowIndex": 7,
"startColumnIndex": 0,
"endColumnIndex": 1
}
]
}
},
"series": {
"sourceRange": {
"sources": [
{
"sheetId": SOURCE_SHEET_ID,
"startRowIndex": 0,
"endRowIndex": 7,
"startColumnIndex": 4,
"endColumnIndex": 5
}
]
}
},
}
},
"position": {
"overlayPosition": {
"anchorCell": {
"sheetId": SHEET_ID,
"rowIndex": 2,
"columnIndex": 2
},
"offsetXPixels": 50,
"offsetYPixels": 50
}
}
}
}
}
]
}
A solicitação cria um gráfico como este:
Como alternativa, também é possível atualizar o valor de captionPosition de RIGHT_LEGEND para LABELED_LEGEND na solicitação, de modo que os valores de legenda sejam conectados às fatias do gráfico de pizza.
'legendPosition': 'LABELED_LEGEND',
A solicitação atualizada cria um gráfico como este:
Adicionar um gráfico de linhas usando vários intervalos não adjacentes
O exemplo de código spreadsheets.batchUpdate a seguir mostra como usar AddChartRequest para criar um gráfico de linhas a partir dos dados de origem, colocando-os na página de origem.
A seleção de intervalos não adjacentes pode ser usada para excluir linhas de
ChartSourceRange.
A solicitação faz o seguinte para configurar o gráfico:
- Define o tipo de gráfico como um gráfico de linhas.
- Define o título horizontal do eixo x.
- Configura uma série de dados que representa vendas. Ele define A1:A3 e A6:A7 como um
domain, e B1:B3 e B6:B7 como umseries, usando a formatação e as cores padrão. Os intervalos são especificados usando a notação A1 no URL da solicitação. - Ancora o gráfico na célula H8 da página especificada por SHEET_ID.
Confira o protocolo da solicitação abaixo.
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
"requests": [
{
"addChart": {
"chart": {
"spec": {
"basicChart": {
"chartType": "LINE",
"domains": [
{
"domain": {
"sourceRange": {
"sources": [
{
"startRowIndex": 0,
"endRowIndex": 3,
"startColumnIndex": 0,
"endColumnIndex": 1,
"sheetId": SOURCE_SHEET_ID
},
{
"startRowIndex": 5,
"endRowIndex": 7,
"startColumnIndex": 0,
"endColumnIndex": 1,
"sheetId": SOURCE_SHEET_ID
}
]
}
}
}
],
"series": [
{
"series": {
"sourceRange": {
"sources": [
{
"startRowIndex": 0,
"endRowIndex": 3,
"startColumnIndex": 1,
"endColumnIndex": 2,
"sheetId": SOURCE_SHEET_ID
},
{
"startRowIndex": 5,
"endRowIndex": 7,
"startColumnIndex": 1,
"endColumnIndex": 2,
"sheetId": SOURCE_SHEET_ID
}
]
}
}
}
]
}
},
"position": {
"overlayPosition": {
"anchorCell": {
"sheetId": SOURCE_SHEET_ID,
"rowIndex": 8,
"columnIndex": 8
}
}
}
}
}
}
]
}
A solicitação cria um gráfico em uma nova planilha como este:
Excluir um gráfico
O exemplo de código spreadsheets.batchUpdate a seguir mostra como usar DeleteEmbeddedObjectRequest para excluir um gráfico especificado por CHART_ID.
Confira o protocolo da solicitação abaixo.
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
"requests": [
{
"deleteEmbeddedObject": {
"objectId": CHART_ID
}
}
]
}
Editar as propriedades de um gráfico
O exemplo de código spreadsheets.batchUpdate a seguir mostra como usar o UpdateChartSpecRequest para editar o gráfico criado no roteiro Adicionar um gráfico de colunas, modificando os dados, o tipo e a aparência dele. Subconjuntos de propriedades do gráfico não podem ser alterados individualmente. Para fazer edições, forneça todo o campo spec
com um UpdateChartSpecRequest. Para editar uma especificação de gráfico, é necessário substituí-la por uma nova.
A solicitação a seguir atualiza o gráfico original (especificado por CHART_ID):
- Define o tipo de gráfico como
BAR. - Move a legenda para a direita do gráfico.
- Inverte os eixos para que "Vendas" esteja no eixo inferior e "Números do modelo" esteja no eixo à esquerda.
- Define o formato do título do eixo como fonte de 24 pontos, negrito e itálico.
- Remove os dados "W-24" do gráfico (linha 7 nos dados de origem do gráfico).
Confira o protocolo da solicitação abaixo.
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
"requests": [
{
"updateChartSpec": {
"chartId": CHART_ID,
"spec": {
"title": "Model Q1 Sales",
"basicChart": {
"chartType": "BAR",
"legendPosition": "RIGHT_LEGEND",
"axis": [
{
"format": {
"bold": true,
"italic": true,
"fontSize": 24
},
"position": "BOTTOM_AXIS",
"title": "Sales"
},
{
"format": {
"bold": true,
"italic": true,
"fontSize": 24
},
"position": "LEFT_AXIS",
"title": "Model Numbers"
}
],
"domains": [
{
"domain": {
"sourceRange": {
"sources": [
{
"sheetId": SOURCE_SHEET_ID,
"startRowIndex": 0,
"endRowIndex": 6,
"startColumnIndex": 0,
"endColumnIndex": 1
}
]
}
}
}
],
"series": [
{
"series": {
"sourceRange": {
"sources": [
{
"sheetId": SOURCE_SHEET_ID,
"startRowIndex": 0,
"endRowIndex": 6,
"startColumnIndex": 1,
"endColumnIndex": 2
}
]
}
},
"targetAxis": "BOTTOM_AXIS"
},
{
"series": {
"sourceRange": {
"sources": [
{
"sheetId": SOURCE_SHEET_ID,
"startRowIndex": 0,
"endRowIndex": 6,
"startColumnIndex": 2,
"endColumnIndex": 3
}
]
}
},
"targetAxis": "BOTTOM_AXIS"
},
{
"series": {
"sourceRange": {
"sources": [
{
"sheetId": SOURCE_SHEET_ID,
"startRowIndex": 0,
"endRowIndex": 6,
"startColumnIndex": 3,
"endColumnIndex": 4
}
]
}
},
"targetAxis": "BOTTOM_AXIS"
}
],
"headerCount": 1
}
}
}
}
]
}
Depois da solicitação, o gráfico aparece assim:
Mover ou redimensionar um gráfico
O exemplo de código spreadsheets.batchUpdate a seguir mostra como usar UpdateEmbeddedObjectPositionRequest para mover e redimensionar um gráfico. Após a solicitação, o gráfico especificado por CHART_ID é:
- Ancorado à célula A5 da página original.
- Deslocamento na direção X em 100 pixels.
- Redimensionado para 1.200 por 742 pixels (o tamanho padrão de um gráfico é 600 por 371 pixels).
A solicitação só muda as propriedades especificadas com o parâmetro fields.
Outras propriedades, como offsetYPixels, mantêm os valores originais.
Confira o protocolo da solicitação abaixo.
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
"requests": [
{
"updateEmbeddedObjectPosition": {
"objectId": CHART_ID,
"newPosition": {
"overlayPosition": {
"anchorCell": {
"rowIndex": 4,
"columnIndex": 0
},
"offsetXPixels": 100,
"widthPixels": 1200,
"heightPixels": 742
}
},
"fields": "anchorCell(rowIndex,columnIndex),offsetXPixels,widthPixels,heightPixels"
}
}
]
}
Ler dados do gráfico
O exemplo de código spreadsheets.get a seguir mostra como receber dados do gráfico de uma planilha. O parâmetro de consulta fields especifica que apenas os dados do gráfico devem ser retornados.
A resposta a essa chamada de método é um objeto
spreadsheet, que contém uma matriz de objetos
sheet. Todos os gráficos
presentes em uma página são representados no objeto
sheet. Se um campo de resposta for definido com o valor padrão, ele será omitido da resposta.
Neste exemplo, a primeira página (SOURCE_SHEET_ID) não tem nenhum gráfico, então um par vazio de chaves é retornado. A segunda tem o gráfico criado em Adicionar um gráfico de colunas, nada mais.
Confira o protocolo da solicitação abaixo.
GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID?fields=sheets(charts)
{
"sheets": [
{},
{
"charts": [
{
"chartId": CHART_ID,
"position": {
"sheetId": SHEET_ID
},
"spec": {
"basicChart": {
"axis": [
{
"format": {
"bold": false,
"italic": false
},
"position": "BOTTOM_AXIS",
"title": "Model Numbers"
},
{
"format": {
"bold": false,
"italic": false
},
"position": "LEFT_AXIS",
"title": "Sales"
}
],
"chartType": "COLUMN",
"domains": [
{
"domain": {
"sourceRange": {
"sources": [
{
"endColumnIndex": 1
"endRowIndex": 7,
"sheetId": SOURCE_SHEET_ID,
"startColumnIndex": 0,
"startRowIndex": 0,
}
]
}
}
}
],
"legendPosition": "BOTTOM_LEGEND",
"series": [
{
"series": {
"sourceRange": {
"sources": [
{
"endColumnIndex": 2,
"endRowIndex": 7,
"sheetId": SOURCE_SHEET_ID,
"startColumnIndex": 1,
"startRowIndex": 0,
}
]
}
},
"targetAxis": "LEFT_AXIS"
},
{
"series": {
"sourceRange": {
"sources": [
{
"endColumnIndex": 3,
"endRowIndex": 7,
"sheetId": SOURCE_SHEET_ID,
"startColumnIndex": 2,
"startRowIndex": 0,
}
]
}
},
"targetAxis": "LEFT_AXIS"
},
{
"series": {
"sourceRange": {
"sources": [
{
"endColumnIndex": 4,
"endRowIndex": 7,
"sheetId": SOURCE_SHEET_ID,
"startColumnIndex": 3,
"startRowIndex": 0,
}
]
}
},
"targetAxis": "LEFT_AXIS"
}
]
},
"hiddenDimensionStrategy": "SKIP_HIDDEN_ROWS_AND_COLUMNS",
"title": "Model Q1 Sales",
},
}
]
}
]
}