Documentation Oracle Cloud Infrastructure

Syntaxe de langage de recherche

Cette rubrique décrit les concepts de base du langage de requête pour le service Search, notamment une explication de la syntaxe et des règles pour que vous puissiez créer vos propres requêtes. Les requêtes appliquent des conditions de recherche à des types de ressource spécifiques et vous permettent de trier les résultats. Le langage de requête 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 requête peuvent donner des résultats différents.

Si vous souhaitez effectuer une recherche sur tous les types de ressource et attributs de ressource pris en charge et que vous n'avez pas besoin de trier les résultats de recherche, ou si vous préférez utiliser l'interface de console pour spécifier des paramètres de recherche, vous n'avez pas besoin de construire une requête. A la place, vous pouvez rechercher une correspondance partielle ou exacte de texte au format libre sans appliquer la syntaxe du langage de requête à la recherche.

Pour plus d'informations, reportez-vous à Interrogation des ressources.

Notions de base sur les requêtes

Les exemples suivants illustrent la syntaxe de base d'une requête .

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

query <resourceType> resources where <conditions>

Pour rechercher des ressources qui répondent à une ou plusieurs conditions et pour inclure des attributs de ressource triés dans les résultats, procédez comme suit :

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

Ou, pour rechercher les ressources ayant un attribut avec une valeur correspondant à ce que vous indiquez :

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

Search ne prend pas en compte les caractères non imprimables, les retraits et les sauts de ligne. Les exemples de requêtes comprennent des retraits pour améliorer la lisibilité. Afin de présenter uniquement la syntaxe, les chevrons (<>) et le texte en italique indiquent des variables, lesquelles peuvent être constituées d'un ou de plusieurs mots-clés.

Les clauses suivantes sont incluses dans une requête :

  • query : (requise) sélectionne les ressources à renvoyer en fonction de clauses ultérieures. Les instructions de requête commencent toujours par le mot query.
  • return - Spécifie les attributs de ressource à inclure dans la vue développée ou améliorée des résultats de recherche. Pour plus d'informations, reportez-vous à Attributs de retour.
  • where : met en correspondance les ressources avec les conditions indiquées. Pour plus d'informations, reportez-vous à Conditions.
  • matching : met en correspondance les ressources avec le texte indiqué, qu'il corresponde exactement au texte indiqué ou au type de ressource ou encore qu'il apparaisse dans un attribut de ressource indexé. Pour plus d'informations, reportez-vous à Correspondance.
  • sorted by : permet de trier les ressources selon fieldName, dans l'ordre indiqué par order. Sans cette clause, Search répertorie les résultats par date de création dans l'ordre décroissant, en répertoriant les ressources les plus récentes en premier. Pour plus d'informations, reportez-vous à Tri.

Les clauses sont facultatives, sauf indication contraire. A des fins de mise en correspondance, vous pouvez utiliser la clause where et la clause matching séparément ou ensemble.

Dans la clause query, indiquez les informations suivantes :

  • resourceType : (obligatoire) indique le type de ressource auquel les clauses suivantes s'appliquent lorsque vous exécutez la requête. Vous pouvez indiquer le nom du type de ressource (par exemple, database ou group) ou all. Si vous indiquez all, la recherche recherche les correspondances avec la valeur conditions indiquée pour tous les types de ressource. Vous pouvez interroger des types de ressource individuels, mais pas des types de famille. Pour obtenir la liste des types de ressource pris en charge, reportez-vous à Ressources prises en charge dans Présentation de Search.
  • resources : (obligatoire) indique que le texte que vous soumettez est une requête de ressource.

Attributs de retour

Pour les utilisateurs du kit SDK ou de l'interface de ligne de commande, la clause return indique les attributs de ressource étendue à inclure dans les résultats de recherche renvoyés par la requête. 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 ensemble limité et commun d'attributs de ressource 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 de cycle de vie et l'heure de création. Dans le kit SDK ou l'interface de ligne de commande, les résultats de recherche de ressource de base incluent également le domaine de disponibilité et toutes les balises associées à la ressource. Lorsqu'une requête 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 et les résultats de base. Avec la clause return, vous pouvez obtenir plus de détails sur les résultats de recherche correspondants, même si la requête n'entraîne pas de correspondance dans les attributs de ressource à afficher.

