Syntaxe des requêtes de recherche

Lorsque vous recherchez des composants, vous pouvez filtrer les résultats de la recherche en spécifiant une requête composée d'un champ de métadonnées de composant, d'un opérateur et d'une valeur.

Champs et ressources pouvant faire l'objet d'une recherche

Pour connaître les champs que vous pouvez utiliser dans une requête searchAllResources, consultez Champs ResourceSearchResult.

Pour connaître les champs que vous pouvez utiliser dans une requête searchAllIamPolicies, consultez Champs IamPolicySearchResult.

Pour connaître les ressources que vous pouvez rechercher, consultez Types de ressources.

Mise en correspondance de texte

Lorsque vous recherchez une correspondance textuelle, vous pouvez faire correspondre un champ de métadonnées d'élément exactement ou partiellement.

Correspondance exacte du texte

Pour une correspondance exacte de texte, utilisez l'opérateur = (égal à) avec la syntaxe suivante :

ASSET_METADATA_FIELD=QUERY

Exemple :

location=us-central1-a

Tenez compte des règles suivantes lorsque vous effectuez une correspondance exacte du texte :

• Pour que la requête soit vraie, la valeur de la requête doit correspondre exactement à la valeur du champ de métadonnées de l'asset.

• Pour un champ avec une valeur de liste, si la valeur de la requête correspond à l'un des éléments de la liste, il s'agit d'une correspondance.

• Les valeurs de requête sont sensibles à la casse.

• Une valeur de requête de correspondance exacte est traitée comme une expression, mais ne peut pas contenir de caractères génériques.

Correspondance partielle du texte

Pour une correspondance partielle de texte, utilisez l'opérateur : (contient) avec la syntaxe suivante :

ASSET_METADATA_FIELD:QUERY

Exemple :

location:us-central1

Lorsque vous effectuez une recherche avec l'opérateur :, la valeur de la requête et les valeurs des champs de métadonnées d'élément sont converties en jetons à des fins de comparaison. Chaque mot de la valeur de la requête est vérifié pour déterminer s'il existe dans l'ordre consécutif dans la valeur du champ de métadonnées de l'élément. Lorsque vous utilisez des correspondances partielles, les valeurs de requête ne sont pas sensibles à la casse.

Les valeurs de requête de correspondance partielle peuvent être des expressions ou une combinaison d'expressions, et peuvent contenir des caractères génériques. Vous pouvez effectuer jusqu'à 10 comparaisons dans une requête, avec un maximum de 2 048 caractères. Si vous disposez d'un cas d'utilisation pour des requêtes plus longues, contactez [e-mail].

Règles de tokenisation

Voici les règles de tokenisation pour la mise en correspondance partielle du texte :

• Les caractères spéciaux de début et de fin sont supprimés.

• Les caractères non alphanumériques ([a-zA-Z0-9]), les traits de soulignement (_) et les esperluettes (&) sont traités comme des délimiteurs.

Voici quelques exemples de tokenisation :

• us-central1 est tokenisé en [us,central1].

• [e-mail] est tokenisé en [alex,2020,example,com].

• google.com/cloud est tokenisé en [google,com,cloud].

• Compute %Instance% est tokenisé en [compute,instance].

• $%^*-! est tokenisé en [].

• compute*storage est tokenisé en [compute,storage].

• compute&storage est tokenisé en [compute&storage].

• [e-mail] est tokenisé en [alex_test,example,com].

• instance/_my_vm_ est tokenisé en [instance,_my_vm_].

Exemples de correspondance exacte et partielle du texte

Un composant dont le champ location a la valeur us-central1-a correspond aux requêtes suivantes.

Requête	Motif de la mise en correspondance
location=us-central1-a	Correspond car l'expression us-central1-a est exactement identique à la valeur du champ.
location:US-Central1-A	Correspondance, car les caractères de ponctuation sont traités comme des délimiteurs et la valeur de requête n'est pas sensible à la casse.
location:"us central1 a"	Correspond car les mots de l'expression "us central1 a" correspondent à la valeur du champ dans l'ordre.
location:(central1 us a)	Correspond car les mots de la combinaison (central1 us a) correspondent aux mots de la valeur du champ dans n'importe quel ordre.
location:(a "us central1")	Correspond car les expressions de la combinaison, a et "us central1", correspondent aux mots de la valeur du champ dans n'importe quel ordre. Comme "us central1" est une expression, ces mots doivent correspondre dans l'ordre.
location:us-central*	Correspond car le caractère générique * est utilisé pour établir une correspondance de préfixe.

