Documentation sur Oracle Cloud Infrastructure

Paramètres d'interrogation

Vous pouvez inclure des paramètres d'interrogation dans les demandes adressées à 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 capacités 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 que vous souhaitez utiliser.

  • Lister uniquement les ressources contenant des attributs spécifiés ou ayant des valeurs spécifiées pour les attributs.

  • Limitez 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.

  • Limitez 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 :

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 les espaces et les guillemets, doivent être encodés en tant qu'URL. Des exemples sont fournis avec des caractères encodé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 montre le corps de la demande d'une méthode POST exécutée sur le point d'extrémité /Users/.search. Elle 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 sauf DELETE. Les autres paramètres d'interrogation ne sont significatifs 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 à valeurs multiples 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 en tant que nom d'attribut valide. L'inclusion de l'ID schéma d'extension dans les attributs renvoie 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 :

  • tout (retourne tous les attributs)

  • toujours (renvoie tous les attributs marqués comme toujours dans le schéma)

  • valeur par défaut (retourne tous les attributs par défaut)

  • demande (retourne tous les attributs marqués comme demande dans le schéma)

Ces valeurs ne sont pas sensibles à la casse. Si attributes et attributeSets sont tous les deux 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émarrage. 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 d'attribut et d'une valeur facultative. Les attributs interrogeables varient d'une ressource à l'autre. Celles-ci sont discutées dans les rubriques pour ces demandes GET.

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

Note

Les caractères d'une URL qui sont en dehors du jeu de caractères ASCII, tels que les espaces et les guillemets, doivent être encodés en tant qu'URL. Des exemples sont fournis avec des caractères encodés par URL. + remplace les espaces et %22 remplace les guillemets (").
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 de l'attribut, à partir du début de la valeur de l'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 de l'attribut, correspondant à la fin de la valeur de l'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 y a 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 de priorités et les crochets [] pour le regroupement de filtres d'attributs complexes.

Exemples de filtre de paramètres d'interrogation

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

Note

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

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 une valeur userName égale à 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 les 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

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

Ou 


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. Utilisez l'exemple suivant pour démarrer.


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