Exporter vers BigQuery

Cet article explique comment exporter les métadonnées d'éléments pour votre organisation, votre dossier ou votre projet vers une table BigQuery, puis comment exécuter une analyse de données sur votre inventaire. BigQuery offre aux utilisateurs une expérience semblable à SQL pour analyser des données et produire des insights pertinents sans avoir à utiliser de scripts personnalisés.

Avant de commencer

Avant de commencer, suivez les étapes ci-dessous.

1. Activez l'API Cloud Asset Inventory sur le projet dans lequel vous allez exécuter les commandes de l'API.
   Activez l'API Cloud Asset Inventory

2. Configurez les autorisations requises pour appeler l'API Cloud Asset Inventory à l'aide de l'outil gcloud ou de l'API.

3. Pour configurer votre environnement, procédez comme suit :

   gcloud

   Pour configurer votre environnement afin d'utiliser l'outil gcloud pour appeler l'API Cloud Asset Inventory, installez le SDK Cloud sur votre client local.

   API

   Pour configurer votre environnement afin d'appeler l'API Cloud Asset Inventory avec la commande Unix curl, procédez comme suit :

   1. Installez oauth2l sur votre ordinateur local, de façon à pouvoir interagir avec le système Google OAuth.
   2. Vérifiez que vous avez accès à la commande Unix curl.

   3. Assurez-vous d'attribuer à votre compte l'un des rôles suivants sur votre projet, votre dossier ou votre organisation.

      • Rôle Lecteur d'éléments cloud (roles/cloudasset.viewer)
      • Rôle de base Propriétaire (roles/owner)

4. Si vous effectuez une exportation vers un ensemble de données BigQuery dans un projet pour lequel l'API Cloud Asset Inventory n'est pas activée, vous devez également attribuer les rôles suivants au compte de service service-${CONSUMER_PROJECT_NUMBER}@gcp-sa-cloudasset.iam.gserviceaccount.com dans le projet de destination.

   • Rôle Éditeur de données BigQuery (roles/bigquery.dataEditor)
   • Rôle Utilisateur BigQuery (roles/bigquery.user)

   Le compte de service sera créé en appelant l'API une fois, ou vous pouvez utiliser la commande suivante :

     gcloud beta services identity create --service=cloudasset.googleapis.com --project=PROJECT_ID
   

5. Créez un ensemble de données BigQuery.

Remarque: Actuellement, les tables BigQuery chiffrées à l'aide de clés Cloud KMS personnalisées ne sont pas acceptées.

Exporter un instantané d'élément

Remarque : L'ajout du résultat de l'exportation à une table existante n'est pas possible. La table de destination doit être vide ou vous devez l'écraser. Pour l'écraser, utilisez l'option --output-bigquery-force avec l'outil gcloud ou utilisez force avec l'API.

Pour exporter un instantané d'élément à un horodatage donné, procédez comme suit :

gcloud

Pour exporter des éléments dans un projet, exécutez la commande suivante. Cette commande stocke l'instantané exporté dans une table BigQuery située dans BIGQUERY_TABLE.

  gcloud asset export \
     --content-type CONTENT_TYPE \
     --project 'PROJECT_ID' \
     --snapshot-time 'SNAPSHOT_TIME' \
     --bigquery-table 'BIGQUERY_TABLE' \
     --output-bigquery-force

Où :

• CONTENT_TYPE est type de contenu de l'élément.
• PROJECT_ID est l'ID du projet dont les métadonnées sont exportées. Ce projet peut être celui à partir duquel vous exécutez l'exportation ou un autre projet.
• SNAPSHOT_TIME (facultatif) est l'heure à laquelle vous souhaitez prendre un instantané de vos éléments. La valeur doit être l'heure actuelle ou une heure passée. Par défaut, un instantané est pris à l'heure actuelle. Pour en savoir plus sur les formats de date et d'heure, consultez la section gcloud topic datetimes.
• BIGQUERY_TABLE est la table dans laquelle vous exportez les métadonnées, au format projects/PROJECT_ID/datasets/DATASET_ID/tables/TABLE_NAME.
• --output-bigquery-force écrase la table de destination si elle existe.

