Esta página foi traduzida pela API Cloud Translation.

Usar páginas conectadas

As páginas conectadas são um recurso das Planilhas Google que permite analisar dados do BigQuery e do Looker diretamente nas Planilhas. É possível acessar as páginas conectadas programaticamente com o serviço de planilhas.

Ações comuns das Páginas conectadas

Use as classes e os objetos DataSource para se conectar ao BigQuery ou ao Looker e analisar dados. A tabela a seguir lista as ações DataSource mais comuns e como criá-las no Apps Script:

Ação	Classe do Google Apps Script	Método a ser usado
Conectar uma planilha a uma fonte de dados compatível	`DataSourceSpec`	`SpreadsheetApp.newDataSourceSpec()`
Escolha uma fonte de dados	`DataSource`	`Spreadsheet.insertDataSourceSheet().getDataSource()`
Adicionar uma página de origem de dados	`DataSourceSheet`	`Spreadsheet.insertDataSourceSheet()`
Adicionar uma tabela dinâmica	`DataSourcePivotTable`	`Range.insertDataSourcePivotTable()`
Extrair dados	`DataSourceTable`	`Range.insertDataSourceTable()`
Usar uma fórmula	`DataSourceFormula`	`Range.setFormula()`
Adicionar um gráfico	`DataSourceChart`	`Sheet.insertDataSourceChart()`

Adicionar escopos de autorização obrigatórios

Para acessar os dados do BigQuery, inclua o método enableBigQueryExecution() no código do Google Apps Script. Esse método adiciona o escopo bigquery.readonly do OAuth necessário ao seu projeto do Google Apps Script.

O exemplo a seguir mostra o método SpreadsheetApp.enableBigQueryExecution() chamado em uma função:

function addDataSource() {
  SpreadsheetApp.enableBigQueryExecution();
  var spreadsheet = SpreadsheetApp.getActive();
  }

Para acessar os dados do Looker, inclua o método enableLookerExecution() no seu código do Google Apps Script. Ao acessar o Looker no Apps Script, o link da sua Conta do Google com o Looker é reutilizado.

A amostra a seguir mostra o método SpreadsheetApp.enableLookerExecution() chamado em uma função:

function addDataSource() {
  SpreadsheetApp.enableLookerExecution();
  var spreadsheet = SpreadsheetApp.getActive();
  }

Adicionar outros escopos do OAuth ao arquivo de manifesto

Ao se conectar ao BigQuery, a maioria dos escopos do OAuth é adicionada automaticamente ao arquivo de manifesto com base nas funções usadas no código. Se você precisar de outros escopos para acessar determinados dados do BigQuery, defina escopos explícitos.

Por exemplo, para consultar dados do BigQuery hospedados no Google Drive, adicione um escopo do OAuth do Drive ao arquivo de manifesto.

O exemplo a seguir mostra a parte oauthScopes de um arquivo de manifesto. Ele adiciona um escopo do OAuth do Drive além dos escopos mínimos necessários spreadsheet e bigquery.readonly do OAuth:

{ ...
  "oauthScopes": [
    "https://www.googleapis.com/auth/bigquery.readonly",
    "https://www.googleapis.com/auth/spreadsheets",
    "https://www.googleapis.com/auth/drive" ],
... }

Exemplo: criar e atualizar um objeto de fonte de dados

Os exemplos a seguir mostram como adicionar uma fonte de dados, criar um objeto de fonte de dados, atualizar esse objeto e ver o status de execução.

Adicionar uma fonte de dados

Os exemplos a seguir mostram como adicionar uma fonte de dados do BigQuery e do Looker, respectivamente.

BigQuery

Para adicionar uma origem de dados do BigQuery a uma planilha, insira uma folha de origem de dados com uma especificação de origem de dados. A folha de origem de dados é atualizada automaticamente para buscar dados de pré-visualização.

Substitua <YOUR_PROJECT_ID> abaixo por um ID de projeto válido do Google Cloud.

// For operations that fetch data from BigQuery, enableBigQueryExecution() must be called.
SpreadsheetApp.enableBigQueryExecution();
var spreadsheet = SpreadsheetApp.create('Test connected sheets');
Logger.log('New test spreadsheet: %s', spreadsheet.getUrl());

// Build data source spec by selecting a table.
var dataSourceSpec = SpreadsheetApp.newDataSourceSpec()
    .asBigQuery()
    .setProjectId('<YOUR_PROJECT_ID>')
    .setTableProjectId('bigquery-public-data')
    .setDatasetId('ncaa_basketball')
    .setTableId('mbb_historical_tournament_games')
    .build();
