Fogli connessi

Fogli connessi consente di analizzare petabyte di dati direttamente in Fogli Google. Puoi collegare i tuoi fogli di lavoro a un data warehouse BigQuery o a Looker ed eseguire l'analisi utilizzando gli strumenti di Fogli che già conosci, come tabelle pivot, grafici e formule.

Gestire un'origine dati BigQuery

Questa sezione utilizza il set di dati pubblico BigQuery Shakespeare per mostrare come utilizzare Fogli connessi. Il set di dati contiene le seguenti informazioni:

Campo Tipo Descrizione
parola STRING Una singola parola univoca (in cui lo spazio bianco è il delimitatore) estratta da un corpus.
word_count INTEGER Il numero di volte in cui questa parola compare in questo corpus.
corpus STRING L'opera da cui è stata estratta la parola.
corpus_date INTEGER L'anno in cui è stato pubblicato questo corpus.

Se la tua applicazione richiede dati di BigQuery Fogli connessi, deve fornire un token OAuth 2.0 che conceda l'ambito bigquery.readonly, oltre agli altri ambiti richiesti per una normale richiesta dell'API Google Sheets. Per maggiori informazioni, vedi Scegliere gli ambiti dell'API Google Sheets.

Un'origine dati specifica una posizione esterna in cui si trovano i dati. L'origine dati viene quindi collegata al foglio di lavoro.

Aggiungere un'origine dati BigQuery

Per aggiungere un'origine dati, fornisci un AddDataSourceRequest utilizzando il metodo spreadsheets.batchUpdate. Il corpo della richiesta deve specificare un campo dataSource di tipo DataSource oggetto.

"addDataSource":{
   "dataSource":{
      "spec":{
         "bigQuery":{
            "projectId":"PROJECT_ID",
            "tableSpec":{
               "tableProjectId":"bigquery-public-data",
               "datasetId":"samples",
               "tableId":"shakespeare"
            }
         }
      }
   }
}

Sostituisci PROJECT_ID con un ID progetto Google Cloud valido.

Dopo aver creato un'origine dati, viene creato un foglio DATA_SOURCE associato per fornire un'anteprima di un massimo di 500 righe. L'anteprima non è disponibile immediatamente. Viene attivata un'esecuzione asincrona per importare i dati BigQuery.

Il AddDataSourceResponse contiene i seguenti campi:

  • dataSource: l'oggetto DataSource creato. dataSourceId è un ID univoco con ambito foglio di lavoro. Viene compilato e fatto riferimento per creare ogni oggetto DataSource dall'origine dati.

  • dataExecutionStatus: lo stato di un'esecuzione che importa i dati BigQuery nel foglio di anteprima. Per ulteriori informazioni, consulta la sezione Stato dell'esecuzione dei dati.

Aggiornare o eliminare un'origine dati BigQuery

Utilizza il metodo spreadsheets.batchUpdate e fornisci una richiesta UpdateDataSourceRequest o DeleteDataSourceRequest di conseguenza.

Gestire gli oggetti dell'origine dati BigQuery

Una volta aggiunta un'origine dati al foglio di lavoro, è possibile creare un oggetto origine dati. Un oggetto origine dati è un normale strumento di Fogli come tabelle pivot, grafici e formule integrati con Fogli connessi per potenziare l'analisi dei dati.

Esistono quattro tipi di oggetti:

  • DataSource tabella
  • DataSource pivotTable
  • Grafico DataSource
  • Formula DataSource

Aggiungere una tabella di origine dati BigQuery

Noto come "estrazione" nell'editor Fogli, l'oggetto tabella importa in Fogli un dump statico dei dati dall'origine dati. Simile a una tabella pivot, la tabella è specificata e ancorata alla cella in alto a sinistra.

Il seguente esempio di codice mostra come utilizzare il metodo spreadsheets.batchUpdate e un UpdateCellsRequest per creare una tabella dell'origine dati con un massimo di 1000 righe di due colonne (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"
}

Sostituisci DATA_SOURCE_ID con un ID univoco con ambito foglio di lavoro che identifica l'origine dati.

Dopo la creazione di una tabella dell'origine dati, i dati non sono immediatamente disponibili. Nell'editor di Fogli, viene visualizzato come anteprima. Devi aggiornare la tabella dell'origine dati per recuperare i dati BigQuery. Puoi specificare un RefreshDataSourceRequest all'interno dello stesso batchUpdate. Tieni presente che tutti gli oggetti di origine dati funzionano in modo simile. Per ulteriori informazioni, vedi Aggiornare un oggetto origine dati.

Al termine dell'aggiornamento e del recupero dei dati BigQuery, la tabella dell'origine dati viene compilata come mostrato di seguito:

Tabella dell'origine dati che mostra i dati del set di dati pubblico Shakespeare.

Aggiungere una tabella pivot dell'origine dati BigQuery

A differenza di una tabella pivot convenzionale, una tabella pivot dell'origine dati è supportata da un'origine dati e fa riferimento ai dati in base al nome della colonna. Il seguente esempio di codice mostra come utilizzare il metodo spreadsheets.batchUpdate e un UpdateCellsRequest per creare una tabella pivot che mostri il conteggio totale delle parole per corpus.

"updateCells":{
   "rows":{
      "values":[
         {
            "pivotTable":{
               "dataSourceId":"DATA_SOURCE_ID",
               "rows":{
                  "dataSourceColumnReference":{
                     "name":"corpus"
                  },
                  "sortOrder":"ASCENDING"
               },
               "values":{
                  "summarizeFunction":"SUM",
                  "dataSourceColumnReference":{
                     "name":"word_count"
                  }
               }
            }
         }
      ]
   },
   "fields":"pivotTable"
    }

