L'API Cloud Asset vous permet d'utiliser un langage de requête personnalisé pour interroger les métadonnées de ressource d'un projet, d'un dossier ou d'une organisation.
Avant de commencer
- Activez l'API Cloud Asset pour votre projet.
- Attribuez l'autorisation
cloudasset.assets.searchAllResources
au compte utilisateur ou au compte de service qui effectue la requête. Cette autorisation est incluse dans les rôles de base et les rôles prédéfinis répertoriés dansRoles
.
Appel de SearchAllResources
gcloud
Vous pouvez appeler SearchAllResources
à l'aide de la commande gcloud asset search-all-resources
. Vous devez exécuter le SDK Cloud version 302.0.0 ou ultérieure. Vous pouvez vérifier votre version à l'aide de la commande gcloud version
.
gcloud asset search-all-resources \ --scope=SCOPE \ --query=QUERY \ --asset-types=ASSET_TYPES,… \ --order-by=ORDER_BY \ --page-size=PAGE_SIZE \
Toutes les options suivantes sont facultatives :
(Facultatif) SCOPE : un champ d'application peut être un projet, un dossier ou une organisation. La recherche est limitée aux ressources Google Cloud comprises dans ce champ d'application. L'appelant doit disposer de l'autorisation
cloudasset.assets.searchAllResources
sur le champ d'application souhaité. Si elle n'est pas spécifiée, la propriété de projet configurée est utilisée. Pour trouver le projet configuré, exécutez la commande suivante :gcloud config get-value project
. Pour modifier le paramètre, exécutez la commande suivante :gcloud config set project PROJECT_ID
.Les valeurs autorisées sont les suivantes :
projects/PROJECT_ID
(par exemple, "projects/foo-bar
")projects/PROJECT_NUMBER
(par exemple, "projects/12345678
")folders/FOLDER_NUMBER
(par exemple, "folders/1234567
")organizations/ORGANIZATION_NUMBER
(par exemple, "organizations/123456
")
(Facultatif) QUERY : l'instruction de requête. Pour en savoir plus, consultez la section Comment construire une requête. Si elle n'est pas spécifiée ou vide, elle recherche toutes les ressources dans l'élément
scope
spécifié.Par exemple :
name:Important
pour trouver les ressources Google Cloud dont le nom contient le mot "Important".name=Important
pour trouver la ressource Google Cloud dont le nom est exactement "Important".displayName:Impor*
pour rechercher des ressources Google Cloud dont le nom à afficher contient "Imper" en tant que préfixe de n'importe quel mot.location:us-west*
pour rechercher les ressources Google Cloud dont l'emplacement comporte deux mots avec les préfixes "us" et "west".labels:prod
pour trouver des ressources Google Cloud qui possèdent une étiquette dont la clé ou la valeur contient le mot "prod".labels.env:prod
pour trouver les ressources Google Cloud qui possèdent une étiquette dont la clé est "env" et la valeur contient le mot "prod".labels.env:*
pour trouver les ressources Google Cloud qui possèdent une étiquette dont la clé est "env".kmsKey:key
pour rechercher des ressources Google Cloud chiffrées avec une clé de chiffrement gérée par le client dont le nom contient "word".state:ACTIVE
pour rechercher des ressources Google Cloud dont l'état contient "ACTIVE".createTime<1609459200
pour rechercher les ressources Google Cloud créées avant "2021-01-01 00:00:00 UTC". 1609459200 est l'horodatage de l'epoch en secondes de "2021-01-01 00:00:00 UTC".updateTime>1609459200
pour rechercher les ressources Google Cloud mises à jour après "2021-01-01 00:00:00 UTC". 1609459200 est l'horodatage de l'epoch en secondes de "2021-01-01 00:00:00 UTC".Important
pour trouver les ressources Google Cloud contenant le mot "Important" dans n'importe quel champ inclus dans l'index de recherche.Impor*
pour rechercher des ressources Google Cloud contenant "Impur" en tant que préfixe de n'importe quel mot dans les champs inclus dans l'index de recherche.Important location:(us-west1 OR global)
pour rechercher des ressources Google Cloud contenant le mot "Important" dans n'importe quel champ inclus dans l'index de recherche, ainsi que dans la région "us-west1" ou dans l'emplacement "global".
(Facultatif) ASSET_TYPES : une liste des types d'éléments à rechercher. Si elle n'est pas spécifiée ou vide, la recherche porte sur tous les types d'éléments pouvant faire l'objet d'une recherche. Exemple :
"cloudresourcemanager.googleapis.com/Project,compute.googleapis.com/Instance"
pour rechercher des ressources de projets et d'instances de VM. Les expressions régulières sont également acceptées. Par exemple:"compute.googleapis.com.*"
les ressources dont le type d'élément commence par"compute.googleapis.com"
. Pour connaître la syntaxe des expressions régulières compatibles, consultez la section RE2. Si l'expression régulière ne correspond à aucun type d'élément compatible, une erreurINVALID_ARGUMENT
est renvoyée.(Facultatif) ORDER_BY : une liste de champs séparés par une virgule indiquant l'ordre de tri des résultats. L'ordre par défaut est croissant. Ajoutez
" DESC"
après le nom du champ pour indiquer l'ordre décroissant. Les espaces vides sont ignorés. Exemple :"location DESC, name"
. Seuls les champs de chaîne dans la réponse peuvent être triés, y comprisname
,displayName
,description
etlocation
.(Facultatif) PAGE_SIZE : taille de la page pour la pagination des résultats de recherche. Le maximum est de 500. Si la valeur est définie sur
0
, une valeur par défaut appropriée sera sélectionnée.
Voici des exemples de commandes gcloud
:
Trouve toutes les ressources dans "
organizations/123456
", dontname
contient le motmycompany
:gcloud asset search-all-resources \ --scope='organizations/123456' --query='name:mycompany'
api
Vous pouvez appeler SearchAllResources
à l'aide d'un jeton OAuth valide pour un projet.
Pour appeler la méthode SearchAllResources
à partir de Cloud Shell ou de toute console où la commande gcloud
est disponible, procédez comme suit :
Si vous n'avez pas configuré l'écran d'autorisation OAuth de votre projet, cette étape est obligatoire. Vous devez fournir une adresse e-mail et un nom de produit pour l'écran d'autorisation OAuth.
- Accédez à l'écran d'autorisation OAuth de votre projet.
Configurer l'écran d'autorisation - Saisissez le nom de l'application que vous souhaitez afficher.
- Sous Adresse e-mail d'assistance, sélectionnez l'adresse e-mail que vous souhaitez afficher en tant que contact public. Elle doit correspondre à votre adresse e-mail ou à un groupe Google dont vous êtes le propriétaire.
- Ajoutez des détails, si nécessaire.
- Cliquez sur Enregistrer.
- Accédez à l'écran d'autorisation OAuth de votre projet.
Créez un jeton OAuth pour votre projet. Pour en savoir plus, consultez la page Configurer OAuth 2.0.
- Accédez à la page "Créer un ID client OAuth".
Créer le client OAuth - Sélectionnez le Type d'application en choisissant Application de bureau.
- Cliquez sur Créer.
- Accédez à la page "Créer un ID client OAuth".
Téléchargez le fichier
client_secret.json
.- Accédez à la page Identifiants.
- À droite de votre nouvel ID client, cliquez sur Télécharger au format JSON.
- Stockez le fichier de manière sécurisée dans un emplacement auquel seule votre application peut accéder.
Connectez-vous à l'aide du fichier JSON avec la commande suivante.
gcloud auth application-default login --client-id-file=YOUR_JSON_FILE
Notez que cette commande vous invite à ouvrir un lien. Assurez-vous que la page affiche le Nom de l'application que vous avez défini dans l'écran d'autorisation OAuth.
Générez un jeton d'authentification pour votre compte à l'aide de la commande suivante :
TOKEN=$(gcloud auth application-default print-access-token)
Vous pouvez maintenant interroger des ressources à l'aide des commandes
curl
.PAGE_SIZE=PAGE_SIZE PAGE_TOKEN="PAGE_TOKEN" SCOPE="SCOPE" QUERY="QUERY" ASSET_TYPES="ASSET_TYPES,…" ORDER_BY="ORDER_BY" curl -s -G \ -H "Authorization: Bearer $TOKEN" \ -d "page_size=$PAGE_SIZE" \ -d "page_token=$PAGE_TOKEN" \ -d "scope=$SCOPE" \ -d "asset_types=$ASSET_TYPES" \ -d "order_by=$ORDER_BY" \ --data-urlencode "query=$QUERY" \ "https://cloudasset.googleapis.com/v1/$SCOPE:searchAllResources"
Toutes les options suivantes sont facultatives :
SCOPE : est requis. Un champ d'application peut correspondre à un projet, un dossier ou une organisation. La recherche est limitée aux ressources Google Cloud comprises dans ce champ d'application. L'appelant doit disposer de l'autorisation
cloudasset.assets.searchAllResources
sur le champ d'application souhaité.Les valeurs autorisées sont les suivantes :
projects/PROJECT_ID
(par exemple, "projects/foo-bar
")projects/PROJECT_NUMBER
(par exemple, "projects/12345678
")folders/FOLDER_NUMBER
(par exemple, "folders/1234567
")organizations/ORGANIZATION_NUMBER
(par exemple, "organizations/123456
")
(Facultatif) QUERY : l'instruction de requête. Pour en savoir plus, consultez la section Comment construire une requête. Si elle n'est pas spécifiée ou vide, elle recherche toutes les ressources dans l'élément
scope
spécifié.Par exemple :
name:Important
pour trouver les ressources Google Cloud dont le nom contient le mot "Important".name=Important
pour trouver la ressource Google Cloud dont le nom est exactement "Important".displayName:Impor*
pour rechercher des ressources Google Cloud dont le nom à afficher contient "Imper" en tant que préfixe de n'importe quel mot.location:us-west*
pour rechercher les ressources Google Cloud dont l'emplacement contient à la fois les préfixes "us" et "west".labels:prod
pour trouver des ressources Google Cloud qui possèdent une étiquette dont la clé ou la valeur contient le mot "prod".labels.env:prod
pour trouver les ressources Google Cloud qui possèdent une étiquette dont la clé est "env" et la valeur contient le mot "prod".labels.env:*
pour trouver les ressources Google Cloud qui possèdent une étiquette dont la clé est "env".kmsKey:key
pour rechercher des ressources Google Cloud chiffrées avec une clé de chiffrement gérée par le client dont le nom contient "word".state:ACTIVE
pour rechercher des ressources Google Cloud dont l'état contient "ACTIVE".createTime<1609459200
pour rechercher les ressources Google Cloud créées avant "2021-01-01 00:00:00 UTC". 1609459200 est l'horodatage de l'epoch en secondes de "2021-01-01 00:00:00 UTC".updateTime>1609459200
pour rechercher les ressources Google Cloud mises à jour après "2021-01-01 00:00:00 UTC". 1609459200 est l'horodatage de l'epoch en secondes de "2021-01-01 00:00:00 UTC".Important
pour trouver les ressources Google Cloud contenant le mot "Important" dans n'importe quel champ inclus dans l'index de recherche.Impor*
pour rechercher des ressources Google Cloud contenant "Impur" en tant que préfixe de n'importe quel mot dans les champs inclus dans l'index de recherche.Important location:(us-west1 OR global)
pour rechercher des ressources Google Cloud contenant le mot "Important" dans n'importe quel champ inclus dans l'index de recherche, ainsi que dans la région "us-west1" ou dans l'emplacement "global".
(Facultatif) ASSET_TYPES : une liste des types d'éléments à rechercher. Si elle n'est pas spécifiée ou vide, la recherche porte sur tous les types d'éléments pouvant faire l'objet d'une recherche. Exemple :
"cloudresourcemanager.googleapis.com/Project,compute.googleapis.com/Instance"
pour rechercher des ressources de projets et d'instances de VM.(Facultatif) ORDER_BY : une liste de champs séparés par une virgule indiquant l'ordre de tri des résultats. L'ordre par défaut est croissant. Ajoutez
" DESC"
après le nom du champ pour indiquer l'ordre décroissant. Les espaces vides sont ignorés. Exemple :"location DESC, name"
. Seuls les champs de chaîne dans la réponse peuvent être triés, y comprisname
,displayName
,description
etlocation
.(Facultatif) PAGE_SIZE : taille de la page pour la pagination des résultats de recherche. Le maximum est de 500. Si la valeur est définie sur
0
, une valeur par défaut appropriée sera sélectionnée.(Facultatif) PAGE_TOKEN : jeton représentant le prochain lot de résultats de l'appel précédent à cette méthode.
page_token
doit être identique à la valeur denext_page_token
de la réponse de l'appel précédent.
Documentation de référence sur la bibliothèque cliente et l'API
- SearchAllResources
Comment construire une requête
Pour en savoir plus sur le langage de requête, consultez la section Syntaxe des requêtes.
Consultez la section Rechercher des exemples de ressources pour en savoir plus sur les exemples de requêtes pour divers cas d'utilisation réels.
Interroger les ressources Google Cloud par champs de métadonnées de ressource
Pour rechercher des métadonnées de ressource, une expression de requête est au format suivant :
- Mot clé exact :
FIELD=QUERY
- Correspondance partielle au format texte :
FIELD:QUERY
- Correspondance numérique: opérateurs de comparaison (
=
,>
,>=
,<
,<=
)FIELDcomparison operatorQUERY
Une métadonnée de ressource pouvant faire l'objet d'une recherche FIELD peut être :
- name : le nom de ressource complet de la ressource. Remarque : tous les types d'éléments ne peuvent pas faire l'objet d'une recherche. Consultez la liste des types pouvant faire l'objet d'une recherche.
- displayName : le nom à afficher dans l'interface utilisateur
- description : la description textuelle de la ressource dans un ou plusieurs paragraphes
- location : l'emplacement de la ressource. L'emplacement peut être "global", régional (par exemple, "us-east1") ou zonal (par exemple, "us-west1-b").
labels : libellés associés à cette ressource. Les libellés peuvent correspondre aux clés de libellé, aux valeurs de libellé ou aux deux. Consultez la section Ajouter des libellés et regrouper des ressources GCP.
labels.[key] : valeur de libellé identifiée par la clé de libellé associée à cette ressource. Par exemple : "
labels.env:prod
". Seuls les traits d'union (-
), les traits de soulignement (_
), les minuscules et les chiffres sont autorisés dans les clés des libellés. Les clés doivent commencer par une lettre minuscule. Les caractères internationaux sont acceptés. Consultez la section Exigences concernant les libellés.networkTags : tags réseau associés à cette ressource. Consultez la section Ajouter des libellés et regrouper des ressources GCP.
kmsKey: clé de chiffrement gérée par le client et utilisée pour chiffrer cette ressource. Consultez les pages CryptoKey et CryptoKeyVersion.
state: valeur textuelle de l'état de cette ressource. Chaque type de ressource possède des définitions d'état différentes mappées à partir de différents champs de types de ressources. Exemple : Si la ressource est une instance fournie par Compute Engine, son état inclut PROVISIONING, STAGING, RUNNING, STOPPING, SUSPENDING, SUSPENDED, REPAIRING et TERMINATED. Consultez la définition de
status
dans la documentation de référence de l'API. Si la ressource est un projet fourni par Cloud Resource Manager, son état inclut LIFECLE_STATE_UNSPECIFIED, ACTIVE, DELETE_REQUESTED et DELETE_IN_PROGRESS. Consultez la définition delifecycleState
dans la documentation de référence de l'API.createTime: horodatage de création de cette ressource, à laquelle la ressource a été créée. La précision est exprimée en secondes.
updateTime: horodatage de la dernière mise à jour de cette ressource, où la ressource a été modifiée ou supprimée pour la dernière fois. La précision est exprimée en secondes.
Exemples : requête par champ spécifique
Recherchez toutes les ressources dans votre
scope
dont lename
contient le motImportant
:name:Important
Trouvez toutes les ressources nécessaires dans votre
scope
dontdisplayName
contient un mot avec préfixeprod
:displayName:prod*
Recherchez toutes les ressources dans votre
scope
dont lelocation
contient le motus
:location:us
Recherchez toutes les ressources dans votre
scope
dont le champlocation
contient exactementus
:location=us
Recherchez toutes les ressources de votre
scope
qui ont unlabel
où la clé ou la valeur contient le motprod
:labels:prod
Recherchez toutes les ressources de votre
scope
qui ont unlabel
où la clé estenv
et la valeur contient le motprod
:labels.env:prod
Recherchez toutes les ressources dans votre fichier
scope
ayant unlabel
dont la clé estenv
et la valeur exactement égale àprod
:labels.env=prod
Recherchez toutes les ressources dans votre
scope
qui ont unlabel
où la clé estenv
:labels.env:*
Rechercher toutes les ressources dans votre
scope
dont l'un desnetworkTags
contient le motinternal
:networkTags:internal
Recherchez dans votre fichier
scope
toutes les ressources dont l'une des ressourcesnetworkTags
correspond exactement àinternal
:networkTags=internal
Recherchez toutes les ressources de votre fichier
scope
chiffrées avec une clé de chiffrement gérée par le client dont le nom contient le motkey
:kmsKey:key
Recherchez toutes les ressources de votre fichier
scope
dont le motstate
contient le motACTIVE
:state:ACTIVE
Recherchez toutes les ressources de votre ressource
scope
qui ont été créées avant "2021-01-01 00:00:00 UTC" (1609459200 correspond à l'horodatage de l'époque en secondes de "2021-01-01 00:00"). :00 UTC"):createTime<1609459200
Recherchez toutes les ressources de votre fichier
scope
qui ont été mises à jour après "2021-01-01 00:00:00 UTC" (1986459200 correspond à l'horodatage de l'époque en secondes de "2021-01-01 00:00"). :00 UTC"):updateTime>1609459200
Recherchez toutes les ressources de votre fichier
scope
dont le motname
contient le motImportant
etdescription
contient un mot ayant le préfixeimport
:name:Important description:import*
Recherchez toutes les ressources de votre fichier
scope
dont le motname
contient le motImportant
oudescription
contient un mot ayant le préfixeimport
:name:Important OR description:import*
Interroger les ressources Google Cloud par texte libre
Vous pouvez aussi tout simplement utiliser une requête de texte libre sans spécifier de champ. Elle renvoie ensuite des ressources, tant qu'un des champs dans les métadonnées de la ressource correspond à la requête.
Exemples : requête par texte libre
Trouve toutes les ressources dans votre
scope
dont les champs de métadonnées (par exemple,name
,displayName
,description
) contiennent le motImportant
:Important
Trouve toutes les ressources dans votre
scope
dont les champs de métadonnées (par exemple,name
,displayName
,description
) contiennent un mot avec le préfixeimport
:import*
Trouve toutes les ressources dans votre
scope
dont les champs de métadonnées (par exemple,name
,displayName
,description
) contiennent le motImportant
et contiennent également un mot avec le préfixeprod
:Important prod*