Documentation sur Oracle Cloud Infrastructure

Syntaxe du langage de recherche

Cette rubrique présente les concepts de base relatifs au langage d'interrogation pour le service de recherche, ainsi qu'une explication de la syntaxe et des règles pour vous permettre de créer vos propres interrogations. Les interrogations appliquent des conditions de recherche à des types de ressource spécifiques et vous permettent de trier les résultats. Le langage d'interrogation vous donne un contrôle plus nuancé et explicite sur les paramètres de recherche, ce qui le rend particulièrement utile dans les cas où des modifications précises d'une interrogation peuvent donner des résultats différents.

Pour effectuer une recherche sur tous les types de ressource et attributs de ressource pris en charge sans trier les résultats de recherche, ou si vous préférez utiliser l'interface de la console pour spécifier des paramètres de recherche, vous n'avez pas besoin de créer une interrogation. À la place, vous pouvez rechercher une correspondance partielle ou exacte avec du texte à structure libre sans appliquer la syntaxe du langage d'interrogation.

Lorsque vous êtes prêt à exécuter une interrogation, voir Interrogation sur les ressources pour obtenir des instructions.

Notions de base sur les interrogations

Les exemples suivants présentent la syntaxe de base d'une interrogation .

Pour rechercher des ressources qui répondent à une ou plusieurs conditions décrites par une instruction condition qui utilise des opérateurs de comparaison :

query <resourceType> resources where <conditions>

Pour interroger les ressources qui répondent à une ou plusieurs conditions et pour inclure des attributs de ressource triés dans les résultats :

query <resourceType> resources return <fieldName> where <conditions> sorted by <fieldName> <order>

Ou pour rechercher les ressources qui ont un attribut avec une valeur correspondant à ce que vous spécifiez :

query <resourceType> resources return <fieldName> matching <keywords>

Le service de recherche ignore les blancs, les indentations et les sauts de ligne. Les exemples d'interrogations comportent des indentations pour améliorer la lisibilité. Dans les exemples, les variables sont représentés par du texte en italique comprenant un ou plusieurs mots-clés indiqué entre crochets (<>).

Dans une interrogation, les clauses comprennent les éléments suivants :

  • query - (obligatoire) Sélectionne les ressources à retourner en fonction des clauses ultérieures. Les énoncés d'interrogation commencent toujours par le mot query.
  • return - Spécifie les attributs de ressource à inclure dans la vue étendue ou améliorée des résultats de recherche. Pour plus d'informations, voir Attributs de retour.
  • where - Recherche les ressources correspondant aux conditions indiquées. Pour plus d'information, voir Conditions.
  • matching - Recherche les ressources présentant une correspondance avec le texte spécifié, peu importe. Il peut s'agir d'une correspondance exacte de texte, d'une correspondance du type de ressource ou bien de la présence du texte dans un attribut indexé de la ressource. Pour plus d'informations, voir Correspondance.
  • sorted by - Trie les ressources en fonction de la variable fieldName dans l'ordre spécifié par order. Sans cette clause, la recherche liste les résultats par date de création en ordre décroissant, avec les ressources les plus récentes listées en premier. Pour plus d'informations, voir Tri.

Les clauses sont facultatives sauf indication contraire. Aux fins de correspondance, vous pouvez utiliser les clauses where et matching séparément ou ensemble.

Dans la clause query, vous spécifiez les informations suivantes :

  • resourceType - (Requis) Spécifie le type de ressource auquel les clauses suivantes s'appliquent lors de l'exécution de l'interrogation. Vous pouvez spécifier le nom du type de ressource (par exemple, database ou group) ou all. Si vous spécifiez all, la recherche recherche les correspondances avec conditions spécifié pour tous les types de ressource. Vous pouvez effectuer des interrogations sur des types de ressource individuels, mais pas des types de famille. Pour obtenir la liste des types de ressource pris en charge, voir Ressources prises en charge sous Aperçu du service de recherche.
  • resources - (obligatoire) Indique que le texte que vous soumettez est une interrogation de ressource.

Attributs de retour