Pour exporter les éléments d'une organisation ou d'un dossier, vous pouvez utiliser l'une des options suivantes à la place de --project.

• --organization=ORGANIZATION_ID
• --folder=FOLDER_ID

access-policy ne peut être exporté que pour une --organization.

API

Pour exporter les métadonnées des éléments dans votre projet, exécutez la commande suivante. Cette commande stocke l'instantané exporté dans une table BigQuery nommée TABLE_NAME. En savoir plus sur la méthode exportAssets.

gcurl -d '{"contentType":"CONTENT_TYPE", \
  "outputConfig":{ \
    "bigqueryDestination": { \
      "dataset": "projects/PROJECT_ID/datasets/DATASET_ID",\
      "table": "TABLE_NAME", \
      "force": true \
    } \
  }}' \
  https://cloudasset.googleapis.com/v1/projects/PROJECT_NUMBER:exportAssets

Définir le type de contenu

Chaque table BigQuery est définie par un schéma qui décrit les noms de colonne, les types de données et d'autres informations. La définition du type de contenu lors de l'exportation détermine le schéma de la table.

• Ressource ou non spécifié : lorsque vous définissez le type de contenu sur RESOURCE ou que vous ne le définissez pas, vous créez une table BigQuery dont le schéma est illustré à la figure 1. Resource.data est les métadonnées de ressource représentées sous forme de chaîne JSON.

  Figure 1. Schéma de ressource

  

Remarque : Le schéma de ressource ne s'applique que lorsque vous n'utilisez pas l'option per-asset-type ou que vous la définissez sur false. Consultez la section Tables distinctes par type d'élément pour comprendre le schéma lorsque vous définissez l'option per-asset-type sur true.

• Stratégie IAM : lorsque vous définissez le type de contenu sur IAM_POLICY dans l'API REST ou sur iam-policy dans l'outil gcloud, vous créez une table BigQuery dont le schéma est illustré à la figure 2. L'enregistrement RECORD iam_policy est entièrement développé.

  Figure 2. Schéma IAM

  

• Règle d'administration : lorsque vous définissez le type de contenu sur ORG_POLICY dans l'API REST ou sur org-policy dans l'outil gcloud, vous créez une table BigQuery dont le schéma est illustré à la figure 3.

  Figure 3. Schéma des règles d'administration

  

• Stratégie VPCSC : lorsque vous définissez le type de contenu sur ACCESS_POLICY dans l'API REST ou sur access-policy dans l'outil gcloud, vous créez une table BigQuery dont le schéma est illustré à la figure 4.

  Figure 4. Schéma de stratégie VPCSC

  

• Inventaire des instances OSConfig : lorsque vous définissez le type de contenu sur OS_INVENTORY dans l'API REST ou os-inventory dans l'outil gcloud, vous créez une table BigQuery qui présente le schéma présenté à la figure 5.

  Figure 5. Schéma d'inventaire du système d'exploitation

  

Séparer les tables par type de ressource

Remarque : Cette fonctionnalité n'est actuellement pas compatible avec les types de ressources Google Kubernetes Engine, à l'exception de "container.googleapis.com/Cluster" et "container.googleapis.com/NodePool".

Pour exporter un instantané d'élément à un horodatage donné par type de ressource, procédez comme suit :

gcloud

Pour exporter des éléments dans un projet par type de ressource, exécutez la commande suivante. Cette commande stocke l'instantané exporté dans aucune table si les résultats sont vides ou dans plusieurs tables BigQuery. Chaque table contient les résultats d'un type d'élément. BIGQUERY_TABLE est concaténé avec _ (trait de soulignement) et le nom du type d'élément. Les caractères non alphanumériques sont remplacés par _.

  gcloud asset export \
     --content-type CONTENT_TYPE \
     --project 'PROJECT_ID' \
     --snapshot-time 'SNAPSHOT_TIME' \
     --bigquery-table 'BIGQUERY_TABLE' \
     --output-bigquery-force \
     --per-asset-type

Où :