Dans une requête, 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 ciblé par la requête est une instance, la spécification de shape indique que vous voulez voir la forme de toutes les instances correspondantes. (Dans le cas des instances uniquement, fieldName peut identifier un attribut d'une ressource associée, comme l'adresse IP privée sur l'attachement de carte d'interface réseau virtuelle d'une instance. Si vous indiquez attachedVnic.privateIp, vous voulez afficher l'adresse IP privée de l'attachement entre une carte d'interface réseau virtuelle et une instance.)

Les détails supplémentaires disponibles pour une ressource particulière dépendent des attributs de ressource indexés pour le type de ressource. Afin de rechercher les noms de tous les attributs de ressource indexés pour un type de ressource, utilisez le kit SDK ou l'interface de ligne de commande pour exécuter une requête qui inclut la clause return, mais au lieu d'indiquer le nom du champ, indiquez que vous voulez afficher allAdditionalFields. Par exemple :

query instance resources return allAdditionalFields

Cette requête génère 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, à l'exception des ressources d'instance lorsque vous appliquez le filtre de type de ressource, c'est pourquoi vous devez utiliser le kit SDK ou l'interface de ligne de commande pour extraire les informations.) Dans les résultats de la 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 des droits d'accès nécessaires pour afficher les attributs de ressource que vous avez demandés avec votre requête.

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

Cette requête génère une réponse qui affiche tous les attributs de ressource indexés pour toutes les ressources d'instance dotées d'un champ assignedEntityType avec la valeur PRIVATE_IP.

de dénomination

Vous ne pouvez utiliser la clause return que pour un seul type de ressource à la fois. La requête ne peut pas indiquer plusieurs types de ressource si vous incluez la clause return. Toutefois, si vous le souhaitez, vous pouvez spécifier plusieurs champs à renvoyer 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 requête. Vous pouvez indiquer le mot-clé allAdditionalFields ou indiquer des noms de champ individuels, séparés par des virgules.

Conditions

La clause where applique les conditions qui filtrent les résultats renvoyés par Search. Vous pouvez spécifier des instructions de condition. Pour plus d'informations sur les conditions multiples, reportez-vous à Regroupement de conditions.

Dans une requête, le paramètre conditions se compose des éléments suivants :

<fieldName> <operation> <value>

Le mot-clé fieldName est l'attribut de ressource par rapport auquel l'évaluation de operation et du value choisi de cet attribut est effectuée. Chaque champ est associé à un type de champ. Le type de champ indique le format attendu pour toute valeur de ce champ. Le type de operation que vous pouvez utiliser dans une instruction conditions dépend du type de champ.

