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 (dove gli spazi sono i delimitatori) estratta da un corpus.
word_count INTEGER Il numero di volte in cui questa parola compare nel corpus.
corpus STRING L'opera da cui è stata estratta questa parola.
corpus_date INTEGER L'anno in cui è stato pubblicato questo corpus.

Se la tua applicazione richiede dati di Fogli connessi BigQuery, deve fornire un token OAuth 2.0 che conceda l'ambito bigquery.readonly, oltre agli altri ambiti richiesti per una normale richiesta dell'API Fogli Google. Per maggiori informazioni, consulta 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.

"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 è subito disponibile. Viene attivata un'esecuzione in modo asincrono per importare i dati di BigQuery.

AddDataSourceResponse contiene i seguenti campi:

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

  • dataExecutionStatus: lo stato di un'esecuzione che importa i dati di BigQuery nel foglio di anteprima. Per ulteriori informazioni, consulta la sezione Stato di 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 delle origini dati BigQuery

Una volta aggiunta un'origine dati al foglio di lavoro, da questa è possibile creare un oggetto origine dati. Un oggetto origine dati è uno strumento normale di Fogli, come tabelle pivot, grafici e formule, integrato con Fogli collegati per migliorare l'analisi dei dati.

Esistono quattro tipi di oggetti:

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

Aggiungere una tabella dell'origine dati BigQuery

Chiamato "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 viene 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 a livello di foglio di lavoro che identifica l'origine dati.

Una volta creata una tabella dell'origine dati, i dati non sono disponibili immediatamente. Nell'editor di Fogli viene 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 di origine dati funzionano in modo simile. Per ulteriori informazioni, consulta Aggiornare un oggetto origine dati.

Al termine dell'aggiornamento e del recupero dei dati di 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 è basata su 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 a livello di foglio di lavoro che identifica l'origine dati.

Dopo aver recuperato i dati di 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 COLONNA, 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 a livello di foglio di lavoro che identifica l'origine dati.

Dopo aver recuperato 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 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 numero medio di parole.

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

Dopo aver recuperato i dati di BigQuery, la formula dell'origine dati viene compilata come mostrato:

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

Aggiornare un oggetto dell'origine dati BigQuery

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

Tieni presente che puoi creare e aggiornare gli oggetti di origine dati all'interno di una singola richiestabatchUpdate.

Gestire un'origine dati di Looker

Questa guida illustra come aggiungere un'origine dati di Looker, aggiornarla o eliminarla, creare una tabella pivot e aggiornarla.

L'applicazione che richiede i dati di Fogli collegati di Looker riutilizzerà il collegamento del tuo Account Google a Looker esistente.

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.

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

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

Dopo aver creato un'origine dati, viene creato un foglio DATA_SOURCE associato per fornire un'anteprima della struttura dell'esplorazione selezionata, incluse visualizzazioni, dimensioni, misure ed eventuali descrizioni dei campi.

AddDataSourceResponse contiene i seguenti campi:

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

  • dataExecutionStatus: lo stato di un'esecuzione che importa i dati di BigQuery nel foglio di anteprima. Per ulteriori informazioni, consulta la sezione Stato di 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 delle origini dati di Looker

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

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

Aggiornare 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 e alle configurazioni degli oggetti dell'origine dati correnti. Puoi utilizzare il metodo spreadsheets.batchUpdate per chiamare RefreshDataSourceRequest. Specifica quindi uno o più riferimenti di oggetti da aggiornare utilizzando l'oggetto DataSourceObjectReferences.

Tieni presente che puoi creare e aggiornare gli oggetti di origine dati all'interno di una singola richiestabatchUpdate.

Stato di esecuzione dei dati

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

Poiché il processo è asincrono, l'applicazione deve implementare un modello di polling per recuperare periodicamente lo stato degli oggetti delle origini dati. Utilizza il metodo spreadsheets.get fino a quando lo stato non restituisce lo stato SUCCEEDED o FAILED. L'esecuzione viene completata rapidamente nella maggior parte dei casi, ma dipende dalla complessità della fonte di dati. In genere l'esecuzione non supera i 10 minuti.