Paramètres d'interrogation

Vous pouvez inclure des paramètres d'interrogation dans les demandes à l'API REST des domaines d'identité. Ces paramètres sont utiles pour rechercher des ressources avec des attributs ou des valeurs d'attribut spécifiques, ainsi que pour trier et paginer la sortie.

À propos des paramètres d'interrogation

À l'aide d'une interrogation, vous pouvez filtrer la sortie pour :

Note

Les fonctions de filtrage des interrogations dépendent du service REST. Les services REST sans SCIM peuvent ne pas prendre en charge le filtrage avancé et les paramètres à utiliser.

Lister uniquement les ressources contenant les attributs spécifiés ou ayant des valeurs spécifiées pour les attributs.
Limiter les attributs retournés dans le corps de la réponse.
Trier la sortie sur un attribut spécifié, par ordre croissant ou décroissant.
Limiter le nombre de ressources retournées.
Indiquez où, dans la liste des ressources de la collection, lancer la demande.

Les paramètres d'interrogation sont généralement utilisés avec les méthodes de recherche suivantes :

GET : Pour filtrer les résultats de recherche. Voir Paramètres d'interrogation avec GET.
POST : Pour filtrer les résultats de recherche à l'aide des paramètres du corps de la demande (pour des raisons de sécurité). Voir Paramètres d'interrogation avec un corps de demande POST /.search.

Paramètres d'interrogation avec GET

Lorsque vous effectuez une recherche à l'aide d'une demande GET sur un point d'extrémité de ressource tel que /Users ou /Groups, vous placez l'interrogation dans l'URL. Ajoutez un point d'interrogation (?) à l'URL, suivi de l'interrogation.

Note

Les caractères d'une URL qui sont en dehors du jeu de caractères ASCII, tels que des espaces et des guillemets, doivent être encodés par une URL. Des exemples sont fournis avec des caractères codés par URL. + remplace les espaces et %22 remplace les guillemets (").

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

Pour rechercher tous les groupes et AppRoles associés à un utilisateur spécifique :

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

Paramètres d'interrogation avec un corps de demande POST /.search

Vous pouvez créer des recherches avec une demande POST sur un point d'extrémité de ressource se terminant par /.search. Dans ce cas, vous placez l'interrogation dans le corps de la demande. Lors de la recherche d'informations sensibles, telles que les noms d'utilisateur, où les informations sensibles sont soumises avec d'autres données, utilisez cette méthode (pour des raisons de sécurité).

Cet exemple présente le corps de la demande d'une méthode POST effectuée sur le point d'extrémité /Users/.search. Il retourne les 10 premières entrées d'utilisateur avec displayName commençant par smith et meta.resourceType égal à User.

{ 
"schemas":["urn:ietf:params:scim:api:messages:2.0:SearchRequest"], 
"attributes": ["displayName","userName"], 
"filter": "(displayName sw \"smith\")", "startIndex": 1, "count": 10
}

Le paramètre attributes peut être utilisé avec toutes les méthodes à l'exception de DELETE. Les autres paramètres d'interrogation ne sont pertinents que pour les méthodes de recherche et sont ignorés par d'autres méthodes.


Paramètre d'interrogation HTTP	Description
`attributes=attribute1,attribute2`	Indique une liste de chaînes multivaleurs indiquant les noms des attributs de ressource à retourner dans la réponse. Ce paramètre d'interrogation accepte également l'ID schéma d'extension comme nom d'attribut valide. L'inclusion de l'ID schéma d'extension dans les attributs retourne tous les attributs par défaut qu'il contient.
`attributeSets`	La recherche retourne un groupe d'attributs dans la réponse plutôt que de spécifier chaque attribut individuellement. Ce paramètre d'interrogation accepte les valeurs séparées par des virgules parmi les paramètres suivants : all (retourne tous les attributs) toujours (retourne tous les attributs marqués comme toujours dans le schéma) par défaut (retourne tous les attributs par défaut) request (retourne tous les attributs marqués comme request dans le schéma) Ces valeurs ne sont pas sensibles à la casse. Si `attributes` et `attributeSets` sont spécifiés dans la demande, les valeurs des deux sont retournées dans la réponse.
`count=N`	Indique le nombre maximal de résultats de recherche par page. Indiquez un nombre non négatif pour extraire une réponse. Un nombre négatif prend par défaut la valeur 50 et retourne les 50 premières ressources.
`startIndex=N`	Indique l'index de la page de début. Il s'agit de l'index basé sur 1 du premier résultat d'interrogation. Une valeur inférieure à 1 est interprétée comme 1.
`filter=Expression`	La recherche retourne toutes les ressources du point d'extrémité spécifié pour lesquelles l'expression est vraie. Pour plus d'informations, voir Utilisation du paramètre d'interrogation de filtre.
`sortBy=attribute`	Fournit le nom d'attribut sur lequel la réponse doit être triée.
`sortOrder=ascending` \| `sortOrder=descending`	Spécifie l'ordre dans lequel le paramètre `sortBy` est appliqué. Si vous spécifiez une valeur pour `sortBy` et que vous ne spécifiez pas `sortOrder`, `sortOrder` prend par défaut la valeur `ascending.`

Utilisation du paramètre d'interrogation de filtre

Vous pouvez utiliser l'interrogation filter dans les recherches que vous effectuez avec la méthode GET. Le format d'une interrogation de filtre est le suivant :

filter=Expression