Pour les utilisateurs de la trousse SDK ou de l'interface de ligne de commande, la clause return indique les attributs de ressource étendus que vous voulez voir inclus avec les résultats de recherche retournés par l'interrogation. Vous pouvez utiliser la clause return pour forcer le retour d'attributs de ressource spécifiques ou de tous les attributs de ressource dans les résultats de recherche, ce qui vous donne plus de détails sur chaque ressource.

Par défaut, les résultats de recherche affichent un jeu limité d'attributs de ressource communs pour toute ressource correspondante. Dans la console, ces attributs de ressource incluent le nom d'affichage, le type de ressource, l'OCID, le compartiment, l'état du cycle de vie et l'heure de création. Dans la trousse SDK ou l'interface de ligne de commande, les résultats de recherche de ressources de base incluent également le domaine de disponibilité et tous les marqueurs associés à la ressource. Lorsqu'une interrogation trouve une correspondance en dehors des attributs de ressource communs, les résultats de recherche développés incluent et mettent en surbrillance les attributs correspondants spécifiques ainsi que les résultats de base. Avec la clause return, vous pouvez obtenir plus de détails sur la correspondance des résultats de recherche, même si l'interrogation n'entraîne pas autrement de correspondance dans les attributs de ressource que vous voulez voir.

Dans une interrogation, la clause return se compose des éléments suivants :

return <fieldName>

Le mot clé fieldName identifie un attribut d'une ressource. Par exemple, lorsque le type de ressource visé par l'interrogation est une instance, l'indication shape indique que vous voulez voir la forme de toutes les instances correspondantes. (Dans le cas des instances seulement, fieldName peut identifier un attribut d'une ressource connexe, par exemple l'adresse IP privée sur l'attachement de la carte vNIC d'une instance. La spécification de attachedVnic.privateIp indique que vous voulez voir l'adresse IP privée de l'attachement entre une carte vNIC et une instance.)

Les détails supplémentaires disponibles pour une ressource particulière dépendent des attributs de ressource qui ont été indexés pour le type de ressource. Pour rechercher les noms de tous les attributs de ressource indexés pour un type de ressource, utilisez la trousse SDK ou l'interface de ligne de commande pour exécuter une interrogation qui inclut la clause return, mais au lieu de spécifier le nom du champ, spécifiez que vous voulez voir allAdditionalFields. Par exemple :

query instance resources return allAdditionalFields

Cette interrogation produit une réponse qui affiche tous les attributs de ressource indexés pour le type de ressource d'instance. (La console ne peut pas afficher ces autres champs, sauf pour les ressources d'instance lorsque vous appliquez le filtre de type de ressource, c'est pourquoi vous devez utiliser la trousse SDK ou l'interface de ligne de commande pour extraire les informations.) Dans les résultats de recherche, les détails supplémentaires disponibles (et la structure de ces informations) dépendent du type de ressource correspondant. En outre, vous devez disposer de l'autorisation nécessaire pour voir les attributs de ressource que vous avez demandés de voir avec votre interrogation.

Vous pouvez combiner la clause return avec la clause where pour obtenir des résultats avec des détails spécifiques tout en appliquant une ou plusieurs conditions. Par exemple :
query instance resources return allAdditionalFields where assignedEntityType = 'PRIVATE_IP'

Cette interrogation produit une réponse qui affiche tous les attributs de ressource indexés pour toutes les ressources d'instance qui ont un champ assignedEntityType avec la valeur PRIVATE_IP.

Restrictions

Vous ne pouvez utiliser la clause return que pour un type de ressource à la fois. L'interrogation ne peut pas spécifier plusieurs types de ressource si vous incluez la clause return. Toutefois, si vous le souhaitez, vous pouvez spécifier plusieurs champs à retourner pour un type de ressource particulier.

Vous ne pouvez pas inclure à la fois le mot clé allAdditionalFields et les noms de champ individuels dans la même interrogation. Vous pouvez spécifier le mot clé allAdditionalFields ou spécifier des noms de champ individuels ou plus, séparés par des virgules.

Conditions

