Questa pagina è stata tradotta dall'API Cloud Translation.

Utilizzare Fogli connessi

Fogli connessi è una funzionalità di Fogli Google che ti consente di analizzare i dati di BigQuery e Looker direttamente in Fogli. Puoi accedere a Fogli connessi programmaticamente con il servizio Fogli.

Azioni comuni di Fogli connessi

Utilizza le classi e gli oggetti DataSource per connetterti a BigQuery o Looker e analizzare i dati. Nella tabella seguente sono elencate le azioni DataSource più comuni e come crearle in Apps Script:

Azione	lezione Google Apps Script	Metodo da utilizzare
Collegare un foglio a un'origine dati supportata	`DataSourceSpec`	`SpreadsheetApp.newDataSourceSpec()`
Scegli un'origine dati	`DataSource`	`Spreadsheet.insertDataSourceSheet().getDataSource()`
Aggiungere un foglio di origine dati	`DataSourceSheet`	`Spreadsheet.insertDataSourceSheet()`
Aggiungere una tabella pivot	`DataSourcePivotTable`	`Range.insertDataSourcePivotTable()`
Recuperare i dati in un'estrazione	`DataSourceTable`	`Range.insertDataSourceTable()`
Utilizzare una formula	`DataSourceFormula`	`Range.setFormula()`
Aggiungi un grafico	`DataSourceChart`	`Sheet.insertDataSourceChart()`

Aggiungi gli ambiti di autorizzazione richiesti

Per accedere ai dati BigQuery, devi includere il metodo enableBigQueryExecution() nel codice di Google Apps Script. Questo metodo aggiunge l'ambito OAuth bigquery.readonly obbligatorio al tuo progetto Google Apps Script.

L'esempio seguente mostra il metodo SpreadsheetApp.enableBigQueryExecution() chiamato all'interno di una funzione:

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

Per accedere ai dati di Looker, devi includere il metodo enableLookerExecution() nel codice di Google Apps Script. L'accesso a Looker in Apps Script riutilizzerà il collegamento del tuo Account Google esistente con Looker.

L'esempio seguente mostra il metodo SpreadsheetApp.enableLookerExecution() chiamato all'interno di una funzione:

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

Aggiungi ulteriori ambiti OAuth al file manifest

Quando esegui la connessione a BigQuery, la maggior parte degli ambiti OAuth viene aggiunta automaticamente al file manifest in base alle funzioni utilizzate nel codice. Se hai bisogno di scopi aggiuntivi per accedere a determinati dati BigQuery, puoi impostare scopi espliciti.

Ad esempio, per eseguire query sui dati BigQuery ospitati in Google Drive, devi aggiungere un ambito OAuth di Drive al file manifest.

L'esempio seguente mostra la parte oauthScopes di un file manifest. Aggiunge un ambito OAuth di Drive oltre agli ambiti OAuth spreadsheet e bigquery.readonly minimi richiesti:

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

Esempio: crea e aggiorna un oggetto di origine dati

Gli esempi riportati di seguito mostrano come aggiungere un'origine dati, creare un oggetto dell'origine dati dall'origine dati, aggiornare l'oggetto dell'origine dati e ottenere lo stato di esecuzione.

Aggiungere un'origine dati

Gli esempi riportati di seguito mostrano come aggiungere rispettivamente un'origine dati BigQuery e un'origine dati Looker.

BigQuery

Per aggiungere un'origine dati BigQuery a un foglio di lavoro, inserisci un foglio di origine dati con una specifica dell'origine dati. Il foglio dell'origine dati viene aggiornato automaticamente per recuperare i dati di anteprima.

Sostituisci <YOUR_PROJECT_ID> di seguito con un ID progetto Google Cloud valido.

// 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

Per aggiungere un'origine dati Looker a un foglio di lavoro, inserisci un foglio di origine dati con una specifica dell'origine dati. Il foglio dell'origine dati viene aggiornato automaticamente per recuperare i dati di anteprima.

Sostituisci <INSTANCE_URL>, <MODEL_NAME>, <EXPLORE_NAME> nel seguente esempio con un URL istanza Looker, un nome modello e un nome esplorazione validi, rispettivamente.

// 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();

Aggiungere un oggetto dell'origine dati

Dopo aver aggiunto l'origine dati al foglio di lavoro, puoi creare gli oggetti dell'origine dati dall'origine dati. In questo esempio viene creata una tabella pivot utilizzando DataSourcePivotTable su BigQuery dataSource creato nel codice di esempio che aggiunge un origine dati BigQuery.

