Páginas conectadas

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 objeto DataSource criado. O dataSourceId é um ID exclusivo no escopo da planilha. Ele é preenchido e referenciado para criar cada objeto DataSource 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 tabela
  • DataSource 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:

Tabela de fonte de dados que mostra informações do conjunto de dados público Shakespeare.

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:

Tabela dinâmica da fonte de dados que mostra dados do conjunto de dados público Shakespeare.

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:

Gráfico de fonte de dados mostrando informações do conjunto de dados público Shakespeare.

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:

Fórmula da fonte de dados que mostra dados do conjunto de dados público Shakespeare.

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.