// Add data source and its associated data source sheet.
var dataSourceSheet = spreadsheet.insertDataSourceSheet(dataSourceSpec);
var dataSource = dataSourceSheet.getDataSource();

Looker

Para adicionar uma fonte de dados do Looker a uma planilha, insira uma página com uma especificação. A página é atualizada automaticamente para buscar dados de visualização.

Substitua <INSTANCE_URL>,<MODEL_NAME> e <EXPLORE_NAME> no exemplo a seguir por um URL de instância do Looker, nome do modelo e nome da análise válidas, respectivamente.

// For operations that fetch data from Looker, enableLookerExecution() must be called.
SpreadsheetApp.enableLookerExecution();
var spreadsheet = SpreadsheetApp.create('Test connected sheets');
Logger.log('New test spreadsheet: %s', spreadsheet.getUrl());

// Build data source spec by selecting a table.
var dataSourceSpec = SpreadsheetApp.newDataSourceSpec()
    .asLooker()
    .setInstanceUrl('<INSTANCE_URL>')
    .setModelName('<MODEL_NAME>')
    .setExploreName('<EXPLORE_NAME>')
    .build();
// Add data source and its associated data source sheet.
var dataSourceSheet = spreadsheet.insertDataSourceSheet(dataSourceSpec);
var dataSource = dataSourceSheet.getDataSource();

Adicionar um objeto de fonte de dados

Depois que a fonte de dados é adicionada à planilha, os objetos dela podem ser criados. Neste exemplo, uma tabela dinâmica é criada usando DataSourcePivotTable no dataSource do BigQuery criado no exemplo de código que adiciona uma fonte de dados do BigQuery.

Ao contrário dos dados normais em planilhas de grade que são referenciados por índice de célula ou notações A1, os dados de fontes de dados geralmente são referenciados por nomes de coluna. Portanto, a maioria dos setters de propriedade em objetos de fonte de dados usa o nome da coluna como entrada.

var rootCell = spreadsheet.insertSheet('pivotTableSheet').getRange('A1');

// Add data source pivot table and set data source specific configurations.
var dataSourcePivotTable = rootCell.createDataSourcePivotTable(dataSource);
var rowGroup = dataSourcePivotTable.addRowGroup('season');
rowGroup.sortDescending().setGroupLimit(5);
dataSourcePivotTable.addColumnGroup('win_school_ncaa');
dataSourcePivotTable.addPivotValue('win_pts', SpreadsheetApp.PivotTableSummarizeFunction.AVERAGE);
dataSourcePivotTable.addPivotValue('game_date', SpreadsheetApp.PivotTableSummarizeFunction.COUNTA);
var filterCriteria = SpreadsheetApp.newFilterCriteria()
    .whenTextEqualToAny(['Duke', 'North Carolina'])
    .build();
dataSourcePivotTable.addFilter('win_school_ncaa', filterCriteria);

// Get a regular pivot table instance and set shared configurations.
var pivotTable = dataSourcePivotTable.asPivotTable();
pivotTable.setValuesDisplayOrientation(SpreadsheetApp.Dimension.ROWS);

Atualizar um objeto da fonte de dados

É possível atualizar objetos da fonte de dados para buscar os dados mais recentes do BigQuery com base nas especificações da fonte de dados e nas configurações de objetos.

O processo de atualização de dados é assíncrono. Para atualizar um objeto de fonte de dados, use os seguintes métodos:

refreshData() inicia a execução da atualização de dados.
waitForCompletion() retorna o estado final quando a execução de dados é concluída. Isso elimina a necessidade de continuar pesquisando o status de execução.
DataExecutionStatus.getErrorCode() receberá o código do erro em caso de falha na execução dos dados.

O exemplo abaixo ilustra uma atualização dos dados da tabela dinâmica:

var status = dataSourcePivotTable.getStatus();
Logger.log('Initial state: %s', status.getExecutionState());

dataSourcePivotTable.refreshData();

status = dataSourcePivotTable.waitForCompletion(/* timeoutInSeconds= */ 60);
Logger.log('Ending state: %s', status.getExecutionState());
if (status.getExecutionState() == SpreadsheetApp.DataExecutionState.ERROR) {
  Logger.log('Error: %s (%s)', status.getErrorCode(), status.getErrorMessage());
}

Usar gatilhos com as páginas conectadas

