Páginas conectadas

Com as páginas conectadas, você pode analisar petabytes de dados diretamente nas Planilhas Google. É possível conectar suas planilhas a um data warehouse do BigQuery ou do Looker e fazer a análise usando ferramentas conhecidas das Planilhas, como tabelas dinâmicas, gráficos e fórmulas.

Gerenciar uma fonte de dados do BigQuery

Esta seção usa o conjunto de dados público Shakespeare do BigQuery 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 exclusiva (em que o espaço em branco é o delimitador) extraída de um corpus.
word_count INTEGER O número de vezes que essa palavra aparece no corpus.
corpus STRING A obra de que a palavra foi extraída.
corpus_date INTEGER O ano em que o corpus foi publicado.

Se o aplicativo solicitar dados das Páginas conectadas do BigQuery, ele precisa fornecer um token OAuth 2.0 que conceda o escopo bigquery.readonly, além dos outros escopos necessários para uma solicitação regular da API das Planilhas Google. Para mais informações, consulte Escolher escopos da API Google Sheets.

Uma fonte de dados especifica um local externo em que os dados são encontrados. A fonte de dados é conectada à planilha.

Adicionar uma origem de dados do BigQuery

Para adicionar uma origem 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 página DATA_SOURCE associada é criada para fornecer uma visualização de até 500 linhas. A visualização não está disponível imediatamente. Uma execução é acionada de forma assíncrona para importar os dados do BigQuery.

O AddDataSourceResponse contém os seguintes campos:

  • 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 da execução de dados.

Atualizar ou excluir uma fonte de dados do BigQuery

Use o método spreadsheets.batchUpdate e forneça uma solicitação UpdateDataSourceRequest ou DeleteDataSourceRequest.

Gerenciar objetos de fonte de dados do BigQuery

Depois que uma fonte de dados é adicionada à planilha, um objeto de fonte de dados pode ser criado a partir dela. Um objeto de fonte de dados é uma ferramenta regular das Páginas, como tabelas dinâmicas, gráficos e fórmulas, integrada às Páginas conectadas para melhorar a análise de dados.

Há quatro tipos de objetos:

  • DataSource tabela
  • DataSource pivotTable
  • Gráfico de DataSource
  • Fórmula DataSource

Adicionar uma tabela de origem de dados do BigQuery

Conhecido como "extração" no editor do Planilhas, o objeto de tabela importa um despejo estático de dados da fonte de dados para as Planilhas. Assim como uma tabela dinâmica, a tabela é especificada e ancorada 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 origem 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.

Depois que uma tabela de origem de dados é criada, os dados não ficam disponíveis imediatamente. No editor do Planilhas, ele aparece como uma prévia. É necessário atualizar a tabela da 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 é concluída e os dados do BigQuery são buscados, a tabela da fonte de dados é preenchida, conforme mostrado:

Tabela de origem de dados mostrando dados do conjunto de dados público Shakespeare.

Adicionar uma pivotTable de origem de dados do BigQuery

Ao contrário de uma tabela dinâmica convencional, a tabela dinâmica da fonte de dados é apoiada por uma fonte de dados e faz referência aos dados pelo nome da coluna. O exemplo de código abaixo mostra como usar o método spreadsheets.batchUpdate e um UpdateCellsRequest para criar uma tabela dinâmica que mostre 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 origem de dados é preenchida conforme exibido:

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

Adicionar um gráfico de origem de dados do BigQuery

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 COLUNA, 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 da fonte de dados mostrando dados do conjunto de dados público de Shakespeare.

Adicionar uma fórmula de origem de dados do BigQuery

O exemplo de código abaixo 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 origem de dados é preenchida conforme mostrado:

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

Atualizar um objeto da fonte de dados do BigQuery

É possível atualizar um objeto da fonte de dados para buscar os dados mais recentes do BigQuery com base nas especificações e configurações de objetos atuais. É possível usar o método spreadsheets.batchUpdate para chamar o RefreshDataSourceRequest. Em seguida, especifique uma ou mais referências de objeto para atualizar usando o objeto DataSourceObjectReferences.

É possível criar e atualizar objetos de fonte de dados em uma única solicitação batchUpdate.

Gerenciar uma origem de dados do Looker

Neste guia, mostramos como adicionar, atualizar ou excluir uma fonte de dados do Looker, criar uma tabela dinâmica e atualizá-la.

Seu aplicativo que solicita dados das páginas conectadas do Looker vai reutilizar sua vinculação da Conta do Google com o Looker.

Adicionar uma origem de dados do Looker

Para adicionar uma origem 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":{
         "looker":{
            "instance_uri":"INSTANCE_URI",
            "model":"MODEL",
            "explore":"EXPLORE"
         }
      }
   }
}

Substitua INSTANCE_URI, MODEL e EXPLORE por um URI de instância, nome do modelo e nome da análise válida do Looker, respectivamente.

Depois que uma fonte de dados é criada, uma planilha associada DATA_SOURCE é criada para fornecer uma prévia da estrutura da análise detalhada selecionada, incluindo visualizações, dimensões, métricas e descrições de campos.

O AddDataSourceResponse contém os seguintes campos:

  • 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 da execução de dados.

Atualizar ou excluir uma fonte de dados do Looker

Use o método spreadsheets.batchUpdate e forneça uma solicitação UpdateDataSourceRequest ou DeleteDataSourceRequest.

Gerenciar objetos de fonte de dados do Looker

Depois que uma fonte de dados é adicionada à planilha, um objeto de fonte de dados pode ser criado a partir dela. Para fontes de dados do Looker, só é possível criar um objeto DataSource pivotTable.

Não é possível criar fórmulas, extrações e gráficos DataSource com base nas fontes de dados do Looker.

Atualizar um objeto da fonte de dados do Looker

É possível atualizar um objeto da fonte de dados para buscar os dados mais recentes do Looker com base nas especificações e configurações de objetos atuais. É possível usar o método spreadsheets.batchUpdate para chamar o RefreshDataSourceRequest. Em seguida, especifique uma ou mais referências de objeto para atualizar usando o objeto DataSourceObjectReferences.

É 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 de fonte de dados, uma execução em segundo plano é criada para buscar os dados do BigQuery ou do Looker e retornar uma resposta contendo o DataExecutionStatus. Se a execução for iniciada, o DataExecutionState geralmente estará no estado RUNNING.

Como o processo é assíncrono, o 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 o estado SUCCEEDED ou FAILED. A execução é concluída rapidamente na maioria dos casos, mas depende da complexidade da sua fonte de dados. Normalmente, a execução não ultrapassa 10 minutos.