Documentazione di Oracle Cloud Infrastructure

Sintassi linguaggio di ricerca

Questo argomento descrive le nozioni di base del linguaggio di query per la ricerca, inclusa una spiegazione della sintassi e delle regole in modo da poter creare query personalizzate. Le query applicano le condizioni di ricerca a tipi di risorse specifici e consentono di ordinare i risultati. Il linguaggio di query offre un controllo più sfumato ed esplicito sui parametri di ricerca, rendendolo particolarmente utile nei casi in cui modifiche precise a una query potrebbero produrre risultati diversi.

Se si desidera eseguire una ricerca tra tutti i tipi di risorsa e gli attributi di risorsa supportati e non sono necessari i risultati di ricerca ordinati oppure se si preferisce utilizzare l'interfaccia della console per specificare i parametri di ricerca, non è necessario creare una query. È invece possibile cercare una corrispondenza parziale o esatta del testo in formato libero senza applicare la sintassi del linguaggio di query alla ricerca.

Quando si è pronti per eseguire una query, vedere Esecuzione di query sulle risorse per istruzioni.

Funzioni base query

Gli esempi seguenti mostrano la sintassi di base di una query.

Per eseguire una query per le risorse che soddisfano una o più condizioni descritte da un'istruzione di condizione che utilizza operatori di confronto, effettuare le operazioni riportate di seguito.

query <resourceType> resources where <conditions>

Per eseguire una query per le risorse che soddisfano una o più condizioni e per includere nei risultati gli attributi delle risorse ordinate:

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

In alternativa, per eseguire una query per le risorse con qualsiasi attributo con un valore corrispondente a quanto specificato:

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

La ricerca ignora lo spazio vuoto, l'indentazione e le interruzioni di riga. Le query di esempio includono l'indentazione per migliorare la leggibilità. Per dimostrare solo la sintassi, le parentesi angolari (<>) e il testo in corsivo indicano variabili che possono essere costituite da una o più parole chiave.

In una query, le clausole includono quanto riportato di seguito.

  • query: (Obbligatorio) seleziona le risorse da restituire in base alle clausole successive. Le istruzioni di query iniziano sempre con la parola query.
  • return: specifica gli attributi risorsa da includere nella vista espansa o avanzata dei risultati della ricerca. Per ulteriori informazioni, vedere Attributi restituzione.
  • where: abbina le risorse all'conditions specificato. Per ulteriori informazioni, vedere Condizioni.
  • matching: abbina le risorse al testo specificato indipendentemente dal fatto che il testo corrisponda esattamente, corrisponda al tipo di risorsa o venga visualizzato in un attributo di risorsa indicizzato. Per ulteriori informazioni, vedere Corrispondenza.
  • sorted by: ordina le risorse secondo fieldName nell'ordine specificato da order. Senza questa clausola, Search elenca i risultati per data di creazione in ordine decrescente, con le risorse più recenti elencate per prime. Per ulteriori informazioni, vedere Ordinamento.

Le clausole sono facoltative se non diversamente indicato. Per la corrispondenza, è possibile utilizzare la clausola where e la clausola matching separatamente o insieme.

Nella clausola query specificare le seguenti informazioni:

  • resourceType - (Obbligatorio) Specifica il tipo di risorsa a cui si applicano le clausole successive quando si esegue la query. È possibile specificare il nome del tipo di risorsa (ad esempio, database o group) o all. Se si specifica all, la ricerca cerca le corrispondenze con il valore conditions specificato in tutti i tipi di risorsa. È possibile eseguire query per singoli tipi di risorsa, ma non per tipi di famiglia. Per un elenco dei tipi di risorsa supportati, vedere la sezione Risorse supportate della panoramica della ricerca.
  • resources - (Obbligatorio) Specifica che il testo che si sta sottomettendo è una query di risorsa.

Attributi restituito

Per gli utenti dell'SDK o dell'interfaccia CLI, la clausola return indica gli attributi estesi delle risorse che si desidera visualizzare inclusi nei risultati della ricerca restituiti dalla query. È possibile utilizzare la clausola return per forzare la restituzione di attributi di risorsa specifici o di tutti gli attributi di risorsa nei risultati della ricerca, fornendo ulteriori dettagli su ciascuna risorsa.

