Paramètres de requête

Vous pouvez inclure des paramètres de requête 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.

A propos des paramètres de requête

A l'aide d'une requête, vous pouvez filtrer la sortie pour :

Remarque

Les fonctionnalités de filtrage des requêtes 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.

Répertoriez uniquement les ressources contenant des attributs spécifiés ou ayant des valeurs spécifiées pour les attributs.
Limitez les attributs renvoyés dans le corps de la réponse.
Trier les résultats sur un attribut spécifié, dans l'ordre croissant ou décroissant.
Limitez le nombre de ressources renvoyées.
Indiquez où, dans la liste des ressources de la collection, démarrer la demande.

Les paramètres de requête sont généralement utilisés avec les méthodes de recherche :

GET : pour le filtrage des résultats de recherche. Reportez-vous à Paramètres de requête avec GET.
POST : Pour filtrer les résultats de la recherche à l'aide des paramètres du corps de la demande (pour des raisons de sécurité). Reportez-vous à Paramètres de requête avec un corps de demande POST /.search.

Paramètres de requête avec GET

Lorsque vous effectuez une recherche à l'aide d'une demande GET sur une adresse de ressource telle que /Users ou /Groups, vous placez la requête dans l'URL. Ajoutez un point d'interrogation (?) à l'URL, suivi de la requête.

Remarque

Les caractères d'une URL qui se trouvent en dehors du jeu de caractères ASCII, tels que les espaces et les guillemets, doivent être encodés en URL. Des exemples sont fournis avec des caractères codés par URL. Le signe + 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, procédez comme suit :

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

Paramètres de requête avec un corps de requête POST /.search

Vous pouvez créer des recherches avec une demande POST sur une adresse de ressource se terminant par /.search. Dans ce cas, vous placez la requête 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 l'adresse /Users/.search. Elle renvoie les 10 premières entrées 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 de requête ne sont significatifs que pour les méthodes de recherche et sont ignorés par d'autres méthodes.


Paramètre de requête HTTP	Description
`attributes=attribute1,attribute2`	Spécifie une liste à valeurs multiples de chaînes indiquant les noms des attributs de ressource à renvoyer dans la réponse. Ce paramètre de requête accepte également l'ID de schéma d'extension en tant que nom d'attribut valide. L'inclusion de l'ID de schéma d'extension dans les attributs renvoie tous les attributs par défaut qu'il contient.
`attributeSets`	La recherche renvoie un groupe d'attributs dans la réponse plutôt que de spécifier chaque attribut individuellement. Ce paramètre de requête accepte les valeurs séparées par des virgules des paramètres suivants : all (renvoie tous les attributs) always (renvoie tous les attributs marqués comme toujours dans le schéma) default (renvoie tous les attributs par défaut) demande (renvoie tous les attributs marqués comme demande dans le schéma) Ces valeurs ne font pas la casse. Si `attributes` et `attributeSets` sont indiqués dans la demande, les valeurs des deux sont renvoyées dans la réponse.
`count=N`	Indique le nombre maximum de résultats de recherche par page. Indiquez un nombre non négatif pour extraire une réponse. Par défaut, un nombre négatif est égal à 50 et renvoie 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 de requête. Une valeur inférieure à 1 est interprétée comme 1.
`filter=Expression`	La recherche renvoie toutes les ressources de l'adresse indiquée pour lesquelles l'expression est vraie. Pour plus d'informations, reportez-vous à Utilisation du paramètre de requête de filtre.
`sortBy=attribute`	Fournit le nom de l'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 indiquez une valeur pour `sortBy` et que vous n'indiquez pas de valeur `sortOrder`, la valeur par défaut de `sortOrder` est `ascending.`

Utilisation du paramètre de requête de filtre

Vous pouvez utiliser la requête filter dans les recherches que vous effectuez avec la méthode GET. Le format d'une requête 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 recherchables varient d'une ressource à l'autre. Celles-ci sont traitées dans les rubriques de ces demandes GET.

L'URL suivante inclut une requête de filtre pour les utilisateurs avec l'attribut userName qui contient jensen:

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


Opérateur d'attributs	Description	Comportement
`eq`	Est égal à	Les valeurs d'attribut et d'opérateur doivent être identiques pour une correspondance.
`ne`	Non égal	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, 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 y a une correspondance.
`gt`	Est 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, une correspondance est établie. 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`	Est inférieur ou égal à	Si la valeur de l'attribut est inférieure ou égale à la valeur de l'opérateur, il y a 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 faisant précéder de l'opérateur d'attribut not. Utilisez les parenthèses () pour le regroupement de priorité et les crochets [] pour le regroupement de filtres d'attribut complexe.

Exemples de filtre de paramètres de requête

Utilisez les exemples de paramètres de requête suivants comme point de départ pour les requêtes dans un domaine d'identité.

Exemples d'utilisateurs

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

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

Cet exemple de filtre recherche un utilisateur avec un élément userName contenant jensen:

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

Cet exemple de filtre recherche un utilisateur avec un élément 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 de requête d'URL complexe renvoie tous les utilisateurs dont la valeur userName est égale à example, répertorie les attributs emails.value et name.familyName dans le corps de réponse JSON et renvoie 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 à l'aide du paramètre de filtre dans GET.

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

Cet exemple de filtre renvoie les utilisateurs dont l'attribut personnalisé recherchable est Nickname. Pour en savoir plus sur les attributs personnalisés pouvant faire l'objet d'une recherche, reportez-vous à Personnalisation des schémas 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 renvoie les utilisateurs dont l'attribut personnalisé recherchable correspond à une chaîne de texte. Pour en savoir plus sur les attributs personnalisés pouvant faire l'objet d'une recherche, reportez-vous à Personnalisation des schémas 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"*.

Remarque

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 personnel 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 dont le numéro de téléphone varie.

Remarque

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 commencer.


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ôles d'application

Cet exemple de filtre recherche tous les utilisateurs ayant un 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 renvoie les membres de AppRole à l'aide de approleid.


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

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


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

Documentation Oracle Cloud Infrastructure