La clause where applique des conditions qui filtrent les résultats retournés par la recherche. Vous pouvez indiquer un ou plusieurs énoncés de condition. Pour plus d'informations sur les conditions multiples, voir Regroupement de conditions.

Dans une interrogation, les conditions se composent des éléments suivants :

<fieldName> <operation> <value>

Le mot-clé fieldName est l'attribut de ressource par rapport auquel l'opération et la valeur choisie de cet attribut sont évaluées. Chaque champ est associé à un type de champ. Le type de champ vous indique le format attendu pour n'importe quelle valeur de ce champ. Quel type d'opération vous pouvez utiliser dans un énoncé de conditions dépend du type de champ.

Dans les conditions de l'interrogation, une opération (operation) est un opérateur de comparaison qui s'applique à l'élément value de l'énoncé. Le mot clé value correspond à la valeur spécifiée pour fieldName. La recherche évalue si l'attribut spécifié du type de ressource sélectionné correspond ou non à value, selon l'opération. Dans une interrogation, vous devez inclure une chaîne ou une valeur date-heure entre des apostrophes droites (ˈ) ou des guillemets (") d'ouverture et de fermeture.

Le tableau suivant présente les opérations prises en charge pour les interrogations de ressource :

Opération Description Types de champ pris en charge Sensible à la casse? Exemple
=

Égal à (ou correspondance exacte pour les chaînes)

Chaîne, entier, rationnel, booléen, date-heure

Non

 Si la variable value a la valeur ' backUp', les résultats incluent les correspondances avec "backup", "BACKUP", "BackUp", "backUp" et toute autre variation de casse.
!=

N'est pas égal à

Chaîne, entier, rationnel, booléen, date-heure

Non

 Si la variable value a la valeur ' backUp', les résultats incluent tout ce qui ne correspond pas à "backUp", "backup" ou toute autre variation de casse. Les résultats comprennent également tout ce qui ne contient pas les caractères 'backup' dans cet ordre.
==

Strictement égal à

Chaîne

Oui

 Si la variable value a la valeur 'backUp', les résultats incluent uniquement les correspondances avec "backUp" et aucune variation de casse.
!==

Est strictement différent de

Chaîne

Oui

 Si la variable value a la valeur 'backUp', les résultats incluent les correspondances avec "backup", "BACKup" et toute autre variation de casse à l'exception de "backUp".
=~

Contient

Chaîne

Non

 Si la variable value a la valeur 'backUp', les résultats incluent les correspondances avec "backup", "BACKUP", "BackUp", "backUp" ou toute autre variante de casse, ou les valeurs qui contiennent ces caractères dans cet ordre, en même temps que d'autres caractères.
>=

Supérieur ou égal à

Entier, rationnel, date-heure

Sans objet

 Pour une interrogation comportant la condition size >= 5, les résultats ont une valeur supérieure ou égale à 5 dans le champ size.
>

Supérieur à

Entier, rationnel, date-heure

Sans objet

 Pour une interrogation comportant la condition size > 5, les résultats ont une valeur supérieure à 5 dans le champ size.
<=

Inférieur ou égal à

Entier, rationnel, date-heure

Sans objet

 Pour une interrogation comportant la condition size <= 5, tous les résultats ont une valeur inférieure ou égale à 5 dans le champ size.
<

Inférieur à

Entier, rationnel, date-heure

Sans objet

 Pour une interrogation comportant la condition size < 5, tous les résultats ont une valeur inférieure ou égale à 5 dans le champ size.

Le tableau suivant énumère quelques exemples d'attributs de ressource appartenant à chaque catégorie de types de champ pris en charge. (Comme décrit précédemment, le type de champ vous indique le format attendu pour un champ donné et le type d'opération avec lequel vous pouvez le coupler dans un état des conditions.)