Per impostazione predefinita, nei risultati della ricerca viene visualizzato un set limitato e comune di attributi risorsa per qualsiasi risorsa corrispondente. Nella console, questi attributi risorsa includono il nome visualizzato, il tipo di risorsa, l'OCID, il compartimento, lo stato del ciclo di vita e l'ora di creazione. Nell'SDK o nell'interfaccia CLI, i risultati della ricerca delle risorse di base includono anche il dominio di disponibilità e le eventuali tag associate alla risorsa. Quando una query trova una corrispondenza al di fuori degli attributi di risorsa comuni, i risultati di ricerca espansi includono ed evidenziano gli attributi specifici corrispondenti insieme ai risultati di base. Con la clausola return, è possibile ottenere ulteriori dettagli sulla corrispondenza dei risultati della ricerca anche se la query non genera altrimenti una corrispondenza negli attributi della risorsa che si desidera visualizzare.

In una query, la clausola return è costituita dai seguenti elementi:

return <fieldName>

La parola chiave fieldName identifica un attributo di una risorsa. Ad esempio, quando il tipo di risorsa oggetto della query è un'istanza, specificando shape si desidera visualizzare la forma di tutte le istanze corrispondenti. Solo nel caso di istanze, fieldName può identificare un attributo di una risorsa correlata, ad esempio l'indirizzo IP privato nel collegamento VNIC di un'istanza. La specifica di attachedVnic.privateIp indica che si desidera visualizzare l'indirizzo IP privato del collegamento tra una VNIC e un'istanza.

I dettagli aggiuntivi disponibili per una determinata risorsa dipendono dagli attributi della risorsa indicizzati per il tipo di risorsa. Per trovare i nomi di tutti gli attributi delle risorse indicizzate per un tipo di risorsa, utilizzare l'SDK o l'interfaccia CLI per eseguire una query che include la clausola return, ma invece di specificare il nome del campo, specificare che si desidera visualizzare allAdditionalFields. Ad esempio:

query instance resources return allAdditionalFields

Questa query produce una risposta che mostra tutti gli attributi delle risorse indicizzate per il tipo di risorsa istanza. Nella console non è possibile visualizzare questi altri campi, ad eccezione delle risorse dell'istanza quando si applica il filtro del tipo di risorsa, motivo per cui è necessario utilizzare l'SDK o l'interfaccia CLI per recuperare le informazioni. Nei risultati della ricerca, i dettagli aggiuntivi disponibili (e la struttura di tali informazioni) dipendono dal tipo di risorsa corrispondente. Inoltre, è necessario disporre dell'autorizzazione necessaria per visualizzare gli attributi della risorsa richiesti con la query.

È possibile combinare la clausola return con la clausola where per ottenere risultati con dettagli specifici applicando allo stesso tempo una o più condizioni. Ad esempio:
query instance resources return allAdditionalFields where assignedEntityType = 'PRIVATE_IP'

Questa query produce una risposta che mostra tutti gli attributi delle risorse indicizzate per tutte le risorse dell'istanza con un campo assignedEntityType con un valore PRIVATE_IP.

Limitazioni

È possibile utilizzare la clausola return solo per un tipo di risorsa alla volta. La query non può specificare più tipi di risorsa se si include la clausola return. Se si desidera, tuttavia, è possibile specificare più campi da restituire per un determinato tipo di risorsa.

Non è possibile includere nella stessa query sia la parola chiave allAdditionalFields che i singoli nomi di campo. È possibile specificare la parola chiave allAdditionalFields oppure specificare uno o più nomi di campo singoli separati da virgole.

Condizioni

La clausola where applica conditions che filtra i risultati restituiti dalla ricerca. È possibile specificare una o più istruzioni di condizione. Per ulteriori informazioni su più condizioni, vedere Condizioni di raggruppamento.

In una query, conditions è costituito dai seguenti elementi:

<fieldName> <operation> <value>

La parola chiave fieldName è l'attributo risorsa in base al quale vengono valutati il valore operation e il valore value scelto per tale attributo. Ogni campo è associato a un tipo di campo. Il tipo di campo indica il formato previsto per qualsiasi valore in tale campo. Il tipo di operation che è possibile utilizzare in un'istruzione conditions dipende dal tipo di campo.

Nella query conditions, un operation è un operatore di confronto che si applica al value nell'istruzione. La parola chiave value fa riferimento al valore di fieldName specificato. La ricerca valuta se l'attributo specificato del tipo di risorsa scelto corrisponde o non corrisponde a value, in base all'operazione. In una query è necessario racchiudere qualsiasi valore stringa o data/ora tra aprendo e chiudendo virgolette semplici (ˈ) o virgolette doppie (").

Nella tabella riportata di seguito vengono descritte le operazioni supportate per le query delle risorse.

