Documentazione dell'infrastruttura Oracle Cloud

Parametri query

È possibile includere parametri di query nelle richieste all'API REST dei domini di Identity. Questi parametri sono utili per trovare risorse con attributi o valori di attributo specifici e per ordinare e impaginare l'output.

Informazioni sui parametri di query

Utilizzando una query, è possibile filtrare l'output per:

Nota

Le funzionalità di filtro delle query dipendono dal servizio REST. I servizi REST senza SCIM potrebbero non supportare il filtro avanzato e i parametri che si desidera utilizzare.

  • Elenca solo le risorse contenenti attributi specificati o con valori specificati per gli attributi.

  • Limitare gli attributi restituiti nel corpo della risposta.

  • Ordinare l'output in base a un attributo specificato, in ordine crescente o decrescente.

  • Limitare il numero di risorse restituite.

  • Specificare dove, nell'elenco delle risorse della raccolta, avviare la richiesta.

I parametri di query vengono in genere utilizzati con i metodi di ricerca riportati di seguito.

Parametri query con GET

Quando si esegue una ricerca utilizzando una richiesta GET su un endpoint di risorsa, ad esempio /Users o /Groups, la query viene inserita nell'URL. Aggiungere un punto interrogativo (?) all'URL, seguito dalla query.
Nota

I caratteri di un URL esterno al set di caratteri ASCII, ad esempio spazi e virgolette, devono essere codificati tramite URL. Vengono forniti esempi con caratteri codificati per l'URL. Il segno + sostituisce gli spazi e il simbolo %22 sostituisce il simbolo (").
https://<domainURL>/admin/v1/Users?attributes=email&filter=userName+co+%22jensen%22

Per trovare tutti i gruppi e AppRoles associati a un utente specifico, effettuare le operazioni riportate di seguito.

https://<domainURL>/admin/v1/Users/1e895413c68d42c7bc006d0033794c1e?attributes=groups,urn:ietf:params:scim:schemas:oracle:idcs:extension:user:User:appRoles

Parametri query con un corpo richiesta POST /.search

È possibile creare ricerche con una richiesta POST su un endpoint della risorsa che termina con /.search. In tal caso, la query viene inserita nel corpo della richiesta. Quando si cercano informazioni sensibili, come i nomi utente, in cui le informazioni sensibili vengono inviate insieme ad altri dati, utilizzare questo metodo (per motivi di sicurezza).

Questo esempio mostra il corpo della richiesta di un metodo POST eseguito sull'endpoint /Users/.search. Restituisce le prime 10 voci utente con displayName che iniziano con smith e meta.resourceType uguali a User. 
{ 
"schemas":["urn:ietf:params:scim:api:messages:2.0:SearchRequest"], 
"attributes": ["displayName","userName"], 
"filter": "(displayName sw \"smith\")", "startIndex": 1, "count": 10
}

Il parametro attributes può essere utilizzato con tutti i metodi ad eccezione di DELETE. Gli altri parametri di query sono significativi solo per i metodi di ricerca e vengono ignorati da altri metodi.

Parametro query HTTP Descrizione
attributes=attribute1,attribute2

Specifica una lista multivalore di stringhe che indicano i nomi degli attributi risorsa da restituire nella risposta. Questo parametro di query accetta anche l'ID schema estensione come nome attributo valido. L'inclusione dell'ID dello schema di estensione negli attributi restituisce tutti gli attributi predefiniti al suo interno.
attributeSets La ricerca restituisce un gruppo di attributi nella risposta anziché specificare singolarmente ogni attributo. Questo parametro di query accetta valori separati da virgole dai seguenti parametri:

  • all (restituisce tutti gli attributi)

  • Sempre (restituisce tutti gli attributi contrassegnati come sempre nello schema)

  • predefinito (restituisce tutti gli attributi predefiniti)

  • richiesta (restituisce tutti gli attributi contrassegnati come richiesta nello schema)

