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.
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 InventoryConfigurez les autorisations requises pour appeler l'API Cloud Asset Inventory à l'aide de la CLI gcloud ou de l'API.
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 :- Installez oauth2l sur votre ordinateur local, de façon à pouvoir interagir avec le système Google OAuth.
- Vérifiez que vous avez accès à la commande Unix
curl
. 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
)
- Rôle Lecteur d'éléments cloud (
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
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:service-PROJECT_NUMBER@gcp-sa-cloudasset.iam.gserviceaccount.com --role=roles/cloudasset.serviceAgent
- Rôle Éditeur 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 commandeforce
avec l'API.Les types de ressources Google Kubernetes Engine (GKE), à l'exception de
container.googleapis.com/Cluster
etcontainer.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'optionper-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.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'indicateurper-asset-type
surtrue
, 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 champResource.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 suriam-policy
dans la CLI gcloud, vous créez une table BigQuery ayant le schéma présenté dans la figure 2. La valeuriam_policy
deRECORD
est entièrement développée.Règle d'administration : lorsque vous définissez le type de contenu sur
ORG_POLICY
dans l'API REST ou surorg-policy
dans la CLI gcloud, vous créez une table BigQuery ayant le schéma présenté dans la figure 3.Règle VPC SC : lorsque vous définissez le type de contenu sur
ACCESS_POLICY
dans l'API REST ou suraccess-policy
dans la CLI gcloud, vous créez une table BigQuery ayant le schéma illustré à la figure 4.Inventaire des instances OSConfig : lorsque vous définissez le type de contenu sur
OS_INVENTORY
dans l'API REST ou suros-inventory
dans la CLI gcloud, vous créez une table BigQuery dont le schéma est illustré à la figure 5.
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.
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.
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"
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
Accédez à la page BigQuery dans Cloud Console.
Accéder à la page BigQueryPour 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.
Dans la liste, sélectionnez votre table.
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.
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.
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
Accédez à la page BigQuery dans Cloud Console.
Accéder à la page BigQuerySélectionnez
Saisir une nouvelle requête.Dans la zone de texte de l'éditeur de requête, saisissez une requête SQL BigQuery valide.
(Facultatif) Pour modifier l'emplacement du traitement des données, procédez comme suit :
- Sélectionnez Plus, puis Paramètres de requête.
- Dans le champ Zone de traitement, sélectionnez Sélection automatique, puis l'emplacement de vos données.
- Pour mettre à jour les paramètres de la requête, sélectionnez Enregistrer.
Sélectionnez Exécuter.
API
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 champquery
sur un objet JobConfigurationQuery qui décrit la tâche de requête BigQuery.Dans le champ
jobReference
, définissez le champlocation
de manière appropriée pour votre tâche.
Pour interroger les résultats, appelez
getQueryResults
jusqu'à ce quejobComplete
ait la valeurtrue
. Vous pouvez vérifier la présence d'erreurs et d'avertissements dans la listeerrors
.