Operazione descrizione; Tipi di campo supportati Con distinzione tra casi? Esempio
=

Uguale o corrispondenza esatta per le stringhe

Stringa, intero, razionale, booleano, data/ora

No

 Se value fosse ˈbackUpˈ, corrisponderebbe a "BACKUP", "BACKUP", "BackUp", "backUp" o a qualsiasi altra variazione nell'involucro.
!=

È diverso da

Stringa, intero, razionale, booleano, data/ora

No

 Se value fosse ˈbackUpˈ, corrisponderebbe a qualsiasi elemento che non sia uguale a "backUp", "backup" o a qualsiasi altra variazione nell'involucro. Corrisponderebbe anche a qualsiasi cosa che non contenga i caratteri 'backup' in quell'ordine.
==

Rigorosamente uguale a

Stringa

Sì

 Se value fosse ˈbackUpˈ, corrisponderebbe solo a "backUp" e nessun'altra variazione nell'involucro.
!==

Rigorosamente non uguale a

Stringa

Sì

 Se il valore value fosse ˈbackUpˈ, corrisponderebbe a "backup", "BACKup" o a qualsiasi elemento tranne "backUp", con tale involucro esatto.
=~

Contiene

Stringa

No

 Se value fosse ˈbackUpˈ, corrisponderebbe a qualsiasi elemento che sia uguale a "BACKUP", "BACKUP", "BackUp", "backUp" o a qualsiasi altra variazione nell'involucro o che contenga tali caratteri in tale ordine, insieme ad altri caratteri.
>=

Maggiore o uguale a

Numero intero, razionale, data/ora

Non applicabile

 Per una query in cui la condizione è size >= 5, tutti i risultati hanno un valore uguale o superiore a 5 nel campo denominato size.
>

Maggiore di

Numero intero, razionale, data/ora

Non applicabile

 Per una query in cui la condizione è size > 5, tutti i risultati hanno un valore maggiore di 5 nel campo denominato dimensione.
<=

minore o uguale a

Numero intero, razionale, data/ora

Non applicabile

 Per una query in cui la condizione è size <= 5, tutti i risultati hanno un valore minore o uguale a 5 nel campo denominato size.
<

Meno di

Numero intero, razionale, data/ora

Non applicabile

 Per una query in cui la condizione è size < 5, tutti i risultati hanno un valore minore o uguale a 5 nel campo denominato size.

Nella tabella seguente sono elencati alcuni esempi di attributi risorsa appartenenti a ciascuna categoria di tipi di campo supportati. Come descritto in precedenza, il tipo di campo indica il formato previsto per un determinato campo e il tipo di operation a cui è possibile associarlo in un'istruzione conditions.

La tabella non include tutti gli esempi possibili per un determinato tipo di campo né include esempi di ogni tipo di risorsa. Se si desidera conoscere il formato previsto dal servizio di ricerca per un attributo di risorsa specifico, è possibile utilizzare l'interfaccia della riga di comando o l'API per ulteriori informazioni sugli attributi di risorsa. È inoltre possibile consultare la documentazione dell'API. La documentazione API include un riferimento per ogni tipo di risorsa supportato che specifica gli attributi, i relativi tipi di campo ed eventuali limitazioni. Per ulteriori informazioni, vedere la sezione Risorse supportate della panoramica della ricerca.

Digitare Attributi risorsa di esempio
Stringa Visualizza nomi, stati del ciclo di vita, domini di disponibilità, tag, blocchi CIDR e URL
Numero intero Dimensione o lunghezza di una risorsa
Razionale Storage dati disponibile
Valore booleano Indica se una funzione è abilitata o configurata, se una risorsa è in buono stato, se una risorsa è pubblica o privata, se un elemento è la versione più recente e se è consentito
Data/ora Date di creazione, date dell'ultimo aggiornamento, date dell'ultima indicizzazione e riavvii della manutenzione pianificata

Raggruppamento di condizioni

Includendo più di un'istruzione di condizione in una query, è possibile perfezionare i risultati in base a diversi criteri. È possibile raggruppare le condizioni utilizzando gli operatori logici && (e commerciale, per indicare un AND logico), || (barre verticali, per indicare un OR logico) o l'operatore IN logico. Ad esempio:

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

Nell'esempio precedente, tutti i risultati hanno LICENSE_INCLUDED come valore nel campo denominato licenseModel, un valore maggiore di 40 per il campo denominato dataStoragePercentage e un valore nel campo lifecycleState diverso da FAILED.