• CONTENT_TYPE est type de contenu de l'élément.
• PROJECT_ID est l'ID du projet dont les métadonnées sont exportées. Ce projet peut être celui à partir duquel vous exécutez l'exportation ou un autre projet.
• SNAPSHOT_TIME (facultatif) est l'heure à laquelle vous souhaitez prendre un instantané de vos éléments. La valeur doit être l'heure actuelle ou une heure passée. Par défaut, un instantané est pris à l'heure actuelle. Pour en savoir plus sur les formats de date et d'heure valides, consultez la page gcloud topic datetimes.
• BIGQUERY_TABLE est la table dans laquelle vous exportez les métadonnées, au format projects/PROJECT_ID/datasets/DATASET_ID/tables/TABLE_NAME.
• --output-bigquery-force écrase la table de destination si elle existe.
• --per-asset-type exporte vers plusieurs tables BigQuery par type de ressource.

API

Pour exporter des éléments dans un projet par type de ressource, exécutez la commande suivante. Cette commande stocke l'instantané exporté dans zéro table si les résultats de l'instantané sont vides, ou dans plusieurs tables BigQuery. Chaque table contient les résultats d'un type d'élément et a concaténé BIGQUERY_TABLE avec _ (trait de soulignement) et le nom du type d'élément. Les caractères non alphanumériques sont remplacés par _. Consultez la exportAssets pour plus d'informations.

gcurl -d '{"contentType":"CONTENT_TYPE", \
  "outputConfig":{ \
    "bigqueryDestination": { \
      "dataset": "projects/PROJECT_ID/datasets/DATASET_ID",\
      "table": "TABLE_NAME", \
      "force": true \
      "separateTablesPerAssetType": true \
    } \
  }}' \
  https://cloudasset.googleapis.com/v1/projects/PROJECT_NUMBER:exportAssets

Si l'exportation vers une table échoue, l'ensemble de l'opération d'exportation échoue et renvoie la première erreur. Toutefois, les résultats des exportations ayant réussi seront conservés.

La définition du type de contenu lors de l'exportation détermine le schéma de chacune des tables.

• Ressource : lorsque vous définissez le type de contenu sur RESOURCE, le schéma de chaque table inclut des colonnes typée RECORD mises en correspondance avec les champs imbriqués du champ Resource.data de ce type d'élément (jusqu'au niveau imbriqué 15 compatible avec BigQuery). Veuillez consulter les schémas BigQuery par type d'exemples de tables dans projects/export-assets-examples/datasets/structured_export.

• Stratégie IAM, règle d'administration, stratégie VPCSC ou non spécifiée : lorsque vous définissez le type de contenu sur IAM_POLICY, ORG_POLICY, ACCESS_POLICY ou que vous ne définissez pas le type de contenu, chaque table dispose du même schéma étant donné que vous définissez la valeur du type par élément sur False. Pour plus d'informations, reportez-vous aux schémas de la section Définition du type de contenu.

Les types suivants sont regroupés dans une chaîne JSON pour résoudre le problème de compatibilité entre les types JSON3 et BigQuery.

• google.protobuf.Timestamp
• google.protobuf.Duration
• google.protobuf.FieldMask
• google.protobuf.ListValue
• google.protobuf.Value
• google.protobuf.Struct
• google.api.*

Exporter vers des tables partitionnées

Pour exporter un instantané d'élément à un horodatage donné dans une table partitionnée, procédez comme suit :

gcloud

Pour exporter des éléments dans un projet dans une ou plusieurs tables partitionnées, exécutez la commande suivante. Cette commande stocke l'instantané exporté dans une table BigQuery à l'adresse BIGQUERY_TABLE avec une précision quotidienne et deux colonnes d'horodatage supplémentaires, readTime et requestTime, dont l'une sera la clé de partition selon votre paramètre partition-key.

  gcloud asset export \
     --content-type CONTENT_TYPE \
     --project 'PROJECT_ID' \
     --snapshot-time 'SNAPSHOT_TIME' \
     --bigquery-table 'BIGQUERY_TABLE' \
     --partition-key 'PARTITION_KEY' \
     --output-bigquery-force \

Où :

