Fogli connessi

Fogli connessi consente di analizzare petabyte di dati direttamente in Fogli Google. Puoi collegare i fogli di lavoro a un BigQuery 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 pubblici Shakespeare di BigQuery 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 bianco è il delimitatore) estratta da un corpus.
word_count INTEGER Il numero di volte in cui questa parola appare in questo 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 a 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 Google Sheets. Per saperne di più, 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 spreadsheets.batchUpdate metodo. 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 associato DATA_SOURCE per fornire un'anteprima di un massimo di 500 righe. L'anteprima non è disponibile immediatamente. Viene attivata un'esecuzione asincrona per importare i dati di BigQuery.

AddDataSourceResponse contiene i seguenti campi:

  • dataSource: l'oggetto DataSource creato. The dataSourceId è un ID univoco con ambito del 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 di BigQuery nel foglio di anteprima. Per saperne di più, consulta la sezione Stato di esecuzione dei dati.

Aggiornare o eliminare un'origine dati BigQuery

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

Gestire gli oggetti dell'origine dati BigQuery

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

Esistono quattro tipi di oggetti:

  • Tabella DataSource
  • DataSource pivotTable
  • Grafico DataSource
  • Formula DataSource

Aggiungere una tabella dell'origine dati BigQuery

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

Il seguente esempio di codice mostra come utilizzare il spreadsheets.batchUpdate metodo 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 del foglio di lavoro che identifica l'origine dati.

Dopo aver creato 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 di 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 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 è supportata da un'origine dati e fa riferimento ai dati per nome della colonna. Il seguente esempio di codice mostra come utilizzare il metodo spreadsheets.batchUpdate e un UpdateCellsRequest per creare una tabella pivot che mostra 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 del 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 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 del 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 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"
}

Dopo aver recuperato 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 pubblici di Shakespeare.

Aggiornare un oggetto dell'origine dati BigQuery

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

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

Gestire un'origine dati Looker

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

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

Aggiungere un'origine dati Looker

Per aggiungere un'origine dati, fornisci un AddDataSourceRequest utilizzando il spreadsheets.batchUpdate metodo. 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 rispettivamente con un URI dell'istanza Looker, un nome del modello e un nome dell'esplorazione validi.

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

AddDataSourceResponse contiene i seguenti campi:

  • dataSource: l'oggetto DataSource creato. The dataSourceId è un ID univoco con ambito del 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 di BigQuery nel foglio di anteprima. Per saperne di più, consulta la sezione Stato di esecuzione dei dati.

Aggiornare o eliminare un'origine dati Looker

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

Gestire gli oggetti dell'origine dati Looker

Una volta aggiunta un'origine dati al foglio di lavoro, è possibile creare un oggetto dell'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 Looker.

Aggiornare un oggetto dell'origine dati Looker

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

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

Stato di esecuzione dei dati

Quando crei origini dati o aggiorni oggetti dell'origine 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, DataExecutionState è in genere nello stato RUNNING.

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