Páginas conectadas

Com as páginas conectadas, você pode analisar petabytes de dados diretamente no Planilhas Google. Você pode conectar suas planilhas a um data warehouse do BigQuery ou ao 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 do BigQuery 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 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 essa palavra foi extraída.
corpus_date INTEGER O ano em que este corpus foi publicado.

Se o aplicativo solicitar dados das Páginas Google conectadas ao BigQuery, ele precisará fornecer um token do 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.

Uma fonte de dados especifica um local externo em que os dados são encontrados. A fonte de dados é 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 do Google Cloud válido.

Depois que uma fonte de dados é criada, uma planilha DATA_SOURCE associada é criada para fornecer uma prévia de até 500 linhas. A prévia não fica 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 prévia. 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 de acordo com a situação.

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 com base nela. Um objeto de fonte de dados é uma ferramenta comum do Google Sheets, como tabelas dinâmicas, gráficos e fórmulas, integrada às páginas conectadas para impulsionar sua análise de dados.

Há quatro tipos de objetos:

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

Adicionar uma tabela de fonte de dados do BigQuery

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

Depois que uma tabela de fonte de dados é criada, os dados não ficam disponíveis imediatamente. No editor das 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 fonte de dados mostrando informações do conjunto de dados público de Shakespeare.

Adicionar uma tabela dinâmica de fonte de dados do BigQuery

Ao contrário de uma tabela dinâmica convencional, uma tabela dinâmica de fonte de dados é apoiada por uma fonte de dados e faz referência aos dados pelo nome da 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 identifica 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 mostrando informações do conjunto de dados público de Shakespeare.

Adicionar um gráfico de fonte 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 identifica a fonte de dados.

Depois que os dados do BigQuery são buscados, o gráfico da fonte de dados é renderizado conforme mostrado:

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

Adicionar uma fórmula de fonte de dados do BigQuery

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 que calcula a 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 conforme mostrado:

Fórmula da fonte de dados mostrando informações do conjunto de dados público de Shakespeare.

Atualizar um objeto de fonte de dados do BigQuery

É possível atualizar um objeto de fonte de dados para buscar os dados mais recentes do BigQuery com base nas especificações e configurações atuais da fonte de dados. Você pode 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 fonte de dados do Looker

Este guia mostra como adicionar, atualizar ou excluir uma fonte de dados do Looker, criar uma tabela dinâmica nela e atualizar.

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

Adicionar uma fonte de dados do Looker

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

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

Depois que uma fonte de dados é criada, uma planilha DATA_SOURCE associada é 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 prévia. 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 de acordo com a situação.

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 com base nela. 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 em fontes de dados do Looker.

Atualizar um objeto da fonte de dados do Looker

É possível atualizar um objeto de fonte de dados para buscar os dados mais recentes do Looker com base nas especificações e configurações de objeto atuais. Você pode 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 da execução de dados

Quando você cria fontes de dados ou atualiza objetos de fontes de dados, uma execução em segundo plano é criada para buscar os dados do BigQuery ou do Looker e retornar uma resposta que contém o DataExecutionStatus. Se a execução for iniciada corretamente, o DataExecutionState geralmente estará no estado RUNNING.

Como o processo é assíncrono, o aplicativo precisa implementar um modelo de sondagem para recuperar periodicamente o status dos objetos de 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 fonte de dados. Normalmente, a execução não leva mais de 10 minutos.