Sostituisci DATA_SOURCE_ID con un ID univoco con ambito foglio di lavoro che identifica l'origine dati.

Una volta recuperati i dati BigQuery, la tabella pivot dell'origine dati viene compilata come mostrato di seguito:

Tabella pivot dell'origine dati che mostra i dati del set di dati pubblico di Shakespeare.

Aggiungere un grafico dell'origine dati BigQuery

Il seguente esempio di codice mostra come utilizzare il metodo spreadsheets.batchUpdate e un AddChartRequest per creare un grafico dell'origine dati con un chartType di COLUMN, che mostra il conteggio totale delle parole per 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"
      }
   }
}

Sostituisci DATA_SOURCE_ID con un ID univoco con ambito foglio di lavoro che identifica l'origine dati.

Una volta recuperati i dati BigQuery, il grafico dell'origine dati viene visualizzato come segue:

Grafico dell'origine dati che mostra i dati del set di dati pubblici di Shakespeare.

Aggiungere una formula dell'origine dati BigQuery

Il seguente esempio di codice mostra come utilizzare il metodo spreadsheets.batchUpdate e un UpdateCellsRequest per creare una formula dell'origine dati per calcolare il conteggio medio delle parole.

"updateCells":{
   "rows":[
      {
         "values":[
            {
               "userEnteredValue":{
                  "formulaValue":"=AVERAGE(shakespeare!word_count)"
               }
            }
         ]
      }
   ],
   "fields":"userEnteredValue"
}

Una volta recuperati i dati BigQuery, la formula dell'origine dati viene compilata come mostrato di seguito:

Formula dell'origine dati che mostra i dati del set di dati pubblici di Shakespeare.

Aggiornare un oggetto di origine dati BigQuery

Puoi aggiornare un oggetto di origine dati per recuperare i dati più recenti da BigQuery in base alle specifiche dell'origine dati e alle configurazioni degli oggetti correnti. Puoi utilizzare il metodo spreadsheets.batchUpdate per chiamare RefreshDataSourceRequest. Specifica quindi uno o più riferimenti agli oggetti da aggiornare utilizzando l'oggetto DataSourceObjectReferences.

Tieni presente che puoi creare e aggiornare gli oggetti dell'origine dati in una singola richiesta batchUpdate.

Gestire un'origine dati di Looker

Questa guida mostra come aggiungere, aggiornare o eliminare un'origine dati di Looker, creare una tabella pivot e aggiornarla.

La tua applicazione che richiede dati di Fogli connessi di Looker riutilizzerà il collegamento esistente dell'Account Google con Looker.

Aggiungere un'origine dati di Looker

Per aggiungere un'origine dati, fornisci un AddDataSourceRequest utilizzando il metodo spreadsheets.batchUpdate. Il corpo della richiesta deve specificare un campo dataSource di tipo DataSource oggetto.

"addDataSource":{
   "dataSource":{
      "spec":{
         "looker":{
            "instance_uri":"INSTANCE_URI",
            "model":"MODEL",
            "explore":"EXPLORE"
         }
      }
   }
}

Sostituisci INSTANCE_URI, MODEL e EXPLORE con un URI dell'istanza di Looker, un nome del modello e un nome dell'esplorazione validi.

Una volta creata un'origine dati, viene creato un foglio DATA_SOURCE associato per fornire un'anteprima della struttura dell'esplorazione selezionata, incluse viste, dimensioni, misure e descrizioni dei campi.

Il AddDataSourceResponse contiene i seguenti campi:

  • dataSource: l'oggetto DataSource creato. dataSourceId è un ID univoco con ambito foglio di lavoro. Viene compilato e fatto riferimento per creare ogni oggetto DataSource dall'origine dati.

  • dataExecutionStatus: lo stato di un'esecuzione che importa i dati BigQuery nel foglio di anteprima. Per ulteriori informazioni, consulta la sezione Stato dell'esecuzione dei dati.

Aggiornare o eliminare un'origine dati di Looker

Utilizza il metodo spreadsheets.batchUpdate e fornisci una richiesta UpdateDataSourceRequest o DeleteDataSourceRequest di conseguenza.

Gestire gli oggetti dell'origine dati di Looker

Una volta aggiunta un'origine dati al foglio di lavoro, è possibile creare un oggetto origine dati. Per le origini dati Looker, puoi creare solo un oggetto DataSource pivotTable.

Non è possibile creare formule, estrazioni e grafici DataSource dalle origini dati di Looker.

Aggiorna un oggetto di origine dati di Looker

Puoi aggiornare un oggetto dell'origine dati per recuperare i dati più recenti da Looker in base alle specifiche dell'origine dati e alle configurazioni degli oggetti correnti. Puoi utilizzare il metodo spreadsheets.batchUpdate per chiamare RefreshDataSourceRequest. Specifica quindi uno o più riferimenti agli oggetti da aggiornare utilizzando l'oggetto DataSourceObjectReferences.

Tieni presente che puoi creare e aggiornare gli oggetti dell'origine dati in una singola richiesta batchUpdate.

Stato di esecuzione dei dati

Quando crei origini dati o aggiorni gli oggetti delle origini dati, viene creata un'esecuzione in background per recuperare i dati da BigQuery o Looker e restituire una risposta contenente DataExecutionStatus. Se l'esecuzione viene avviata correttamente, il DataExecutionState si trova in genere nello stato RUNNING.

Poiché il processo è asincrono, l'applicazione deve implementare un modello di polling per recuperare periodicamente lo stato degli oggetti dell'origine dati. Utilizza il metodo spreadsheets.get finché lo stato non restituisce lo stato SUCCEEDED o FAILED. L'esecuzione viene completata rapidamente nella maggior parte dei casi, ma dipende dalla complessità dell'origine dati. Di solito l'esecuzione non supera i 10 minuti.