Questi valori non fanno distinzione tra maiuscole e minuscole. Se nella richiesta sono specificati sia attributes che attributeSets, i valori di entrambi vengono restituiti nella risposta.
count=N Indica il numero massimo di risultati di ricerca per pagina. Specificare un numero non negativo per recuperare una risposta. Per impostazione predefinita, un numero negativo è 50 e restituisce le prime 50 risorse.
startIndex=N Specifica l'indice della pagina iniziale. Indice basato su 1 del primo risultato della query. Un valore inferiore a 1 viene interpretato come 1.
filter=Expression La ricerca restituisce tutte le risorse nell'endpoint specificato per le quali l'espressione è vera. Per ulteriori informazioni, vedere Utilizzo del parametro Query filtro.
sortBy=attribute Fornisce il nome dell'attributo in base al quale deve essere ordinata la risposta.
sortOrder=ascending | sortOrder=descending Specifica l'ordine di applicazione del parametro sortBy. Se si specifica un valore per sortBy e non si specifica un valore per sortOrder, il valore predefinito per sortOrder è ascending.

Uso del parametro di query filtro

È possibile utilizzare la query filter nelle ricerche eseguite con il metodo GET. Il formato di una query di filtro è: 

filter=Expression

Un filtro deve contenere almeno un'espressione valida. Ogni espressione contiene un nome di attributo seguito da un operatore di attributo e un valore facoltativo. Gli attributi ricercabili variano da una risorsa all'altra. Questi argomenti vengono discussi negli argomenti di tali richieste GET.

L'URL seguente include una query di filtro per gli utenti con l'attributo userName contenente jensen:

Nota

I caratteri di un URL esterno al set di caratteri ASCII, ad esempio spazi e virgolette, devono essere codificati tramite URL. Vengono forniti esempi con caratteri codificati per l'URL. Il segno + sostituisce gli spazi e il simbolo %22 sostituisce il simbolo (").
https://<domainURL>/admin/v1/Users?filter=userName+co+%22jensen%22
Operatore attributo Descrizione Funzionamento
eq Uguale I valori di attributo e operatore devono essere identici per una corrispondenza.
ne Diverso da I valori di attributo e operatore non sono identici.
co Contiene L'intero valore dell'operatore deve essere una sottostringa del valore di attributo per una corrispondenza.
sw Inizia con L'intero valore dell'operatore deve essere una sottostringa del valore dell'attributo a partire dall'inizio del valore dell'attributo. Questo criterio è soddisfatto se le due stringhe sono identiche.
ew Termina con L'intero valore dell'operatore deve essere una sottostringa del valore di attributo corrispondente alla fine del valore di attributo. Questo criterio è soddisfatto se le due stringhe sono identiche.
pr Presente (con valore) Se l'attributo ha un valore non vuoto o se contiene un nodo non vuoto per attributi complessi, esiste una corrispondenza.
gt Maggiore di Se il valore dell'attributo è maggiore del valore dell'operatore, viene trovata una corrispondenza. Il confronto effettivo dipende dal tipo di attributo. Per i tipi di attributo stringa, si tratta di un confronto lessicografico e per i tipi DateTime si tratta di un confronto cronologico.
ge Maggiore o uguale a Se il valore dell'attributo è maggiore o uguale al valore dell'operatore, viene trovata una corrispondenza. Il confronto effettivo dipende dal tipo di attributo. Per i tipi di attributo stringa, si tratta di un confronto lessicografico e per i tipi DateTime si tratta di un confronto cronologico.
lt Minore di Se il valore dell'attributo è inferiore al valore dell'operatore, viene trovata una corrispondenza. Il confronto effettivo dipende dal tipo di attributo. Per i tipi di attributo stringa, si tratta di un confronto lessicografico e per i tipi DateTime si tratta di un confronto cronologico.
le Minore o uguale a Se il valore dell'attributo è minore o uguale al valore dell'operatore, viene trovata una corrispondenza. Il confronto effettivo dipende dal tipo di attributo. Per i tipi di attributo stringa, si tratta di un confronto lessicografico e per i tipi DateTime si tratta di un confronto cronologico.

È possibile combinare più espressioni utilizzando gli operatori logici and e or e negare un'espressione precedendola con l'operatore attributo not. Utilizzare le parentesi () per il raggruppamento delle priorità e le parentesi quadre [] per il raggruppamento di filtri di attributi complessi.

Esempi di filtro dei parametri di query

Utilizzare gli esempi dei parametri di query riportati di seguito come punto di partenza per le query in un dominio di Identity.

Nota

I caratteri di un URL esterno al set di caratteri ASCII, ad esempio spazi e virgolette, devono essere codificati tramite URL. Vengono forniti esempi con caratteri codificati per l'URL. Il segno + sostituisce gli spazi e il simbolo %22 sostituisce il simbolo (").

