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, puis effectuer l'analyse à l'aide d'outils Sheets courants 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 délimiteur) extrait d'un corpus.
word_count INTEGER Nombre de fois où ce mot apparaît dans ce corpus.
corpus STRING L'œuvre dont ce mot a été extrait.
corpus_date INTEGER Année de publication de ce corpus.

Si votre application demande des données BigQuery Connected Sheets, 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 d'API Google Sheets standard. Pour en savoir plus, consultez Choisir les niveaux d'accès 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 la 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 au niveau de la 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 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 est ajoutée à la feuille de calcul, un objet de source de données peut être créé à partir de celle-ci. Un objet de source de données est un outil Sheets standard (tableaux croisés dynamiques, graphiques, formules, etc.) intégré aux feuilles connectées 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

Également appelé "extrait" dans l'éditeur Sheets, l'objet de 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 un tableau 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 à l'échelle de la feuille de calcul qui identifie la source de données.

Une fois la table de source de données créée, les données ne sont pas disponibles immédiatement. Dans l'éditeur Sheets, il s'affiche sous forme d'aperçu. Vous devez actualiser la table de 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 Actualiser un objet de 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 rempli comme suit :

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

Ajouter un tableau croisé dynamique de source de données BigQuery

Contrairement à un tableau croisé dynamique classique, un tableau croisé dynamique de 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 à l'échelle de la 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 type COLUMN, 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 à l'échelle de la 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 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 une UpdateCellsRequest pour créer une formule de source de données permettant 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 suit :

Formule de 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 dernières données de BigQuery en fonction des spécifications de la source de données et des configurations d'objet actuelles. Vous pouvez utiliser la méthode spreadsheets.batchUpdate pour appeler RefreshDataSourceRequest. Spécifiez ensuite une ou plusieurs références d'objet à actualiser à l'aide de l'objet DataSourceObjectReferences.

Notez que vous pouvez à la fois créer et actualiser des objets de source de données dans une même requête batchUpdate.

Gérer une source de données Looker

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

Votre application demandant 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 la 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 les vues, les dimensions, les mesures et les descriptions de champ.

AddDataSourceResponse contient les champs suivants :

  • dataSource : objet DataSource créé. dataSourceId est un ID unique au niveau de la 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 est ajoutée à la feuille de calcul, un objet de source de données peut être créé à partir de celle-ci. Pour les sources de données Looker, vous ne pouvez créer qu'un objet DataSource à partir de celles-ci.

Il n'est pas possible de créer des formules, des extraits et des 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 actuelles de la source de données et des configurations des objets. Vous pouvez utiliser la méthode spreadsheets.batchUpdate pour appeler RefreshDataSourceRequest. Spécifiez ensuite une ou plusieurs références d'objet à actualiser à l'aide de l'objet DataSourceObjectReferences.

Notez que vous pouvez à la fois créer et actualiser des objets de source de données dans une même requête batchUpdate.

État d'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 Looker et renvoyer une réponse contenant le DataExecutionStatus. Si l'exécution démarre correctement, l'DataExecutionState est généralement à l'état RUNNING.

Comme le processus est asynchrone, votre application doit implémenter un modèle d'interrogation pour récupérer régulièrement 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. Dans la plupart des cas, l'exécution se termine rapidement, 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.