Feuilles connectées

Les feuilles connectées vous permettent d'analyser des pétaoctets de données directement dans Google Sheets. Vous pouvez connecter vos feuilles de calcul à un entrepôt de données BigQuery ou à Looker, et effectuer l'analyse à l'aide d'outils Sheets familiers, tels que les tableaux croisés dynamiques, les graphiques et les formules.

Gérer une source de données BigQuery

Cette section utilise l'ensemble de données public BigQuery Shakespeare pour vous montrer comment utiliser les feuilles connectées. L'ensemble de données contient les informations suivantes:

Champ Type Description
mot STRING Mot unique (où l'espace est le séparateur) extrait d'un corpus.
word_count INTEGER Nombre de fois où ce mot apparaît dans ce corpus.
corpus STRING Oeuvre à partir de laquelle ce mot a été extrait.
corpus_date INTEGER Année de publication de ce corpus.

Si votre application demande des données de feuilles connectées BigQuery, elle doit fournir un jeton OAuth 2.0 qui accorde le champ d'application bigquery.readonly, en plus des autres champs d'application requis pour une requête API Google Sheets standard. Pour en savoir plus, consultez Choisir les habilitations de l'API Google Sheets.

Une source de données spécifie un emplacement externe où se trouvent les données. La source de données est ensuite connectée à la feuille de calcul.

Ajouter une source de données BigQuery

Pour ajouter une source de données, fournissez un AddDataSourceRequest à l'aide de la méthode spreadsheets.batchUpdate. Le corps de la requête doit spécifier un champ dataSource de type objet DataSource.

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

Remplacez PROJECT_ID par un ID de projet Google Cloud valide.

Une fois une source de données créée, une feuille DATA_SOURCE associée est créée pour fournir un aperçu de 500 lignes maximum. L'aperçu n'est pas disponible immédiatement. Une exécution est déclenchée de manière asynchrone pour importer les données BigQuery.

AddDataSourceResponse contient les champs suivants:

  • dataSource: objet DataSource créé. dataSourceId est un ID unique de portée feuille de calcul. Il est renseigné et référencé pour créer chaque objet DataSource à partir de la source de données.

  • dataExecutionStatus: état d'une exécution qui importe des données BigQuery dans la feuille d'aperçu. Pour en savoir plus, consultez la section État de l'exécution des données.

Modifier ou supprimer une source de données BigQuery

Utilisez la méthode spreadsheets.batchUpdate et fournissez une requête UpdateDataSourceRequest ou DeleteDataSourceRequest en conséquence.

Gérer les objets de source de données BigQuery

Une fois qu'une source de données a été ajoutée à la feuille de calcul, vous pouvez créer un objet source de données à partir de celle-ci. Un objet source de données est un outil Sheets standard, tel que des tableaux croisés dynamiques, des graphiques et des formules, qui est intégré à Sheets connecté pour alimenter votre analyse de données.

Il existe quatre types d'objets:

  • DataSource table
  • DataSource pivotTable
  • Graphique "DataSource"
  • Formule DataSource

Ajouter une table de source de données BigQuery

Appelé "extrait" dans l'éditeur Sheets, l'objet table importe un vidage statique des données de la source de données dans Sheets. Comme pour un tableau croisé dynamique, le tableau est spécifié et ancré à la cellule en haut à gauche.

L'exemple de code suivant montre comment utiliser la méthode spreadsheets.batchUpdate et un UpdateCellsRequest pour créer une table de source de données comportant jusqu'à 1 000 lignes de deux colonnes (word et word_count).

"updateCells":{
   "rows":{
      "values":[
         {
            "dataSourceTable":{
               "dataSourceId":"DATA_SOURCE_ID",
               "columns":[
                  {
                     "name":"word"
                  },
                  {
                     "name":"word_count"
                  }
               ],
               "rowLimit":{
                  "value":1000
               },
               "columnSelectionType":"SELECTED"
            }
         }
      ]
   },
   "fields":"dataSourceTable"
}

Remplacez DATA_SOURCE_ID par un ID unique de portée feuille de calcul qui identifie la source de données.

Une fois la table de la source de données créée, les données ne sont pas immédiatement disponibles. Dans l'éditeur Sheets, elle s'affiche sous forme d'aperçu. Vous devez actualiser la table de la source de données pour extraire les données BigQuery. Vous pouvez spécifier un RefreshDataSourceRequest dans le même batchUpdate. Notez que tous les objets de source de données fonctionnent de la même manière. Pour en savoir plus, consultez la section Actualiser un objet source de données.

Une fois l'actualisation terminée et les données BigQuery récupérées, le tableau de la source de données est renseigné comme indiqué:

Tableau de la source de données affichant les données de l'ensemble de données public Shakespeare.

Ajouter un tableau croisé dynamique à partir d'une source de données BigQuery

Contrairement à un tableau croisé dynamique classique, un tableau croisé dynamique basé sur une source de données est basé sur une source de données et fait référence aux données par nom de colonne. L'exemple de code suivant montre comment utiliser la méthode spreadsheets.batchUpdate et un UpdateCellsRequest pour créer un tableau croisé dynamique affichant le nombre total de mots par corpus.

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

Remplacez DATA_SOURCE_ID par un ID unique de portée feuille de calcul qui identifie la source de données.

Une fois les données BigQuery récupérées, le tableau croisé dynamique de la source de données est renseigné comme suit:

Tableau croisé dynamique de la source de données affichant les données de l'ensemble de données public Shakespeare.

Ajouter un graphique de source de données BigQuery

L'exemple de code suivant montre comment utiliser la méthode spreadsheets.batchUpdate et un AddChartRequest pour créer un graphique de source de données avec un chartType de COLONNE, affichant le nombre total de mots par 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"
      }
   }
}