Esempi utente

Per cercare gli utenti con l'attributo userName uguale a example, utilizzare questo filtro:

https://<domainURL>/admin/v1/Users?filter=userName+eq+%22example%22

In questo esempio di filtro viene eseguita la ricerca di un utente con userName contenente jensen:

https://<domainURL>/admin/v1/Users?filter=userName+co+%22jensen%22

Questo esempio di filtro cerca un utente con userName che contiene example o che inizia con my:

https://<domainURL>/admin/v1/Users?filter=userName+co+%22example%22+or+userName+sw+%22my%22

In questo esempio di filtro viene eseguita la ricerca di un utente con l'attributo secondario familyName name che contiene jensen:

https://<domainURL>/admin/v1/Users?filter=name.familyName+co+%22jensen%22

Questo esempio di query URL complessa restituisce tutti gli utenti con un valore userName uguale a example, elenca gli attributi emails.value e name.familyName nel corpo della risposta JSON e restituisce un massimo di otto utenti per pagina di output.

https://<domainURL>/admin/v1/Users?filter=userName+eq+%22example%22&attributes=emails.value,name.familyName&count=8

Questo esempio di filtro consente di cercare gli utenti utilizzando il parametro di filtro in GET.

https://<domainURL>/admin/v1/Users/?filter=phoneNumbers.value co "415"

Questo esempio di filtro restituisce gli utenti che dispongono dell'attributo personalizzato ricercabile Nickname. Per ulteriori informazioni sugli attributi personalizzati ricercabili, vedere Personalizzazione degli schemi utente e Personalizzazione degli schemi.

GET https://<domainURL>/admin/v1/Users?filter=(urn:ietf:params:scim:schemas:idcs:extension:custom:User:Nickname pr)

Questo esempio di filtro restituisce gli utenti il cui attributo personalizzato ricercabile corrisponde a una stringa di testo. Per ulteriori informazioni sugli attributi personalizzati ricercabili, vedere Personalizzazione degli schemi utente e Personalizzazione degli schemi.

GET https://<domainURL>/admin/v1/Users?filter=(urn:ietf:params:scim:schemas:idcs:extension:custom:User:Nickname eq "aabbccc")

Esempi di numeri di telefono

Questo esempio di filtro cerca gli utenti il cui numero di telefono inizia con "+1"*.
Nota

Funziona solo con operazioni POST.


POST https://<domainURL>/admin/v1/Users/.search
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:SearchRequest"],
"filter": "phoneNumbers.value sw \"+1\""
}

Questo esempio di filtro cerca gli utenti che il numero di telefono abitazione contiene la stringa "503".


POST https://<domainURL>/admin/v1/Users/.search
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:SearchRequest"],  
"filter": "phoneNumbers[type eq \"home\"].value co \"503\""
}

Oppure 


POST https://<domainURL>/admin/v1/Users/.search
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:SearchRequest"], 
"filter": "phoneNumbers[type eq \"home\" and value co \"503\"]"
}
Questo esempio di filtro consente di cercare gli utenti con variazioni dei numeri di telefono.
Nota

Il parametro di filtro SCIM non supporta i pattern RegEx. Devi aver incluso tutte le possibili variazioni. Utilizzare l'esempio seguente per iniziare.


POST https://<domainURL>/admin/v1/Users/.search 
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:SearchRequest"],
"phoneNumbers.value eq \"+1 9xxxx xxxxx\" or phoneNumbers.value eq \"+19xxxx xxxxx\" or phoneNUmbers.value eq \"+19xxxxxxxxx\""
}

Esempi di ruoli applicazione

In questo esempio di filtro vengono cercati tutti gli utenti che dispongono di un AppRole specifico:

https://<domainURL>/admin/v1/Users?filter=urn:ietf:params:scim:schemas:oracle:idcs:extension:user:User:approles.value+eq+<idOfAppRole>

Questo esempio di filtro restituisce i membri di AppRole utilizzando approleid.


GET https://<domainURL>/admin/v1/AppRoles/{{approleid}}?attributes=members

Questo esempio di filtro restituisce AppRoles per un'applicazione specifica utilizzando appid.


GET https://<domainURL>/admin/v1/AppRoles?filter=app.value eq "{{appid}}"