Le tableau n'inclut pas tous les exemples possibles pour un type de champ donné et n'inclut pas d'exemples de chaque type de ressource. Si vous voulez savoir quel format le service de recherche attend pour un attribut de ressource spécifique, vous pouvez utiliser l'interface de ligne de commande ou l'API pour en savoir plus sur les attributs de ressource. Vous pouvez également consulter la documentation sur l'API. La documentation sur l'API offre des informations de référence sur chaque type de ressource pris en charge : attributs, types de champ et toute restriction applicable. Pour plus d'informations, voir Ressources prises en charge sous Aperçu du service de recherche.

Type Exemples d'attributs de ressource
Chaîne Afficher les noms, les états du cycle de vie, les domaines de disponibilité, les étiquettes, les blocs CIDR et les URL
Nombre entier Taille ou longueur d'une ressource
Rationnel Stockage de données disponible
Booléen Si une fonctionnalité est activée ou configurée, si une ressource est saine, si une ressource est publique ou privée, si quelque chose est la dernière version et si quelque chose est autorisé
Date/heure Dates de création, dates de dernière mise à jour, dates de dernière mise à jour et redémarrages de maintenance programmés

Regroupement de conditions

En incluant plusieurs énoncés de condition dans une interrogation, vous pouvez affiner les résultats en fonction de plusieurs critères. Vous pouvez regrouper des conditions en utilisant les opérateurs logiques && (perluettes, pour indiquer un ET logique), || (barres verticales, pour indiquer un OU logique) ou l'opérateur logique IN. Par exemple :

licenseModel = 'LICENSE_INCLUDED' && dataStoragePercentage > 40 && lifecycleState != 'FAILED'

Dans l'exemple précédent, tous les résultats ont pour valeur LICENSE_INCLUDED dans le champ nommé licenseModel, une valeur supérieure à 40 dans le champ nommé dataStoragePercentage et une valeur dans le champ lifecycleState autre que FAILED.

Vous ne pouvez pas combiner deux opérateurs logiques différents dans la même interrogation, sauf si vous placez un groupe de prédicat entre parenthèses. (Sinon les conditions multiples peuvent seulement utiliser le même opérateur logique.) Par exemple :

(licenseModel = 'LICENSE_INCLUDED' && dataStoragePercentage > 40) || lifecycleState != 'FAILED'

Dans l'exemple précédent, les résultats retournés ont la valeur LICENSE_INCLUDED dans le champ nommé licenseModel et une valeur supérieure à 40 dans le champ nommé dataStoragePercentage ou la valeur de leur champ lifecycleState est différente de FAILED.

Le groupe suivant est également acceptable :

licenseModel = 'LICENSE_INCLUDED' && (dataStoragePercentage > 40 || lifecycleState != 'FAILED')

Dans l'exemple précédent, les résultats retournés ont la valeur LICENSE_INCLUDED dans le champ nommé licenseModel et une valeur supérieure à 40 dans le champ nommé dataStoragePercentage ou une valeur différente de FAILED dans le champ nommé lifecycleState.

Pour appliquer plusieurs conditions dans lesquelles chaque condition accepte plusieurs valeurs possibles, l'utilisation d'un opérateur IN logique peut simplifier une interrogation. Par exemple, vous pouvez utiliser les conditions suivantes :
licenseModel IN ('LICENSE_INCLUDED', 'BRING_YOUR_OWN_LICENSE') && dbWorkload IN ('OLTP', 'DW', 'AJD', 'APEX')
Dans l'exemple précédent, tous les résultats retournés ont la valeur LICENSE_INCLUDED ou BRING_YOUR_OWN_LICENSE dans le champ nommé licenseModel et la valeur OLTP, DW, AJD ou APEX dans le champ nommé dbWorkload. L'exemple précédent peut remplacer des conditions d'interrogation plus complexes, telles que les suivantes :
(licenseModel = 'LICENSE_INCLUDED' && dbWorkload = 'OLTP') || (licenseModel = 'BRING_YOUR_OWN_LICENSE' && dbWorkload = 'OLTP') || (licenseModel = 'LICENSE_INCLUDED' && dbWorkload = 'DW') || (licenseModel = 'BRING_YOUR_OWN_LICENSE' && dbWorkload = 'DW') || (licenseModel = 'LICENSE_INCLUDED' && dbWorkload = 'AJD') || (licenseModel = 'BRING_YOUR_OWN_LICENSE' && dbWorkload = 'AJD') || (licenseModel = 'LICENSE_INCLUDED' && dbWorkload = 'APEX') || (licenseModel = 'BRING_YOUR_OWN_LICENSE' && dbWorkload = 'APEX')
Ou même ce qui suit :
((licenseModel = 'LICENSE_INCLUDED' || licenseModel = 'BRING_YOUR_OWN_LICENSE') && (dbWorkload = 'OLTP' || dbWorkload = 'DW' || dbWorkload = 'AJD' || dbWorkload = 'APEX'))

