Syntaxe des requêtes de recherche

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

Champs et ressources indexables

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

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

Pour connaître les ressources que vous pouvez rechercher, consultez la section 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 rechercher une correspondance exacte de texte, utilisez l'opérateur = (égalité) avec la syntaxe suivante:

ASSET_METADATA_FIELD=QUERY

Exemple :

location=us-central1-a

Tenez compte des règles suivantes lorsque vous utilisez la correspondance exacte:

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

• Pour un champ dont la valeur est une liste, si la valeur de la requête correspond à l'un des éléments de la liste, elle est considérée comme une correspondance.

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

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

Mise en 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 la 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

Les règles de tokenisation pour la mise en correspondance partielle du texte sont les suivantes:

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

• Les caractères qui ne sont pas alphanumériques ([a-zA-Z0-9]), les traits de soulignement (_) ou les esperluettes (&) sont traités comme des séparateurs.

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 correspondances exactes et partielles de texte

Un élément 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	Correspondance, 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 la 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 consécutif.
location:(central1 us a)	Correspondance, 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")	Correspondance, car les expressions de la combinaison, a et "us central1", correspondent aux mots de la valeur du champ dans n'importe quel ordre. Étant donné que "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 effectuer une correspondance de préfixe.

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

Requête	Motif de la non-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 textuelle

Une valeur de requête peut être composée de phrases, de combinaisons, de négations et d'espaces réservés.

Expressions

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

La requête suivante correspond aux éléments dont le champ policy contient le mot alex et le mot 2020 dans l'ordre:

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. . est ignoré, car les signes de ponctuation sont traités comme des délimiteurs.

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.

Créer une phrase

Tenez compte des règles suivantes lorsque vous créez une phrase:

• 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'adresse e-mail ou d'URL de base [_-+.@/&], ou des caractères génériques [*], vous n'avez pas besoin de la placer entre guillemets doubles:

  policy:[e-mail]
  

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

  policy:"[e-mail]"
  

• Si la phrase 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 qu'elle contient également des guillemets doubles (") ou une barre oblique inverse (\), vous devez les échapper en tant que \" 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 d'une 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 gcloud CLI ou l'API REST, vous devez échapper aux doubles guillemets utilisés pour indiquer une phrase:

  --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 composant contient un champ de métadonnées avec une liste de valeurs, une combinaison AND ne garantit pas que tous les mots doivent se trouver 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 des types de combinaisons. L'exemple suivant renvoie les éléments dont le champ de stratégie contient alex et charlie dans n'importe quel ordre, ou les éléments dont le champ de stratégie contient bola.

policy:((alex charlie) OR bola)

Vous pouvez utiliser une expression dans une combinaison pour faire correspondre plusieurs mots dans l'ordre. L'exemple suivant renvoie les éléments 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. La combinaison d'opérateurs dans un seul ensemble de parenthèses n'est pas valide (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 éléments 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 des requêtes de négation de recherche à l'aide de l'opérateur NOT en majuscule. 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 éléments dont le champ policy ne contient ni alex, ni charlie.

  NOT policy:(alex OR charlie)
  

• Renvoie les éléments dont le champ networkTags ne contient ni 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 la 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*" correspond à (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 (par exemple, alex) et un jeton commençant par 20 (par exemple, 2020).

• Pour labels, si la valeur entière de la requête ne contient qu'un seul * (par exemple, "labels.env:*"), il s'agit d'une vérification d'existence. Autrement dit, inventaire des éléments cloud vérifie si la clé de libellé env existe. Seul le champ labels est compatible avec 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 est équivalente à "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. Cette valeur de requête est équivalente à "compute storage".

Comparaison numérique et code temporel

Pour la comparaison numérique et de code temporel, utilisez des opérateurs de comparaison avec la syntaxe suivante:

ASSET_METADATA_FIELD>=QUERY

Les opérateurs de comparaison disponibles sont les suivants:

• =: égal à

• >: supérieur à

• >= : supérieur ou égal à

• <: inférieur à

• <= : inférieur ou égal à

Pour comparer 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 (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/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"