Un filtre doit contenir au moins une expression valide. Chaque expression contient un nom d'attribut suivi d'un opérateur Attribut et d'une valeur facultative. Les attributs interrogeables varient d'une ressource à l'autre. Ces questions sont traitées dans les rubriques relatives à ces demandes GET.

L'URL suivante inclut une interrogation de filtre pour les utilisateurs ayant l'attribut userName qui contient jensen:

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


Opérateur d'attribut	Description	Comportement
`eq`	Égal	Les valeurs d'attribut et d'opérateur doivent être identiques pour une correspondance.
`ne`	Est différent de	Les valeurs d'attribut et d'opérateur ne sont pas identiques.
`co`	Contient	La valeur entière de l'opérateur doit être une sous-chaîne de la valeur d'attribut pour une correspondance.
`sw`	Commence par	La valeur entière de l'opérateur doit être une sous-chaîne de la valeur d'attribut, en commençant au début de la valeur d'attribut. Ce critère est satisfait si les deux chaînes sont identiques.
`ew`	se termine par	La valeur entière de l'opérateur doit être une sous-chaîne de la valeur d'attribut, correspondant à la fin de la valeur d'attribut. Ce critère est satisfait si les deux chaînes sont identiques.
`pr`	Présent (a une valeur)	Si l'attribut a une valeur non vide ou s'il contient un noeud non vide pour les attributs complexes, il existe une correspondance.
`gt`	supérieur à	Si la valeur de l'attribut est supérieure à la valeur de l'opérateur, il existe une correspondance. La comparaison réelle dépend du type d'attribut. Pour les types d'attribut de chaîne, il s'agit d'une comparaison lexicographique et pour les types `DateTime`, il s'agit d'une comparaison chronologique.
`ge`	Supérieur ou égal à	Si la valeur de l'attribut est supérieure ou égale à la valeur de l'opérateur, il existe une correspondance. La comparaison réelle dépend du type d'attribut. Pour les types d'attribut de chaîne, il s'agit d'une comparaison lexicographique et pour les types `DateTime`, il s'agit d'une comparaison chronologique.
`lt`	Inférieur à	Si la valeur de l'attribut est inférieure à la valeur de l'opérateur, il existe une correspondance. La comparaison réelle dépend du type d'attribut. Pour les types d'attribut de chaîne, il s'agit d'une comparaison lexicographique et pour les types `DateTime`, il s'agit d'une comparaison chronologique.
`le`	Inférieur ou égal à	Si la valeur de l'attribut est inférieure ou égale à la valeur de l'opérateur, il existe une correspondance. La comparaison réelle dépend du type d'attribut. Pour les types d'attribut de chaîne, il s'agit d'une comparaison lexicographique et pour les types `DateTime`, il s'agit d'une comparaison chronologique.

Vous pouvez combiner plusieurs expressions à l'aide des opérateurs logiques and et or et annuler une expression en la précédant de l'opérateur d'attribut not. Utilisez les parenthèses () pour le regroupement des priorités et les crochets [] pour le regroupement des filtres d'attributs complexes.

Exemples de filtres de paramètres d'interrogation

Utilisez les exemples de paramètres d'interrogation suivants comme point de départ pour les interrogations dans un domaine d'identité.

Exemples d'utilisateurs

Pour rechercher des utilisateurs dont l'attribut userName est égal à example, utilisez ce filtre :

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

Cet exemple de filtre recherche un utilisateur avec userName qui contient jensen:

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

Cet exemple de filtre recherche un utilisateur avec userName qui contient example ou qui commence par my:

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

Cet exemple de filtre recherche un utilisateur avec le sous-attribut familyName de name qui contient jensen:

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

Cet exemple d'interrogation d'URL complexe retourne tous les utilisateurs avec un userName égal à example, liste les attributs emails.value et name.familyName dans le corps de la réponse JSON et retourne un maximum de huit utilisateurs par page de sortie.

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

Cet exemple de filtre recherche des utilisateurs utilisant le paramètre de filtre dans GET.

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

Cet exemple de filtre retourne les utilisateurs dotés de l'attribut personnalisé interrogeable Nickname. Pour en savoir plus sur les attributs personnalisés interrogeables, voir Personnalisation des schémas d'utilisateur et Personnalisation des schémas.

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

Cet exemple de filtre retourne les utilisateurs dont l'attribut personnalisé interrogeable correspond à une chaîne de texte. Pour en savoir plus sur les attributs personnalisés interrogeables, voir Personnalisation des schémas d'utilisateur et Personnalisation des schémas.

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

Exemples de numéros de téléphone

Cet exemple de filtre recherche les utilisateurs dont le numéro de téléphone commence par "+1"*.

Note

Ne fonctionne qu'avec les opérations POST.


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

Cet exemple de filtre recherche les utilisateurs dont le numéro de téléphone du domicile contient la chaîne "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\""
}


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\"]"
}

Cet exemple de filtre recherche les utilisateurs avec des variations de numéro de téléphone.

Note

Le paramètre de filtre SCIM ne prend pas en charge les modèles RegEx. Vous devez avoir inclus toutes les variations possibles. Pour commencer, utilisez l'exemple suivant.


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\""
}

Exemples de rôle d'application

Cet exemple de filtre recherche tous les utilisateurs ayant une valeur AppRole spécifique :

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

Cet exemple de filtre retourne les membres de AppRole à l'aide de approleid.


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

Cet exemple de filtre retourne AppRoles pour une application spécifique à l'aide de appid.


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

Documentation sur Oracle Cloud Infrastructure