• CONTENT_TYPE est type de contenu de l'élément.
• PROJECT_ID est l'ID du projet dont les métadonnées ont été exportées. Ce projet peut être celui à partir duquel vous exécutez l'exportation ou un autre projet.
• SNAPSHOT_TIME (facultatif) est l'heure à laquelle vous souhaitez prendre un instantané de vos éléments. La valeur doit être l'heure actuelle ou une heure passée. Par défaut, un instantané est pris à l'heure actuelle. Pour en savoir plus sur les formats de date et d'heure, consultez la section gcloud topic datetimes.
• BIGQUERY_TABLE est la table dans laquelle vous exportez les métadonnées, au format projects/PROJECT_ID/datasets/DATASET_ID/tables/TABLE_NAME.
• PARTITION_KEY est la colonne de clé de partitionnement lors de l'exportation vers des tables partitionnées BigQuery.
• --output-bigquery-force écrase la table de destination si elle existe.

API

Pour exporter des éléments dans un projet dans une ou plusieurs tables partitionnées, exécutez la commande suivante. Cette commande stocke l'instantané exporté dans une table BigQuery à l'adresse BIGQUERY_TABLE avec une précision quotidienne et deux colonnes d'horodatage supplémentaires, readTime et requestTime, dont l'une sera la clé de partition selon votre paramètre partition-key. En savoir plus sur la méthode exportAssets.

gcurl -d '{"contentType":"CONTENT_TYPE", \
  "outputConfig":{ \
    "bigqueryDestination": { \
      "dataset": "projects/PROJECT_ID/datasets/DATASET_ID",\
      "table": "TABLE_NAME", \
      "force": true \
      "partitionSpec": {"partitionKey": "PARTITION_KEY"} \
    } \
  }}' \
  https://cloudasset.googleapis.com/v1/projects/PROJECT_NUMBER:exportAssets

Dans le cas où une table de destination existe déjà, le schéma de la table existante est mis à jour si nécessaire en ajoutant des colonnes supplémentaires. Cette mise à jour de schéma échoue si des colonnes changent de type ou de mode, par exemple, de façon facultative à répéter. Ensuite, si l'option output-bigquery-force est définie sur TRUE, la partition correspondante est écrasée par les résultats de l'instantané. Toutefois, les données d'une ou plusieurs partitions différentes restent intactes. Si output-bigquery-force n'est pas défini ou si FALSE est défini, les données sont ajoutées à la partition correspondante.

L'opération d'exportation échoue si la mise à jour du schéma ou la tentative d'ajout de données échoue.

Vérifier le statut d'une exportation

Pour vérifier l'état d'une exportation, exécutez les commandes suivantes.

Remarque : Les opérations sont associées à une valeur OPERATION_ID, qui est un UUID. Cette valeur est potentiellement sensible, car la commande gcloud asset operations describe ne nécessite aucune autorisation supplémentaire pour fonctionner correctement. Veillez à ne partager la valeur OPERATION_ID qu'avec des utilisateurs de confiance.

Remarque : Le serveur rejette les requêtes si une requête antérieure vers la même destination a démarré dans les dernières 15 minutes et est toujours en cours d'exécution. Des résultats non définis peuvent survenir si le délai d'exportation dure plus de 15 minutes et qu'une requête consécutive vers la même destination est exécutée avant que la première requête n'aboutisse.

gcloud

Pour vérifier l'état de l'exportation, exécutez la commande suivante. Il est affiché dans l'outil gcloud après l'exécution de la commande d'exportation.

gcloud asset operations describe OPERATION_ID

API

Pour afficher l'état de l'exportation, exécutez la commande suivante en spécifiant l'ID d'opération renvoyé dans la réponse à l'exportation.

1. Vous pouvez trouver l'ID d'opération OPERATION_ID dans le champ name de la réponse à l'exportation, au format suivant :

   "name": "projects/PROJECT_NUMBER/operations/ExportAssets/CONTENT_TYPE/OPERATION_ID"
   

