Com as páginas conectadas, você pode analisar petabytes de dados diretamente nas Planilhas Google. Você pode conectar suas planilhas a um data warehouse do BigQuery e fazer a análise usando ferramentas conhecidas do Planilhas, como tabelas dinâmicas, gráficos e fórmulas.
Neste guia, usamos o conjunto de dados público Shakespeare
para mostrar como usar as páginas conectadas. O conjunto de dados
contém as seguintes informações:
Campo | Tipo | Descrição |
---|---|---|
palavra | STRING |
Uma única palavra única (em que o espaço em branco é o delimitador) extraída de um corpus. |
word_count | INTEGER |
O número de vezes que esta palavra aparece neste corpus. |
corpus | STRING |
A obra de onde a palavra foi extraída. |
corpus_date | INTEGER |
O ano em que este corpus foi publicado. |
Se o aplicativo solicitar dados das páginas conectadas, ele precisará fornecer um token OAuth 2.0 que conceda o escopo bigquery.readonly
, além dos outros escopos necessários para uma solicitação normal da API Google Sheets. Para mais informações, consulte Escolher escopos da API Google Sheets.
Gerenciar uma fonte de dados
Uma fonte de dados especifica um local externo onde os dados são encontrados. A fonte de dados é então conectada à planilha.
Adicionar uma fonte de dados do BigQuery
Para adicionar uma fonte de dados, forneça um
AddDataSourceRequest
usando o
método
spreadsheets.batchUpdate
. O corpo da solicitação precisa especificar um campo dataSource
do tipo
objeto DataSource
.
"addDataSource":{
"dataSource":{
"spec":{
"bigQuery":{
"projectId":"PROJECT_ID",
"tableSpec":{
"tableProjectId":"bigquery-public-data",
"datasetId":"samples",
"tableId":"shakespeare"
}
}
}
}
}
Substitua PROJECT_ID por um ID de projeto válido do Google Cloud.
Depois que uma fonte de dados é criada, uma planilha DATA_SOURCE
(em inglês) é criada para fornecer uma visualização de até 500 linhas. A visualização não fica disponível imediatamente. Uma execução é acionada de modo assíncrono para importar os dados do BigQuery.
O
AddDataSourceResponse
contém os campos abaixo:
dataSource
: o objetoDataSource
criado. OdataSourceId
é um ID exclusivo no escopo da planilha. Ele é preenchido e referenciado para criar cada objetoDataSource
da fonte de dados.dataExecutionStatus
: o status de uma execução que importa dados do BigQuery para a planilha de visualização. Para mais informações, consulte a seção Status de execução de dados.
Atualizar ou excluir uma fonte de dados
Use o método
spreadsheets.batchUpdate
e forneça uma solicitação
UpdateDataSourceRequest
ou
DeleteDataSourceRequest
.
Gerenciar objetos da fonte de dados
Quando uma fonte de dados é adicionada à planilha, um objeto de fonte de dados pode ser criado com base nela. Um objeto de origem de dados é uma ferramenta comum das Planilhas Google, como tabelas dinâmicas, gráficos e fórmulas, que é integrada às páginas conectadas para aprimorar a análise dos dados.
Há quatro tipos de objetos:
DataSource
tabelaDataSource
pivotTable- Gráfico de
DataSource
- Fórmula
DataSource
Adicionar uma tabela de fonte de dados
Conhecido como "extração" no editor do Planilhas, o objeto da tabela importa um despejo estático de dados da fonte de dados para o Planilhas. Semelhante a uma tabela dinâmica, ela é especificada e fixada na célula superior esquerda.
O exemplo de código a seguir mostra como usar o método
spreadsheets.batchUpdate
e um
UpdateCellsRequest
para criar uma tabela de fonte de dados com até 1.000 linhas de duas colunas (word
e
word_count
).
"updateCells":{
"rows":{
"values":[
{
"dataSourceTable":{
"dataSourceId":"DATA_SOURCE_ID",
"columns":[
{
"name":"word"
},
{
"name":"word_count"
}
],
"rowLimit":{
"value":1000
},
"columnSelectionType":"SELECTED"
}
}
]
},
"fields":"dataSourceTable"
}
Substitua DATA_SOURCE_ID por um ID exclusivo no escopo da planilha que identifique a fonte de dados.
Após a criação de uma tabela de fonte de dados, os dados não ficam disponíveis imediatamente. No editor do Planilhas, ela aparece como uma visualização. Você precisa atualizar a tabela de fonte de dados para buscar os dados do BigQuery. É possível especificar um
RefreshDataSourceRequest
no mesmo batchUpdate
. Todos os objetos de fonte de dados funcionam de maneira semelhante.
Para mais informações, consulte Atualizar um objeto de fonte de dados.
Depois que a atualização for concluída e os dados do BigQuery forem buscados, a tabela da fonte de dados será preenchida conforme mostrado:
Adicionar uma tabela dinâmica de fonte de dados
Ao contrário de uma tabela dinâmica convencional, uma tabela dinâmica de fonte de dados tem o apoio de uma fonte de dados e faz referência aos dados por nome de coluna. O exemplo de código a seguir
mostra como usar o método spreadsheets.batchUpdate
e um
UpdateCellsRequest
para criar uma tabela dinâmica que mostra a contagem total de palavras por
corpus.
"updateCells":{
"rows":{
"values":[
{
"pivotTable":{
"dataSourceId":"DATA_SOURCE_ID",
"rows":{
"dataSourceColumnReference":{
"name":"corpus"
},
"sortOrder":"ASCENDING"
},
"values":{
"summarizeFunction":"SUM",
"dataSourceColumnReference":{
"name":"word_count"
}
}
}
}
]
},
"fields":"pivotTable"
}
Substitua DATA_SOURCE_ID por um ID exclusivo no escopo da planilha que identifique a fonte de dados.
Depois que os dados do BigQuery são buscados, a tabela dinâmica da fonte de dados é preenchida conforme mostrado:
Adicionar um gráfico de fonte de dados
O exemplo de código a seguir mostra como usar o método spreadsheets.batchUpdate
e um AddChartRequest
para criar um gráfico de fonte de dados com um chartType
de COLUMN, mostrando a contagem total de palavras por corpus.
"addChart":{
"chart":{
"spec":{
"title":"Corpus by word count",
"basicChart":{
"chartType":"COLUMN",
"domains":[
{
"domain":{
"columnReference":{
"name":"corpus"
}
}
}
],
"series":[
{
"series":{
"columnReference":{
"name":"word_count"
},
"aggregateType":"SUM"
}
}
]
}
},
"dataSourceChartProperties":{
"dataSourceId":"DATA_SOURCE_ID"
}
}
}
Substitua DATA_SOURCE_ID por um ID exclusivo no escopo da planilha que identifique a fonte de dados.
Depois que os dados do BigQuery são buscados, o gráfico da fonte de dados é renderizado da seguinte maneira:
Adicionar uma fórmula de fonte de dados
O exemplo de código a seguir mostra como usar o método spreadsheets.batchUpdate
e um UpdateCellsRequest
para criar uma fórmula de fonte de dados para calcular a contagem média de palavras.
"updateCells":{
"rows":[
{
"values":[
{
"userEnteredValue":{
"formulaValue":"=AVERAGE(shakespeare!word_count)"
}
}
]
}
],
"fields":"userEnteredValue"
}
Depois que os dados do BigQuery são buscados, a fórmula da fonte de dados é preenchida da seguinte maneira:
Atualizar um objeto de fonte de dados
Atualize um objeto de fonte de dados para buscar os dados mais recentes do BigQuery com base nas especificações da fonte de dados e nas configurações do objeto. Use
o
método
spreadsheets.batchUpdate
para chamar o
RefreshDataSourceRequest
.
Em seguida, especifique uma ou mais referências de objeto a serem atualizadas usando o
objeto
DataSourceObjectReferences
.
Observe que é possível criar e atualizar objetos de fonte de dados em uma única solicitação batchUpdate
.
Status de execução dos dados
Quando você cria fontes de dados ou atualiza objetos delas, uma execução em segundo plano é criada para buscar os dados do BigQuery e retornar uma resposta contendo DataExecutionStatus
.
Se a execução for iniciada com êxito, o
DataExecutionState
geralmente estará no estado RUNNING
.
Como o processo é assíncrono, seu aplicativo precisa implementar um modelo de pesquisa para recuperar periodicamente o status dos objetos da fonte de dados. Use o método
spreadsheets.get
até que o status retorne SUCCEEDED
ou FAILED
. A execução é concluída rapidamente na maioria dos casos, mas depende da complexidade da fonte de dados. Normalmente, a execução não excede 10 minutos.
Temas relacionados
- Escolher escopos da API Google Sheets
- Como usar os dados do BigQuery no Planilhas Google
- Documentação do BigQuery
- BigQuery: como usar as páginas conectadas
- Tutorial em vídeo das páginas conectadas