Remplacez DATA_SOURCE_ID par un ID unique de portée feuille de calcul qui identifie la source de données.

Une fois les données BigQuery récupérées, le graphique de la source de données s'affiche comme suit:

Graphique de la source de données affichant les données de l'ensemble de données public Shakespeare.

Ajouter une formule de source de données BigQuery

L'exemple de code suivant montre comment utiliser la méthode spreadsheets.batchUpdate et un UpdateCellsRequest pour créer une formule de source de données afin de calculer le nombre moyen de mots.

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

Une fois les données BigQuery récupérées, la formule de la source de données est renseignée comme indiqué:

Formule de la source de données affichant les données de l'ensemble de données public Shakespeare.

Actualiser un objet de source de données BigQuery

Vous pouvez actualiser un objet de source de données pour extraire les données les plus récentes de BigQuery en fonction des spécifications et des configurations d'objet actuelles de la source de données. Vous pouvez utiliser la méthode spreadsheets.batchUpdate pour appeler RefreshDataSourceRequest. Spécifiez ensuite une ou plusieurs références d'objets à actualiser à l'aide de l'objet DataSourceObjectReferences.

Notez que vous pouvez créer et actualiser des objets de source de données dans une seule requête batchUpdate.

Gérer une source de données Looker

Ce guide explique comment ajouter une source de données Looker, la mettre à jour ou la supprimer, créer un tableau croisé dynamique à partir d'elle et l'actualiser.

Votre application qui demande des données Looker Sheets connectées réutilisera votre association de compte Google existante avec Looker.

Ajouter une source de données Looker

Pour ajouter une source de données, fournissez un AddDataSourceRequest à l'aide de la méthode spreadsheets.batchUpdate. Le corps de la requête doit spécifier un champ dataSource de type objet DataSource.

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

Remplacez INSTANCE_URI, MODEL et EXPLORE par un URI d'instance Looker, un nom de modèle et un nom d'exploration valides, respectivement.

Une fois une source de données créée, une feuille DATA_SOURCE associée est créée pour fournir un aperçu de la structure de l'exploration sélectionnée, y compris des vues, des dimensions, des mesures et des descriptions de champs.

AddDataSourceResponse contient les champs suivants:

  • dataSource: objet DataSource créé. dataSourceId est un ID unique de portée feuille de calcul. Il est renseigné et référencé pour créer chaque objet DataSource à partir de la source de données.

  • dataExecutionStatus: état d'une exécution qui importe des données BigQuery dans la feuille d'aperçu. Pour en savoir plus, consultez la section État de l'exécution des données.

Mettre à jour ou supprimer une source de données Looker

Utilisez la méthode spreadsheets.batchUpdate et fournissez une requête UpdateDataSourceRequest ou DeleteDataSourceRequest en conséquence.

Gérer les objets de source de données Looker

Une fois qu'une source de données a été ajoutée à la feuille de calcul, vous pouvez créer un objet source de données à partir de celle-ci. Pour les sources de données Looker, vous ne pouvez créer qu'un objet DataSource pivotTable à partir de celles-ci.

Vous ne pouvez pas créer de formules, d'extraits ni de graphiques DataSource à partir de sources de données Looker.

Actualiser un objet de source de données Looker

Vous pouvez actualiser un objet de source de données pour récupérer les dernières données de Looker en fonction des spécifications et des configurations d'objet actuelles de la source de données. Vous pouvez utiliser la méthode spreadsheets.batchUpdate pour appeler RefreshDataSourceRequest. Spécifiez ensuite une ou plusieurs références d'objets à actualiser à l'aide de l'objet DataSourceObjectReferences.

Notez que vous pouvez créer et actualiser des objets de source de données dans une seule requête batchUpdate.

État de l'exécution des données

Lorsque vous créez des sources de données ou actualisez des objets de source de données, une exécution en arrière-plan est créée pour extraire les données de BigQuery ou de Looker et renvoyer une réponse contenant le DataExecutionStatus. Si l'exécution démarre correctement, DataExecutionState est généralement à l'état RUNNING.

Étant donné que le processus est asynchrone, votre application doit implémenter un modèle de sondage pour récupérer périodiquement l'état des objets de source de données. Utilisez la méthode spreadsheets.get jusqu'à ce que l'état renvoie l'état SUCCEEDED ou FAILED. L'exécution se termine rapidement dans la plupart des cas, mais cela dépend de la complexité de votre source de données. L'exécution ne dépasse généralement pas 10 minutes.