Parametri della 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 in modo da:

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 gli attributi specificati o con i 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.
Limita il numero di risorse restituite.
Specificare dove, nella lista di risorse della raccolta, avviare la richiesta.

I parametri di query vengono in genere utilizzati con i metodi di ricerca:

GET: per filtrare i risultati della ricerca. Vedere Parametri query con GET.
POST: per filtrare i risultati della ricerca utilizzando i parametri nel corpo della richiesta (per motivi di sicurezza). Vedere Parametri di query con un corpo di richiesta POST/.search.

Parametri di 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 che si trovano al di fuori del set di caratteri ASCII, ad esempio spazi e virgolette, devono essere codificati mediante URL. Esempi sono forniti con caratteri con codifica URL. Il segno + sostituisce gli spazi e il segno %22 sostituisce le virgolette (").

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 di query con un corpo di richiesta POST/.search

È possibile creare ricerche con una richiesta POST su un endpoint di risorsa che termina con /.search. In questo caso, inserire la query nel corpo della richiesta. Quando si cercano informazioni riservate, come i nomi utente, in cui le informazioni riservate 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 uguale 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 tranne 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 di stringhe multivalore che indica i nomi degli attributi risorsa da restituire nella risposta. Questo parametro di query accetta anche l'ID dello schema di estensione come nome di 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 ogni attributo singolarmente. 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) default (restituisce tutti gli attributi predefiniti) richiesta (restituisce tutti gli attributi contrassegnati come richiesta nello schema) Questi valori non fanno riferimento a casi. Se nella richiesta sono specificati sia `attributes` che `attributeSets`, nella risposta vengono restituiti i valori di entrambi.
`count=N`	Indica il numero massimo di risultati della 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. Questo è l'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 cui 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 `sortOrder`, il valore predefinito di `sortOrder` sarà `ascending.`

Utilizzo del parametro di query di 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 sono discussi negli argomenti per tali richieste GET.

Il seguente URL include una query di filtro per gli utenti con l'attributo userName che contiene jensen:

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`	Diversi	I valori di attributo e operatore non sono identici.
`co`	Contiene	L'intero valore dell'operatore deve essere una sottostringa del valore dell'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`	Finisce con	L'intero valore dell'operatore deve essere una sottostringa del valore dell'attributo, corrispondente alla fine del valore dell'attributo. Questo criterio è soddisfatto se le due stringhe sono identiche.
`pr`	Presente (ha valore)	Se l'attributo ha un valore non vuoto o contiene un nodo non vuoto per gli attributi complessi, viene trovata 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`	Meno di	Se il valore dell'attributo è minore 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.
`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 di parametri di query riportati di seguito come punto di partenza per le query in un dominio di Identity.

Esempi di utenti

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

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

Questo esempio di filtro cerca un utente con un userName contenente jensen:

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

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

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

Questo esempio di filtro cerca un utente con l'attributo secondario familyName di name che contiene jensen:

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

Questo esempio di query URL complesso 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

In questo esempio di filtro vengono cercati gli utenti che utilizzano 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\""
}

In questo esempio di filtro vengono cercati gli utenti il cui 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 cerca gli utenti con variazioni di numero di telefono.

Nota

Il parametro di filtro SCIM non supporta i pattern RegEx. Devi aver incluso tutte le possibili varianti. Per iniziare, utilizzare l'esempio seguente.


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 ruolo 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 del file AppRole utilizzando approleid.


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

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


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

Documentazione di Oracle Cloud Infrastructure