Fogli connessi

Fogli connessi consente di analizzare petabyte di dati direttamente all'interno di Fogli Google. Puoi collegare i tuoi fogli di lavoro a un data warehouse BigQuery ed eseguire l'analisi utilizzando strumenti familiari di Fogli, come tabelle pivot, grafici e formule.

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

Campo Tipo Descrizione
parola STRING Una singola parola univoca (dove lo spazio vuoto rappresenta 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 questa parola è stata estratta.
corpus_date INTEGER L'anno in cui è stato pubblicato il corpus.

Se l'applicazione richiede dati di Fogli connessi, deve fornire un token OAuth 2.0 che conceda l'ambito bigquery.readonly, oltre agli altri ambiti necessari per una normale richiesta dell'API Fogli Google. Per ulteriori informazioni, consulta Scegliere gli ambiti dell'API Fogli Google.

Gestire un'origine dati

Un'origine dati specifica una località esterna in cui vengono trovati i dati. L'origine dati viene quindi collegata al foglio di lavoro.

Aggiungere un'origine dati BigQuery

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

"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 massimo 500 righe. L'anteprima non è disponibile immediatamente. Viene attivata in modo asincrono un'esecuzione per importare i dati di BigQuery.

Il AddDataSourceResponse contiene i seguenti campi:

  • dataSource: l'oggetto DataSource creato. dataSourceId è un ID univoco con ambito foglio di lavoro. Viene compilato e vi viene 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 esecuzione dati.

Aggiornare o eliminare un'origine dati

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

Gestire gli oggetti dell'origine dati

Dopo aver aggiunto un'origine dati al foglio di lavoro, è possibile creare un oggetto dell'origine dati a partire da questa. Un oggetto dell'origine dati è un normale strumento di Fogli, come tabelle pivot, grafici e formule, che si integra con Fogli connessi per ottimizzare l'analisi dei dati.

Esistono quattro tipi di oggetti:

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

Aggiungere una tabella dell'origine dati

Noto come "estrazione" nell'editor di Fogli, l'oggetto tabella importa un dump statico dei dati dall'origine dati in Fogli. Come 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 massimo 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 basato sul foglio di lavoro che identifica l'origine dati.

Dopo aver creato una tabella dell'origine dati, i dati non sono immediatamente disponibili. Nell'editor di Fogli, è visualizzata 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 dell'origine dati funzionano in modo simile. Per saperne di più, consulta Aggiornare un oggetto dell'origine dati.

Una volta completato l'aggiornamento e recuperati i 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 di Shakespeare.

Aggiungere una tabella pivot di origine dati

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 UpdateCellsRequest per creare una tabella pivot che mostra il conteggio totale delle parole per corpo.

"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 basato sul foglio di lavoro che identifica l'origine dati.

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

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

Aggiungere un grafico dell'origine dati

Il seguente esempio di codice mostra come utilizzare il metodo spreadsheets.batchUpdate e un AddChartRequest per creare un grafico dell'origine dati con 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 basato sul foglio di lavoro che identifica l'origine dati.

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

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

Aggiungere una formula dell'origine dati

Il seguente esempio di codice mostra come utilizzare il metodo spreadsheets.batchUpdate e un UpdateCellsRequest per creare una formula di 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 di BigQuery, la formula dell'origine dati viene compilata come mostrato di seguito:

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

Aggiornare un oggetto dell'origine dati

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

Tieni presente che puoi creare e aggiornare gli oggetti dell'origine dati all'interno di 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 e restituire una risposta contenente DataExecutionStatus. Se l'esecuzione viene avviata correttamente, DataExecutionState di solito è 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. In genere l'esecuzione non dura più di 10 minuti.