Ces deux exemples utilisent l'opérateur logique OR pour exprimer efficacement les mêmes conditions en termes plus verbose que l'exemple qui utilise l'opérateur logique IN.

La recherche n'effectue pas d'évaluation de gauche à droite pour réduire l'ambiguïté ou clarifier l'intention.

Valeurs de date-heure

Vous pouvez indiquer des valeurs de date-heure en utilisant un des formats suivants :

Format Exemples Commentaires
<yyyy>-<MM>-<dd> <HH>:<mm>:<ss> <TimeZone>

'2018-06-19 16:15:41 PDT', '2018-06-19 16:15:41 -08:00'

 TimeZone est facultatif. Si TimeZone est omis, UTC est utilisé.
<EEE>, <d> <MMM> <yyyy> <HH>:<mm>:<ss> <TimeZone>

'Mar, 19 Jun 2018 16:15:41 +0300', '19 Juin 2018 16:15:41'

 EEE est facultatif. La MMM peut également être exprimée en MMMM. TimeZone est également facultatif. Si TimeZone est omis, UTC est utilisé.
<yyyy>-<MM>-<dd>T<HH>:<mm>:<ss>Z

"2018-06-19T16:15:41Z"

Heure en UTC. 'T' et 'Z' sont sensibles à la casse.

Vous devez respecter les espaces. Les tirets, les deux-points, les virgules et les caractères 'T'et 'Z' sont interprétés de manière littérale. Pour interpréter les paramètres fictifs dans le tableau précédent, reportez-vous au tableau suivant :

Lettre Composant de date-heure Présentation
y

Année

Année
M

Mois dans l'année

Mois
d

Jour du mois

Jour
H Heure du jour (de 00 à 23) Nombre
m Minutes dans l'heure Nombre
s Secondes dans la minute Nombre
E Jour de la semaine Texte

Les lettres sont répétées pour indiquer la présentation exacte. Par exemple, 'HH' signifie que vous devez utiliser '00' et non '0' pour représenter minuit. De même, 'EEE' signifie 'Mar' et pas 'Mardi'. De la même manière, '09' doit être utilisé au lieu de '9' pour 'MM' pour indiquer le mois de septembre.

TimeZone est facultatif, mais vous pouvez spécifier TimeZone de l'une des façons suivantes :

  • Nom. Vous pouvez indiquer un fuseau horaire par son nom, par exemple GMT ou PDT. Les valeurs ne sont pas sensibles à la casse.
  • Décalage GMT. Vous pouvez indiquer un fuseau horaire en fonction de son décalage par rapport à GMT. Par exemple, GMT-08:00. Les valeurs ne sont pas sensibles à la casse.
  • Fuseau horaire ISO 8601. Vous pouvez indiquer un fuseau horaire en fonction des normes ISO 8601. Par exemple, -08, -0800 ou -08:00.

Au lieu d'utiliser un des formats précédents, vous pouvez t spécifier une valeur de date-heure avec la constante now. La constante now représente l'heure courante au niveau de granularité des secondes dans une minute.

Enfin, vous pouvez ajouter ou soustraire des intervalles de temps à n'importe quelle valeur de date-heure. Par exemple, vous pouvez effectuer une interrogation sur les ressources qui ont été créées dans une période de cinq minutes par rapport à une heure particulière. Le service de recherche prend en charge les intervalles de temps suivants :

Lettre Composant de date-heure
s

Secondes
m

Minutes
h

Heures
d Jours
w Semaines