Automatize as funções da fonte de dados das páginas conectadas com acionadores e eventos. Por exemplo, use acionadores baseados em tempo para atualizar objetos da fonte de dados repetidamente em um horário específico e acionadores de evento da planilha para acionar a execução de dados em um evento predefinido.

O exemplo a seguir adiciona uma fonte de dados do BigQuery com um parâmetro de consulta e refresca a página da fonte de dados quando o parâmetro de consulta é editado.

Substitua <YOUR_PROJECT_ID> abaixo por um ID de projeto válido do Google Cloud.

// Add data source with query parameter.
function addDataSource() {
  SpreadsheetApp.enableBigQueryExecution();
  var spreadsheet = SpreadsheetApp.getActive();

  // Add a new sheet and use A1 cell as the parameter cell.
  var parameterCell = spreadsheet.insertSheet('parameterSheet').getRange('A1');
parameterCell.setValue('Duke');

  // Add data source with query parameter.
  var dataSourceSpec = SpreadsheetApp.newDataSourceSpec()
      .asBigQuery()
      .setProjectId('<YOUR_PROJECT_ID>')
      .setRawQuery('select * from `bigquery-public-data`.`ncaa_basketball`.`mbb_historical_tournament_games` WHERE win_school_ncaa = @SCHOOL')
      .setParameterFromCell('SCHOOL', 'parameterSheet!A1')
      .build();
  var dataSourceSheet = spreadsheet.insertDataSourceSheet(dataSourceSpec);
  dataSourceSheet.asSheet().setName('ncaa_data');
}

// Function used to configure event trigger to refresh data source sheet.
function refreshOnParameterEdit(e) {
  var editedRange = e.range;
if (editedRange.getSheet().getName() != 'parameterSheet') {
  return;
}
// Check that the edited range includes A1.
if (editedRange.getRow() > 1 || editedRange.getColumn() > 1) {
   return;
}

  var spreadsheet = e.source;
  SpreadsheetApp.enableBigQueryExecution();
  spreadsheet.getSheetByName('ncaa_data').asDataSourceSheet().refreshData();
}

No exemplo acima, a função addDataSource() adiciona uma fonte de dados à planilha. Depois de executar addDataSource(), crie um acionador de evento no editor do Apps Script. Para saber como criar um gatilho de evento, consulte Gatilhos instaláveis.

Selecione as seguintes opções para seu gatilho:

Origem do evento: Da planilha
Tipo de evento: Em edição
Função a ser executada: refreshOnParameterEdit

Depois que o acionador é criado, a página da fonte de dados é atualizada automaticamente sempre que a célula de parâmetro é editada.

Resolver problemas

Mensagem de erro Resolução

Use enableBigQuery() para ativar execuções de dados para fontes de dados do BigQuery. Esse erro indica que SpreadsheetApp.enableBigQueryExecution() não é chamado antes de buscar dados do BigQuery.
Chame SpreadsheetApp.enableBigQueryExecution() em funções que usam métodos para execução do BigQuery.
Por exemplo, refreshData() nos objetos da fonte de dados, Spreadsheet.insertDataSourceTable() e DataSource.updateSpec().
Esses métodos exigem um escopo OAuth bigquery.readonly extra para funcionar.

Não é permitido realizar ações nas fontes de dados.
Entre em contato com o administrador para ativar o recurso. Esse erro indica que as páginas conectadas não estão ativadas na conta.
As páginas conectadas estão disponíveis apenas para Google Workspace usuários com determinadas assinaturas.
Entre em contato com o administrador para ativar o recurso.

Mensagem de erro	Resolução
Use `enableBigQuery()` para ativar execuções de dados para fontes de dados do BigQuery.	Esse erro indica que `SpreadsheetApp.enableBigQueryExecution()` não é chamado antes de buscar dados do BigQuery. Chame `SpreadsheetApp.enableBigQueryExecution()` em funções que usam métodos para execução do BigQuery. Por exemplo, `refreshData()` nos objetos da fonte de dados, `Spreadsheet.insertDataSourceTable()` e `DataSource.updateSpec()`. Esses métodos exigem um escopo OAuth bigquery.readonly extra para funcionar.
Não é permitido realizar ações nas fontes de dados. Entre em contato com o administrador para ativar o recurso.	Esse erro indica que as páginas conectadas não estão ativadas na conta. As páginas conectadas estão disponíveis apenas para Google Workspace usuários com determinadas assinaturas. Entre em contato com o administrador para ativar o recurso.