Dans conditions de la requête, operation est un opérateur de comparaison qui s'applique à value dans l'instruction. Le mot-clé value fait référence à la valeur de fieldName que vous avez indiquée. La recherche évalue si l'attribut indiqué du type de ressource choisi correspond ou non à value, selon l'opération. Dans une requête, toutes les valeurs de type chaîne ou date/heure doivent être placées entre des guillemets simples (') ou doubles (").

Le tableau suivant décrit les opérations prises en charge pour les requêtes de ressources :

Opération Description Types de champ pris en charge Respect majuscules/minuscules ? Exemple
=

Est égal à, ou correspond exactement dans le cas des chaînes

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

Non

 Si le paramètre value était ' backUp', il serait mis en correspondance avec "backup", "BACKUP", "BackUp", "backUp" ou toute autre variante de casse.
!=

N'est pas égal à

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

Non

 Si value était 'backUp', il serait mis en correspondance avec tout élément différent de "backUp", "backup" ou toute autre variante de casse. Il correspondrait également à tout élément qui ne contient pas les caractères 'backup' dans cet ordre.
==

Strictement égal à

Chaîne

Oui

 Si le paramètre value était ' backUp', il serait uniquement mis en correspondance avec "backUp" et aucune autre variante de casse.
!==

Est strictement différent de

Chaîne

Oui

 Si value était 'backUp', il serait mis en correspondance avec "backup", "BACKup" ou tout autre élément, à l'exception de "backUp", avec cette casse exacte.
=~

Contient

Chaîne

Non

 Si value était 'backUp', il serait mis en correspondance avec tous les éléments égaux à "backup", "BACKUP", "BackUp", "backUp" ou toute autre variante de casse, ou avec ceux contenant ces caractères dans cet ordre, avec d'autres caractères.
>=

Est supérieur ou égal à

Entier, rationnel, date/heure

Non applicable

 Pour une requête dont la condition est size >= 5, tous les résultats ont une valeur supérieure ou égale à 5 dans le champ nommé size.
>

Est supérieur à

Entier, rationnel, date/heure

Non applicable

 Pour une requête dont la condition est size > 5, tous les résultats ont une valeur supérieure à 5 dans le champ nommé size.
<=

Est inférieur ou égal à

Entier, rationnel, date/heure

Non applicable

 Pour une requête dont la condition est size <= 5, tous les résultats ont une valeur inférieure ou égale à 5 dans le champ nommé size.
<

Est inférieur à

Entier, rationnel, date/heure

Non applicable

 Pour une requête dont la condition est size < 5, tous les résultats ont une valeur inférieure à 5 dans le champ nommé size.

Le tableau suivant répertorie 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 indique le format attendu pour un champ donné et le type operation avec lequel vous pouvez l'associer dans une instruction conditions.)

Le tableau n'inclut pas tous les exemples possibles pour un type de champ donné et n'inclut pas non plus des exemples de chaque type de ressource. Pour connaître le format attendu par le service Search pour un attribut de ressource donné, vous pouvez utiliser l'API ou l'interface de ligne de commande pour en savoir plus sur les attributs de ressource. Vous pouvez également consulter la documentation relative à l'API. La documentation d'API inclut une référence pour chaque type de ressource pris en charge qui spécifie les attributs, leurs types de champ ainsi que toute restriction. Pour plus d'informations, reportez-vous à Ressources prises en charge dans Présentation de Search.

Type Exemple d'attributs de ressource
Chaîne Noms d'affichage, états de cycle de vie, domaines de disponibilité, balises, blocs CIDR et URL
Entier Taille ou longueur d'une ressource
Rational Stockage de données disponible
Booléen Si une fonctionnalité est activée ou configurée, si une ressource est en bon état, 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 indexation et réinitialisations de la maintenance planifiée

Regroupement de conditions

En incluant plus d'une instruction de condition dans une requête, vous pouvez affiner les résultats en fonction de plusieurs critères. Vous pouvez regrouper des conditions en utilisant les opérateurs logiques && (esperluettes, pour indiquer l'opérateur logique AND), || (barres verticales pour indiquer l'opérateur logique OR) 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 LICENSE_INCLUDED comme valeur dans le champ nommé licenseModel, une valeur supérieure à 40 pour 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 requête, sauf si vous entonnez un groupe de prédicats entre parenthèses. (Dans le cas contraire, les conditions multiples peuvent uniquement utiliser le même opérateur logique.) Par exemple :

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

Dans l'exemple précédent, tous les résultats renvoyés ont la valeur LICENSE_INCLUDED dans le champ nommé licenseModel et une valeur supérieure à 40 pour 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, tous les résultats renvoyés ont LICENSE_INCLUDED comme valeur dans le champ nommé licenseModel et une valeur supérieure à 40 comme valeur pour le champ nommé dataStoragePercentage ou tout ce qui n'est pas FAILED pour la valeur du 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 requête. 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 renvoyé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 de requête 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 détaillés que l'exemple qui utilise l'opérateur logique IN à la place.

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

Valeurs de date et d'heure

Vous pouvez indiquer des valeurs de date et d'heure à l'aide de l'un des formats de chaîne de modèle 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 juin 2018 16:15:41 +0300', '19 juin 2018 16:15:41'

 EEE est facultatif. MMM peut également être exprimé sous la forme 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 au format UTC. Les caractères 'T' et 'Z' respectent la casse.

Vous devez respecter l'espacement. Interprétez les tirets, les deux-points, les virgules, et les caractères 'T'et 'Z' de manière littérale. Pour interpréter les valeurs d'espace réservé dans le tableau précédent, reportez-vous à la syntaxe de modèle suivante :

Lettre Composant de date ou d'heure Présentation
y

Année

Année
M

Mois de l'année

Mois
d

Jour du mois

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

Les lettres de modèle répétées indiquent leur présentation exacte. Par exemple, 'HH' signifie que vous devez utiliser '00' et non '0' pour indiquer minuit. De même, 'EEE' signifie que vous devez utiliser 'Tue' et non 'Tuesday'. De même, MM requiert l'utilisation de 09 au lieu de 9 pour représenter le mois de septembre.

TimeZone est facultatif mais, dans le format choisi, vous pouvez indiquer TimeZone de l'une des façons suivantes :

  • Nom. Vous pouvez spécifier un fuseau horaire par son nom, par exemple GMT ou PDT. Les valeurs ne respectent pas les majuscules/minuscules.
  • Valeur de décalage GMT. Vous pouvez indiquer un fuseau horaire en fonction de son décalage GMT. Par exemple, GMT-08:00. Les valeurs ne respectent pas les majuscules/minuscules.
  • Fuseau horaire au format ISO 8601. Vous pouvez spécifier un fuseau horaire conformément à la norme ISO 8601. Par exemple, -08, -0800 ou -08:00.

Au lieu d'utiliser l'un des formats précédents, vous pouvez également spécifier une valeur date/heure en tant que constante now. La constante now représente l'heure actuelle au niveau de granularité des secondes dans une minute.

Enfin, vous pouvez ajouter ou soustraire des intervalles de temps aux valeurs de date/d'heure. Par exemple, vous pouvez exécuter une requête pour les ressources créées dans les cinq minutes par rapport à une heure précise. La recherche prend en charge les intervalles de temps suivants :

Lettre Composant de date ou d'heure
s

Secondes
m

Minutes
h

Heures
d Jours
w Semaines

Pour spécifier un intervalle en fonction d'une valeur date-heure, utilisez l'un des formats suivants :

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

Mise en correspondance

Pour la mise en correspondance, au lieu d'utiliser une clause where, ou en plus de celle-ci, avec conditions, vous pouvez utiliser la clause matching. La clause matching contourne la nécessité d'indiquer conditions (qui contient un nom de champ, une opération et une valeur). Une clause matching interroge tous les champs indexés en appliquant l'opérateur = (égal à) avec le texte que vous indiquez. Cependant, elle effectue cette requête sans nécessiter de correspondance exacte. Par exemple, la requête suivante utilise une clause matching pour se comporter de la même manière qu'une recherche de texte libre :

query all resources matching 'instance'

La requête produit des résultats qui correspondent à toutes les ressources et à tous les attributs de ressource contenant 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 requête de ressource est la clause sorted by qui est facultative. La clause sorted by trie les résultats renvoyés par Search en fonction du nom du champ et les répertorie en fonction de la valeur order que vous indiquez. 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 dans l'ordre croissant.

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

  • fieldName : champ utilisé par Search pour trier les résultats. Vous pouvez indiquer n'importe quel champ de n'importe quelle ressource. Les ressources ne contenant pas le champ que vous spécifiez sont répertoriées après les ressources concernées.
  • order : vous pouvez indiquer asc ou desc. Si vous indiquez asc, les résultats sont triés par ordre croissant. Si vous indiquez desc, les résultats sont triés par ordre décroissant.

Interrogation de plusieurs types de ressource

Vous pouvez interroger plusieurs types de ressource à la fois en joignant des requêtes. Chaque requête peut avoir sa propre clause conditionnelle. Si les requêtes que vous souhaitez joindre présentent des conditions "where" différentes, la syntaxe est différente des requêtes portant sur plusieurs types de ressource partageant la même condition "where".

La syntaxe de base d'une requête pour plusieurs types de ressource est la suivante :

query <resourceType>, <resourceType> resources

Par exemple :

query group, user resources

L'exemple de requête précédent renvoie tous les groupes et tous les utilisateurs de la location.

L'exemple suivant présente la syntaxe d'une requête pour plusieurs types de ressource avec des conditions, mais 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'exemple de requête précédent renvoie tous les groupes ayant le nom d'affichage "administrator" et tous les utilisateurs ayant le nom d'affichage "administrator", avec n'importe quelle variante de casse.

Si vous devez appliquer des conditions différentes à un type de ressource, vous devez utiliser un mot-clé union au lieu d'effectuer une séparation par des virgules entre les requêtes jointes. L'exemple suivant présente la syntaxe d'une requête pour plusieurs types de ressource où certains types de ressource partagent des conditions et d'autres non :

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 renvoie tous les groupes ayant le nom d'affichage "administrator" et tous les utilisateurs ayant le nom d'affichage "administrator", avec n'importe quelle variante de casse et toutes les ressources de compartiment.

Ou, par exemple :

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

L'exemple précédent renvoie tous les groupes et tous les compartiments. Il renvoie également tous les utilisateurs portant le nom d'affichage "administrator", avec n'importe quelle variante de casse.

Vous pouvez éventuellement ajouter la clause sorted by à la fin de la requête pour trier tous les résultats dans l'ordre croissant ou décroissant.