Un composant dont le champ location a la valeur us-central1-a ne correspond pas aux requêtes suivantes.

Requête	Motif de l'échec de la mise en correspondance
location=US-central1-a	Ne correspond pas, car l'expression est sensible à la casse. Utilisez plutôt l'opérateur : pour les correspondances non sensibles à la casse.
location=us-central1	Ne correspond pas, car l'expression correspond partiellement à la valeur du champ. Utilisez plutôt l'opérateur : pour les correspondances partielles.

Créer une requête de correspondance exacte

Une valeur de requête peut être composée d'expressions, de combinaisons, de négations et de caractères génériques.

Expressions

Une expression est constituée d'un ou de plusieurs mots qui doivent correspondre dans l'ordre. Pour mettre en correspondance des mots sans respecter l'ordre, utilisez plutôt des combinaisons.

La requête suivante correspond aux composants dont le champ policy contient les mots alex et 2020 dans l'ordre et consécutifs :

policy:"alex 2020"

Un élément dont la valeur du champ policy est "[e-mail]" correspond à la requête, car les mots alex et 2020 sont dans l'ordre. Le caractère . est ignoré, car la ponctuation est traitée comme un délimiteur.

Un élément dont la valeur du champ policy est "[e-mail]" ou "[e-mail]" ne correspond pas, car les mots alex et 2020 ne sont pas dans l'ordre consécutif.

Construire une phrase

Lorsque vous créez une expression, tenez compte des règles suivantes :

• Si l'expression ne contient que des caractères de l'alphabet latin de base ISO [a-zA-Z], des chiffres [0-9], des connecteurs d'adresses e-mail ou d'URL de base [_-+.@/&], ou des caractères génériques [*], il n'est pas nécessaire de la placer entre guillemets :

  policy:[e-mail]
  

  Toutefois, l'utilisation de guillemets doubles fonctionne toujours et se comporte de la même manière :

  policy:"[e-mail]"
  

• Si l'expression contient des espaces ou d'autres caractères spéciaux, elle doit être placée entre guillemets doubles :

  location:"us central1"
  

• Si l'expression est placée entre guillemets doubles et contient également un guillemet double (") ou une barre oblique inverse (\), vous devez les échapper en les remplaçant par \" ou \\. Vous pouvez également les remplacer par un espace unique, car les caractères non alphanumériques sont traités comme des délimiteurs lors de la recherche. Les requêtes suivantes sont traitées de la même manière :

  description:"One of \"those\" descriptions."
  description:"One of those descriptions."
  

• Lorsque vous utilisez la gcloud CLI ou l'API REST, vous devez échapper les guillemets doubles utilisés pour indiquer une expression :

  --query="location:(a \"us central1\")"
  

  "query": "location:(a \"us central1\")"
  

Combinaisons

Les expressions de recherche peuvent être combinées à l'aide des opérateurs logiques en majuscules AND ou OR. L'inclusion de AND est facultative lorsque vous utilisez des parenthèses. Par exemple, les requêtes suivantes sont traitées de la même manière :

policy:(alex charlie)
policy:(alex AND charlie)

Si un élément contient un champ de métadonnées avec une liste de valeurs, une combinaison AND ne garantit pas que tous les mots doivent figurer dans un seul élément. Par exemple, si un champ de métadonnées est policy=["[e-mail]", "[e-mail]", "[e-mail]"], la recherche avec policy:(alex charlie) correspond, car [e-mail] contient alex et [e-mail] contient charlie.

Vous pouvez utiliser des parenthèses pour regrouper les types de combinaisons. L'exemple suivant renvoie les éléments dont le champ "policy" contient alex et charlie dans n'importe quel ordre, ou les éléments dont le champ "policy" contient bola.

policy:((alex charlie) OR bola)

Vous pouvez utiliser une expression dans une combinaison pour faire correspondre plusieurs mots dans un ordre consécutif. L'exemple suivant renvoie les composants dont le champ de stratégie contient alex et 2020 dans l'ordre consécutif, ou bola :

