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 la CLI gcloud ou de l'API.

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

   gcloud

   Pour configurer votre environnement afin d'utiliser la CLI gcloud pour appeler l'API Cloud Asset Inventory, installez la CLI Google 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)

   Notez que la CLI gcloud utilise le projet de facturation comme projet client. Si vous recevez un message d'autorisation refusée, vous pouvez vérifier si le projet de facturation est différent du projet principal :

   gcloud config list
   

   Pour définir le projet de facturation sur le projet client, procédez comme suit :

   gcloud config set billing/quota_project CONSUMER_PROJECT_NUMBER
   

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. Vous pouvez également utiliser les commandes suivantes pour créer le compte de service et attribuer le rôle d'agent de service manuellement :

     gcloud beta services identity create --service=cloudasset.googleapis.com --project=PROJECT_ID
     gcloud projects add-iam-policy-binding PROJECT_ID --member=serviceAccount:[e-mail] --role=roles/cloudasset.serviceAgent
   

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

Limites

• Les tables BigQuery chiffrées avec des clés Cloud KMS (Cloud Key Management Service) personnalisées ne sont pas compatibles.

• Il n'est pas possible d'ajouter la sortie d'exportation à une table existante, sauf si vous exportez vers une table partitionnée. La table de destination doit être vide ou vous devez l'écraser. Pour le remplacer, utilisez l'option --output-bigquery-force avec la CLI gcloud ou la commande force avec l'API.

• Les types de ressources Google Kubernetes Engine (GKE), à l'exception de container.googleapis.com/Cluster et container.googleapis.com/NodePool, ne sont pas compatibles lors de l'exportation vers des tables distinctes par type de ressource.

Définir le schéma BigQuery pour l'exportation

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 spécifiez pas, et que vous définissez l'option per-asset-type sur "false" ou que vous ne l'utilisez pas, vous créez une table BigQuery dont le schéma est illustré à la figure 1. Resource.data correspond aux métadonnées de ressource représentées sous forme de chaîne JSON.

  Figure 1. Schéma de ressource

  

  Lorsque vous définissez le type de contenu sur RESOURCE ou que vous ne définissez pas le type de contenu, et que vous définissez l'indicateur per-asset-type sur true, vous créez des tables distinctes par type d'élément. Le schéma de chaque table inclut des colonnes de type RECORD mappées aux champs imbriqués dans le champ Resource.data de ce type d'élément (jusqu'à 15 niveaux imbriqués compatibles avec BigQuery). Pour obtenir des exemples de tables BigQuery par type, consultez projects/export-assets-examples/dataset/structured_export.

• Stratégie IAM : lorsque vous définissez le type de contenu sur IAM_POLICY dans l'API REST ou sur iam-policy dans la CLI gcloud, vous créez une table BigQuery ayant le schéma présenté dans la figure 2. La valeur iam_policy de RECORD est entièrement développée.

  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 la CLI gcloud, vous créez une table BigQuery ayant le schéma présenté dans la figure 3.

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

  

• Règle VPC SC : lorsque vous définissez le type de contenu sur ACCESS_POLICY dans l'API REST ou sur access-policy dans la CLI gcloud, vous créez une table BigQuery ayant le schéma 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 sur os-inventory dans la CLI gcloud, vous créez une table BigQuery dont le schéma est illustré à la figure 5.

  Figure 5. Schéma de l'inventaire d'OS

  

Exporter un instantané d'élément

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

Exporter des tables distinctes pour chaque type de ressource

Pour exporter des éléments d'un projet vers des tables BigQuery distinctes pour chaque type de ressource, utilisez l'option --per-asset-type. Le nom de chaque table est BIGQUERY_TABLE concaténé avec les traits d'union _ (trait de soulignement) et ASSET_TYPE_NAME. Les caractères non alphanumériques sont remplacés par _.

Notez que les types de ressources GKE, à l'exception de container.googleapis.com/Cluster et container.googleapis.com/NodePool, ne sont pas compatibles avec ce type d'exportation.

Pour exporter des éléments séparés vers des tables BigQuery pour chaque type de ressource, exécutez la commande suivante.

gcloud

  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. Cette valeur détermine également le schéma pour l'exportation.
• 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

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

En savoir plus sur la méthode exportAssets

Si l'exportation vers une table échoue, l'opération d'exportation échoue et la première erreur est renvoyée. Les résultats des exportations précédentes sont conservés.

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

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

Exporter vers une table partitionnée

Pour exporter des éléments d'un projet vers des tables partitionnées, utilisez l'indicateur --partition-key. L'instantané exporté est stocké dans une table BigQuery à l'adresse BIGQUERY_TABLE, avec une précision quotidienne et deux colonnes d'horodatage supplémentaires, readTime et requestTime. L'une d'elles est le paramètre partition-key.

Pour exporter des éléments d'un projet vers des tables partitionnées, exécutez la commande suivante.

gcloud

  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. Cette valeur détermine également le schéma pour l'exportation.
• 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 partition lors de l'exportation vers des tables partitionnées par BigQuery.
• --output-bigquery-force écrase la table de destination si elle existe.

API

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

En savoir plus sur la méthode 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 du schéma échoue si des colonnes changent de type ou de mode (par exemple, facultatif ou répété). 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 est défini sur FALSE, il ajoute les données à la partition correspondante.

L'opération d'exportation échoue en cas d'échec de la mise à jour ou de la tentative d'ajout de données au schéma.

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 s'affiche dans la CLI 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 dans 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 la CLI 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.

Remarque:Certains champs de test peuvent sembler vides dans un premier temps dans BigQuery. Ne définissez aucune dépendance sur les colonnes concernées tant que les champs ne sont pas renseignés. Pour déterminer quels champs sont publics, reportez-vous au document de découverte de la ressource.

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 dans 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.