2. Pour vérifier l'état de l'exportation, exécutez la commande suivante avec l'ID d'opération OPERATION_ID :

   gcurl https://cloudasset.googleapis.com/v1/projects/PROJECT_NUMBER/operations/ExportAssets/CONTENT_TYPE/OPERATION_ID
   

Afficher un instantané d'élément

Pour afficher la table contenant les métadonnées de l'instantané d'élément, procédez comme suit :

Console

1. Accédez à la page "BigQuery" de Cloud Console.
   Accéder à la page BigQuery

2. Pour afficher les tables et les vues de l'ensemble de données, ouvrez le panneau de navigation. Dans la section Ressources, sélectionnez votre projet pour le développer, puis sélectionnez un ensemble de données.

3. Dans la liste, sélectionnez votre table.

4. Sélectionnez Détails et notez la valeur indiquée pour le champ Nombre de lignes. Vous aurez peut-être besoin de cette valeur pour contrôler le point de départ de vos résultats à l'aide de l'outil gcloud ou de l'API.

5. Pour afficher un exemple d'ensemble de données, sélectionnez Aperçu.

API

Pour parcourir les données d'une table, appelez tabledata.list. Dans le paramètre tableId, spécifiez le nom de la table.

Vous pouvez configurer les paramètres facultatifs suivants pour contrôler la sortie.

• maxResults est le nombre maximal de résultats à renvoyer.
• selectedFields est une liste de colonnes à renvoyer, séparées par une virgule. Si ce paramètre n'est pas spécifié, toutes les colonnes sont renvoyées.
• startIndex est l'index basé sur zéro de la première ligne à lire.

Remarque : Si l'index startIndex spécifié dans la requête se trouve au-delà de la dernière ligne, la méthode renvoie un résultat, mais sans la propriété rows. Vous pouvez savoir combien de lignes figurent dans la table en appelant la méthode tables.get et en examinant la propriété numRows.

Les valeurs renvoyées sont encapsulées dans un objet JSON que vous devez analyser, comme décrit dans la documentation de référence de tabledata.list.

L'exportation répertorie les éléments et le nom de leurs ressources.

Interroger un instantané d'élément

Après avoir exporté votre instantané vers BigQuery, vous pouvez exécuter des requêtes sur vos métadonnées d'éléments. Pour en savoir plus sur plusieurs cas d'utilisation types, consultez la page Exporter vers des exemples de requêtes BigQuery.

Par défaut (ou à la demande), BigQuery exécute des tâches de requête interactives, ce qui signifie que la requête est exécutée dès que possible. Les requêtes interactives sont comptabilisées dans votre limite de débit simultané et votre limite quotidienne.

Les résultats de requête sont enregistrés dans une table temporaire ou permanente. Vous pouvez choisir d'ajouter ou d'écraser les données dans une table existante, ou de créer une nouvelle table si aucune table portant le même nom n'existe.

Pour exécuter une requête interactive qui écrit les résultats dans une table temporaire, procédez comme suit :

Console

1. Accédez à la page "BigQuery" de Cloud Console.
   Accéder à la page BigQuery

2. Sélectionnez Saisir une nouvelle requête.

3. Dans la zone de texte de l'éditeur de requête, saisissez une requête SQL BigQuery valide.

4. (Facultatif) Pour modifier l'emplacement du traitement des données, procédez comme suit :

   1. Sélectionnez Plus, puis Paramètres de requête.
   2. Dans le champ Zone de traitement, sélectionnez Sélection automatique, puis l'emplacement de vos données.
   3. Pour mettre à jour les paramètres de la requête, sélectionnez Enregistrer.

5. Sélectionnez Exécuter.

API

1. Pour démarrer une nouvelle tâche, appelez la méthode jobs.insert. Dans la ressource de tâche, définissez les paramètres suivants.

   • Dans le champ configuration, définissez le champ query sur un objet JobConfigurationQuery qui décrit la tâche de requête BigQuery.

   • Dans le champ jobReference, définissez le champ location de manière appropriée pour votre tâche.

2. Pour interroger les résultats, appelez getQueryResults jusqu'à ce que jobComplete ait la valeur true. Vous pouvez vérifier la présence d'erreurs et d'avertissements dans la liste errors.