A differenza dei dati regolari nei fogli di lavoro a griglia a cui viene fatto riferimento tramite l'indice di cella o le notazioni A1, i dati delle origini dati vengono solitamente indicati tramite i nomi delle colonne. Pertanto, la maggior parte degli impostatori delle proprietà negli oggetti origine dati utilizza il nome della colonna come input.

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);

Aggiornare un oggetto di origine dati

Puoi aggiornare gli oggetti dell'origine dati per recuperare i dati più recenti da BigQuery in base alle specifiche dell'origine dati e alle configurazioni degli oggetti.

Il processo di aggiornamento dei dati è asincrono. Per aggiornare un oggetto dell'origine dati, utilizza i seguenti metodi:

refreshData() avvia l'esecuzione dell'aggiornamento dei dati.
waitForCompletion() restituisce lo stato finale al termine dell'esecuzione dei dati. In questo modo non è necessario continuare a eseguire il polling dello stato di esecuzione.
DataExecutionStatus.getErrorCode() riceve il codice di errore nel caso in cui l'esecuzione dei dati non vada a buon fine.

L'esempio seguente illustra un aggiornamento dei dati della tabella pivot:

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());
}

Utilizzare gli attivatori con Fogli connessi

Automatizza le funzioni dell'origine dati di Fogli connessi con trigger ed eventi. Ad esempio, utilizza gli attivatori basati sul tempo per aggiornare ripetutamente gli oggetti dell'origine dati in un momento specifico e gli attivatori di eventi della cartella di lavoro per attivare l'esecuzione dei dati in base a un evento predefinito.

Il seguente esempio aggiunge un'origine dati BigQuery con un parametro di query e aggiorna il foglio dell'origine dati quando il parametro di query viene modificato.

Sostituisci <YOUR_PROJECT_ID> di seguito con un ID progetto Google Cloud valido.

// 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();
}

Nell'esempio precedente, la funzione addDataSource() aggiunge un'origine dati al foglio di lavoro. Dopo aver eseguito addDataSource(), crea un attivatore di eventi nell'editor di Apps Script. Per scoprire come creare un trigger evento, consulta Trigger installabili.

Seleziona le seguenti opzioni per l'attivatore:

Origine evento: Da foglio di lavoro
Tipo di evento: Durante la modifica
Funzione da eseguire: refreshOnParameterEdit

Una volta creato l'attivatore, il foglio dell'origine dati viene aggiornato automaticamente ogni volta che la cella del parametro viene modificata.

Risoluzione dei problemi

Messaggio di errore Risoluzione

Utilizza enableBigQuery() per attivare l'esecuzione dei dati per le origini dati BIGQUERY. Questo errore indica che SpreadsheetApp.enableBigQueryExecution() non viene chiamato prima del recupero dei dati di BigQuery.
Chiama SpreadsheetApp.enableBigQueryExecution() nelle funzioni che utilizzano metodi per l'esecuzione di BigQuery.
Ad esempio, refreshData() negli oggetti dell'origine dati, Spreadsheet.insertDataSourceTable() e DataSource.updateSpec().
Per funzionare, questi metodi richiedono un ambito OAuth bigquery.readonly aggiuntivo.

Azioni sulle origini dati non consentite.
Contatta l'amministratore per attivare la funzionalità. Questo errore indica che nell'account non è attivato Fogli connessi.
Fogli connessi è disponibile solo per Google Workspace gli utenti con determinati abbonamenti.
Contatta l'amministratore per attivare la funzionalità.

Messaggio di errore	Risoluzione
Utilizza `enableBigQuery()` per attivare l'esecuzione dei dati per le origini dati BIGQUERY.	Questo errore indica che `SpreadsheetApp.enableBigQueryExecution()` non viene chiamato prima del recupero dei dati di BigQuery. Chiama `SpreadsheetApp.enableBigQueryExecution()` nelle funzioni che utilizzano metodi per l'esecuzione di BigQuery. Ad esempio, `refreshData()` negli oggetti dell'origine dati, `Spreadsheet.insertDataSourceTable()` e `DataSource.updateSpec()`. Per funzionare, questi metodi richiedono un ambito OAuth bigquery.readonly aggiuntivo.
Azioni sulle origini dati non consentite. Contatta l'amministratore per attivare la funzionalità.	Questo errore indica che nell'account non è attivato Fogli connessi. Fogli connessi è disponibile solo per Google Workspace gli utenti con determinati abbonamenti. Contatta l'amministratore per attivare la funzionalità.