Impossibile combinare due operatori logici diversi nella stessa query a meno che non si racchiudano parentesi attorno a un gruppo di predicati. In caso contrario, più condizioni possono utilizzare solo lo stesso operatore logico. Ad esempio:

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

Nell'esempio precedente, tutti i risultati restituiti hanno LICENSE_INCLUDED come valore nel campo denominato licenseModel e un valore maggiore di 40 per il campo denominato dataStoragePercentage oppure il valore del relativo campo lifecycleState è diverso da FAILED.

È accettabile anche il seguente gruppo:

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

Nell'esempio precedente, tutti i risultati restituiti hanno LICENSE_INCLUDED come valore nel campo denominato licenseModel e un valore maggiore di 40 come valore per il campo denominato dataStoragePercentage o qualsiasi altro valore diverso da FAILED per il valore del campo denominato lifecycleState.

Per applicare più condizioni in cui ogni condizione accetta più valori possibili, l'uso di un operatore IN logico può semplificare una query. Ad esempio, è possibile utilizzare le seguenti condizioni:
licenseModel IN ('LICENSE_INCLUDED', 'BRING_YOUR_OWN_LICENSE') && dbWorkload IN ('OLTP', 'DW', 'AJD', 'APEX')
Nell'esempio precedente, tutti i risultati restituiti hanno LICENSE_INCLUDED o BRING_YOUR_OWN_LICENSE come valore nel campo denominato licenseModel e un valore di OLTP, DW, AJD o APEX come valore nel campo denominato dbWorkload. L'esempio precedente può sostituire condizioni di query più complesse, come quelle riportate di seguito.
(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')
O anche quanto segue:
((licenseModel = 'LICENSE_INCLUDED' || licenseModel = 'BRING_YOUR_OWN_LICENSE') && (dbWorkload = 'OLTP' || dbWorkload = 'DW' || dbWorkload = 'AJD' || dbWorkload = 'APEX'))

Entrambi questi esempi utilizzano l'operatore OR logico per esprimere efficacemente le stesse condizioni in termini più verbosi rispetto all'esempio che utilizza invece l'operatore IN logico.

La ricerca non esegue una valutazione da sinistra a destra per ridurre l'ambiguità o chiarire l'intento.

Valori data e ora

È possibile specificare valori di data e ora utilizzando uno dei seguenti formati di stringa di pattern:

Formato Esempi commenti
<yyyy>-<MM>-<dd> <HH>:<mm>:<ss> <TimeZone>

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

 TimeZone è facoltativo. Se TimeZone viene omesso, viene utilizzato UTC.
<EEE>, <d> <MMM> <yyyy> <HH>:<mm>:<ss> <TimeZone>

"Mar 19 giu 2018 16:15:41 +0300", "19 giugno 2018 16:15:41"

 EEE è facoltativo. MMM può anche essere espresso come MMMM. TimeZone è anche facoltativo. Se TimeZone viene omesso, viene utilizzato UTC.
<yyyy>-<MM>-<dd>T<HH>:<mm>:<ss>Z

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

Tempo in ora UTC. 'T' e 'Z' fanno distinzione tra maiuscole e minuscole.

È necessario osservare la spaziatura. Interpretare trattini, due punti, virgole e i caratteri 'T' e 'Z' letteralmente. Per interpretare i valori segnaposto nella tabella precedente, vedere la seguente sintassi del pattern:

Letter Componente di data o ora Presentazione
y

Anno

Anno
M

Mese dell'anno

mese
d

Giorno del mese

Giorno
H Ora nel giorno (da 00-23) Numerico
m Minuto dell'ora Numerico
s Secondi in minuti Numerico
E Giorno della settimana Testo

Le lettere ripetute indicano la loro esatta presentazione. Ad esempio, 'HH' significa che è necessario utilizzare '00' e non '0' per rappresentare la mezzanotte. Allo stesso modo, "EEE" significa "Mar" e non "Martedì". Allo stesso modo, 'MM' richiede '09' invece di '9' per rappresentare il mese di settembre.

TimeZone è facoltativo, ma nel formato scelto è possibile specificare TimeZone in uno dei seguenti modi:

  • Nome: È possibile specificare un fuso orario in base al nome, ad esempio GMT o PDT. I valori non fanno distinzione tra casi.
  • Valore offset GMT. È possibile specificare un fuso orario in base al relativo offset GMT. ad esempio GMT-08:00. I valori non fanno distinzione tra casi.
  • Fuso orario ISO 8601. È possibile specificare un fuso orario in base agli standard ISO 8601. Ad esempio, -08, -0800, o -08:00.

Anziché utilizzare uno dei formati precedenti, è inoltre possibile specificare un valore data/ora come costante now. La costante now rappresenta l'ora corrente fino al livello di granularità dei secondi in un minuto.

Infine, è possibile aggiungere o sottrarre intervalli di tempo da qualsiasi valore di data e ora. Ad esempio, è possibile eseguire una query per le risorse create entro cinque minuti da un'ora specifica. La ricerca supporta i seguenti intervalli di tempo:

Letter Componente di data o ora
s

secondi
m

minuti
h

Ore
d Giorni
w settimane

Per specificare un intervallo di tempo in relazione a un valore data/ora, utilizzare uno dei seguenti formati:

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

Corrispondente a

Ai fini della corrispondenza, anziché utilizzare o in aggiunta all'utilizzo di una clausola where con conditions, è possibile utilizzare la clausola matching. La clausola matching elimina la necessità di specificare conditions (che contiene un nome di campo, un'operazione e un valore). Una clausola matching esegue effettivamente una query su tutti i campi indicizzati applicando l'operatore = (uguale a) insieme al testo specificato. Tuttavia, lo fa senza richiedere una corrispondenza esatta. Ad esempio, la query seguente utilizza una clausola matching per funzionare allo stesso modo di una ricerca di testo libero:

query all resources matching 'instance'

La query produce risultati che corrispondono a tutte le risorse e agli attributi delle risorse contenenti la parola "istanza".

La clausola matching esegue una query su tutti i campi indicizzati per individuare le corrispondenze, ma ignora i caratteri speciali, inclusa qualsiasi punteggiatura.

Ordinamento

L'ultima clausola di una query di risorsa è la clausola sorted by ed è facoltativa. La clausola sorted by ordina i risultati restituiti da Search in base al nome del campo e li elenca in base al order specificato. Per impostazione predefinita, se non si specifica il criterio di ordinamento, i risultati vengono sempre ordinati in base alla data e all'ora create in ordine decrescente.

Nella clausola sorted by è possibile specificare:

  • fieldName: il campo utilizzato dalla ricerca per ordinare i risultati. È possibile specificare qualsiasi campo di qualsiasi risorsa. Le risorse che non contengono il campo specificato vengono elencate dopo le risorse che lo fanno.
  • order: è possibile specificare asc o desc. Se si specifica asc, i risultati vengono elencati in ordine crescente. Se si specifica desc, i risultati vengono visualizzati in ordine decrescente.

Query su più tipi di risorse

È possibile eseguire query su più tipi di risorsa alla volta partecipando alle query. Ogni query può avere una propria clausola condizionale. Se le query a cui si desidera partecipare hanno condizioni "where" diverse, la sintassi è diversa da quella delle query per diversi tipi di risorse che condividono la stessa condizione "where".

La sintassi di base per una query per più tipi di risorsa è la seguente:

query <resourceType>, <resourceType> resources

Ad esempio:

query group, user resources

La query di esempio precedente restituisce tutti i gruppi e tutti gli utenti nella tenancy.

Di seguito viene illustrata la sintassi di una query per diversi tipi di risorsa con condizioni, ma in cui le condizioni sono uguali per tutti i tipi di risorsa.

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

Ad esempio:

query group, user resources where displayName = 'administrator'

La query di esempio precedente restituisce tutti i gruppi con il nome visualizzato "amministratore" e tutti gli utenti con il nome visualizzato "amministratore", con qualsiasi variazione nell'involucro.

Se è necessario applicare condizioni diverse a qualsiasi tipo di risorsa, è necessario utilizzare una parola chiave union anziché una separazione di virgole tra le query unite. Di seguito viene illustrata la sintassi di una query per diversi tipi di risorsa in cui alcuni tipi di risorsa condividono le condizioni, mentre altri no.

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

Ad esempio:

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

L'esempio precedente restituisce tutti i gruppi con il nome visualizzato "administrator" e tutti gli utenti con il nome visualizzato "administrator", con qualsiasi variazione nell'involucro e tutte le risorse del compartimento.

Oppure, ad esempio:

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

L'esempio precedente restituisce tutti i gruppi e tutti i compartimenti. Restituisce anche tutti gli utenti con il nome visualizzato "amministratore", con qualsiasi variazione di involucro.

Facoltativamente, è possibile aggiungere la clausola sorted by alla fine della query per ordinare tutti i risultati in ordine crescente o decrescente.