policy:(("alex 2020") OR bola)

Exemples de combinaisons

Les requêtes suivantes illustrent différentes combinaisons. Notez l'emplacement des parenthèses pour séparer les opérateurs AND et OR. Il est impossible de combiner des opérateurs dans un même ensemble de parenthèses. Par exemple : policy:(alex charlie OR bola).

Requête	Description
policy:(alex charlie)	Renvoie les éléments dont le champ policy contient à la fois alex et charlie.
policy:(alex OR charlie)	Renvoie les éléments dont le champ policy contient alex ou charlie.
policy:((alex charlie) OR bola)	Renvoie les composants dont le champ policy contient à la fois alex et charlie, ou le mot bola.
policy:(alex charlie) OR name:bola	Renvoie les éléments dont le champ policy contient alex et charlie, ou dont le champ name contient bola.

Négation

Vous pouvez utiliser l'opérateur NOT en majuscules pour nier les requêtes de recherche. Les parenthèses sont acceptées, mais pas obligatoires.

Remarque : La négation n'est acceptée que lors de la recherche de ressources, et non de stratégies IAM.

Exemples de négation

• Renvoie les éléments dont le champ state ne contient pas le mot running.

  NOT state:running
  

• Renvoie les composants dont le champ policy ne contient ni alex ni charlie.

  NOT policy:(alex OR charlie)
  

• Renvoie les composants dont le champ networkTags ne contient pas internal ni private.

  NOT (networkTags:internal OR networkTags:private)
  

Caractères génériques

Les astérisques (*) peuvent être utilisés dans une expression en tant que caractère générique. Selon sa position, un astérisque peut avoir différentes significations.

• Si * se trouve à la fin d'une expression, il est traité comme une correspondance de préfixe de jeton. Par exemple, "al 20*" équivaut à (al* 20*). L'ordre des préfixes n'a pas d'importance.

  L'expression "al 20*" correspond à une valeur de champ avec un jeton commençant par al (comme alex) et un jeton commençant par 20 (comme 2020).

• Pour labels, si la valeur de requête entière ne contient qu'un seul * (par exemple, "labels.env:*"), cela représente une vérification de l'existence. Autrement dit, inventaire des éléments cloud vérifie si la clé de libellé env existe. Seul le champ labels accepte les vérifications d'existence.

• Si * se trouve au milieu d'une expression (par exemple, "compute*storage"), il est traité comme un délimiteur de tokenisation. Cette valeur de requête équivaut à "compute storage".

• Si * se trouve au début et à la fin d'une expression, par exemple "*compute storage*", il est traité comme un délimiteur de tokenisation. La valeur de cette requête équivaut à "compute storage".

Comparaison numérique et de codes temporels

Pour comparer des valeurs numériques et des codes temporels, utilisez des opérateurs de comparaison avec la syntaxe suivante :

ASSET_METADATA_FIELD>=QUERY

Voici les opérateurs de comparaison disponibles :

• = : égal à

• > : supérieur à

• >= : supérieur ou égal à

• < : inférieur à

• <= : inférieur ou égal à

Pour effectuer une comparaison avec des codes temporels tels que ceux stockés dans les champs de métadonnées d'éléments createTime et updateTime, utilisez un entier signé de 64 bits (le code temporel d'époque en secondes) ou une chaîne de date et heure UTC+0 dans l'un des formats suivants :

• 2021-01-01 (AAAA-MM-JJ)

• "2021-01-01T00:00:00" ("YYYY-MM-DDThh:mm:ss")

Exemples de date et heure

Un élément dont le champ createTime a la valeur 1609459200 (horodatage de l'époque de 2021-01-01T00:00:00) correspond aux requêtes suivantes :

createTime=1609459200
createTime=2021-01-01
createTime="2021-01-01T00:00:00"

createTime>1500000000
createTime>2020-01-01
createTime>"2020-01-01T00:00:00"

createTime>=1609459200
createTime>=2021-01-01
createTime>="2021-01-01T00:00:00"

createTime<1700000000
createTime<2022-01-01
createTime<"2022-01-01T00:00:00"

createTime<=1609459200
createTime<=2021-01-01
createTime<="2021-01-01T00:00:00"