Pour spécifier un intervalle de temps par rapport à une valeur de date-heure, utilisez un des formats suivants :

  • now - 3h
  • 2018-06-19 16:15:41 PDT + 1h

Correspondance

Aux fins de correspondance, au lieu ou en plus d'utiliser une clause where avec des conditions, vous pouvez utiliser la clause matching. La clause matching évite de devoir spécifier des conditions (contenant un nom de champ, une opération et une valeur). La clause matching effectue une interrogation sur tous les champs indexés en appliquant l'opérateur = (égal à) avec le texte que vous spécifiez. Cependant, il le fait sans avoir besoin d'une correspondance exacte. Par exemple, l'interrogation suivante utilise une clause matching qui se comporte de la même manière que la recherche en texte libre :

query all resources matching 'instance'

Les résultats incluent toutes les ressources et tous les attributs de ressources qui contiennent le mot "instance".

La clause matching interroge tous les champs indexés pour les correspondances, mais ignore les caractères spéciaux, y compris toute ponctuation.

Tri

La dernière clause d'une interrogation de ressources est la clause sorted by, qui est facultative. La clause sorted by trie les résultats retournés par le service de recherche en fonction du nom du champ et les liste dans l'ordre order indiqué. Par défaut, si vous n'indiquez pas d'ordre de tri, les résultats sont toujours triés par date-heure de création en ordre décroissant.

Dans la clause sorted by, vous pouvez spécifier les éléments suivants :

  • fieldName - Champ utilisé par le service de recherche pour trier les résultats. Vous pouvez spécifier n'importe quel champ de n'importe quelle ressource. Les ressources qui ne contiennent pas le champ indiqué sont listées après les ressources qui le contiennent.
  • order - Vous pouvez spécifier asc ou desc. Si vous indiquez asc, les résultats sont listés en ordre croissant. Si vous indiquez desc, les résultats sont listés en ordre décroissant.

Interrogation de plusieurs types de ressource

Vous pouvez interroger plusieurs types de ressource à la fois en joignant des interrogations. Chaque interrogation peut avoir sa propre clause conditionnelle. Si les interrogations que vous souhaitez joindre présentent des conditions "where" différentes, la syntaxe diffère alors du cas où des interrogations sur plusieurs types de ressource partagent la même condition "where".

La syntaxe de base d'une interrogation sur plusieurs types de ressource est la suivante :

query <resourceType>, <resourceType> resources

Par exemple :

query group, user resources

L'interrogation précédente retourne tous les groupes et tous les utilisateurs de la location.

Voici la syntaxe d'une interrogation pour plusieurs types de ressource avec des conditions identiques pour tous les types de ressource :

query <resourceType>, <resourceType> resources where <conditions>

Par exemple :

query group, user resources where displayName = 'administrator'

L'interrogation précédente retourne tous les groupes portant le nom d'affichage "administrator" et tous les utilisateurs dotés du nom d'affichage "administrator", avec toutes les variantes de casse.

Si vous devez appliquer des conditions différentes à un type de ressource quelconque, vous devez utiliser un mot clé union au lieu d'une virgule entre les interrogations jointes. Voici la syntaxe d'une interrogation pour plusieurs types de ressource où certains types partagent des conditions alors que d'autres ne les partagent pas :

query <resourceType>, <resourceType> resources where <conditions> union <resourceType> resources

Par exemple :

query group, user resources where displayName = 'administrator' union compartment resources

L'exemple précédent retourne tous les groupes portant le nom d'affichage "administrateur" et tous les utilisateurs ayant le nom d'affichage "administrator", avec toutes les variantes de casse, ainsi que toutes les ressources du compartiment.

Ou, par exemple :

query group resources union user resources where displayName = 'administrator' union compartment resources

L'exemple précédent retourne tous les groupes et tous les compartiments. Il retourne également tous les utilisateurs portant le nom d'affichage "administrator", avec toutes les variantes de casse.

Facultativement, vous pouvez ajouter la clause sorted by à la fin de l'interrogation pour classer tous les résultats en ordre croissant ou décroissant.