Parámetros de Consulta

Puede incluir parámetros de consulta en las solicitudes a la API de REST de los dominios de identidad. Estos parámetros son útiles para buscar recursos con atributos o valores de atributo específicos y para ordenar y paginar la salida.

Acerca de los Parámetros de Consulta

Mediante una consulta, puede filtrar la salida para:

Nota

Las capacidades de filtrado de consultas dependen del servicio REST. Es posible que los servicios REST sin SCIM no admitan los filtros y parámetros avanzados que desea utilizar.

Enumere solo los recursos que contienen atributos especificados o que tienen valores especificados para atributos.
Limite los atributos devueltos en el cuerpo de la respuesta.
Ordene la salida en un atributo especificado, en orden ascendente o descendente.
Limite el número de recursos devueltos.
Especifique dónde, en la lista de recursos de la recopilación, iniciar la solicitud.

Los parámetros de consulta se suelen utilizar con métodos de búsqueda:

GET: Para filtrar los resultados de búsqueda. Consulte Query Parameters With GET.
POST: para filtrar los resultados de búsqueda mediante los parámetros del cuerpo de la solicitud (por motivos de seguridad). Consulte Query Parameters with a POST /.search Request Body.

Parámetros de consulta con GET

Al realizar una búsqueda mediante una solicitud GET en un punto final de recurso como /Users o /Groups, la consulta se coloca en la URL. Agregue un signo de interrogación (?) a la URL, seguido de la consulta.

Nota

Los caracteres de una URL que están fuera del juego de caracteres ASCII, como espacios y comillas, deben estar codificados en URL. Se proporcionan ejemplos con caracteres codificados en URL. + sustituye los espacios y %22 sustituye las comillas (").

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

Para buscar todos los grupos y AppRoles asociados a un usuario específico:

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

Parámetros de Consulta con Cuerpo de Solicitud POST /.search

Puede crear búsquedas con una solicitud POST en un punto final de recurso que termine en /.search. En ese caso, la consulta se coloca en el cuerpo de la solicitud. Al buscar información confidencial, como nombres de usuario, en los que se envía la información confidencial junto con otros datos, utilice este método (por motivos de seguridad).

En este ejemplo se muestra el cuerpo de solicitud de un método POST realizado en el punto final /Users/.search. Devuelve las primeras 10 entradas de usuario con displayName empezando por smith y meta.resourceType igual a User.

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

El parámetro attributes se puede utilizar con todos los métodos excepto DELETE. Los demás parámetros de consulta solo son significativos para los métodos de búsqueda y otros métodos los ignoran.


Parámetro de consulta HTTP	Descripción
`attributes=attribute1,attribute2`	Especifica una lista de cadenas de varios valores que indica los nombres de los atributos de recursos que se devolverán en la respuesta. Este parámetro de consulta también acepta el ID de esquema de extensión como un nombre de atributo válido. Si se incluye el ID de esquema de extensión en los atributos, se devuelven todos los atributos por defecto que contiene.
`attributeSets`	La búsqueda devuelve un grupo de atributos en la respuesta en lugar de especificar cada atributo individualmente. Este parámetro de consulta acepta valores separados por comas de los siguientes parámetros: all (devuelve todos los atributos) always (devuelve todos los atributos marcados como siempre en el esquema) default (devuelve todos los atributos por defecto) request (devuelve todos los atributos marcados como solicitud en el esquema) Estos valores no distinguen entre mayúsculas y minúsculas. Si se especifican `attributes` y `attributeSets` en la solicitud, los valores de ambos se devuelven en la respuesta.
`count=N`	Indica el número máximo de resultados de búsqueda por página. Especifique un número no negativo para recuperar una respuesta. Un número negativo se establece por defecto en 50 y devuelve los primeros 50 recursos.
`startIndex=N`	Especifica el índice de la página de inicio. Se trata del índice basado en 1 del primer resultado de consulta. Un valor menor que 1 se interpreta como 1.
`filter=Expression`	La búsqueda devuelve todos los recursos del punto final especificado para el que la expresión es verdadera. Consulte Uso del parámetro de consulta de filtro para obtener más información.
`sortBy=attribute`	Proporciona el nombre de atributo en el que se debe ordenar la respuesta.
`sortOrder=ascending` \| `sortOrder=descending`	Especifica el orden en el que se aplica el parámetro `sortBy`. Si especifica un valor para `sortBy` y no especifica un valor `sortOrder`, el valor por defecto de `sortOrder` es `ascending.`

Uso del parámetro de consulta de filtro

Puede utilizar la consulta filter en las búsquedas que realice con el método GET. El formato de una consulta de filtro es:

filter=Expression

Un filtro debe contener al menos una expresión válida. Cada expresión contiene un nombre de atributo seguido de un operador de atributo y un valor opcional. Los atributos que se pueden buscar varían de un recurso a otro. Estos se tratan en los temas de esas solicitudes de GET.

La siguiente URL incluye una consulta de filtro para los usuarios con el atributo userName que contiene jensen:

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


Operador de atributo	Descripción	Comportamiento
`eq`	Igual que	Los valores de atributo y operador deben ser idénticos para una coincidencia.
`ne`	Distinto de	Los valores de atributo y operador no son idénticos.
`co`	Contiene	El valor de operador completo debe ser una subcadena del valor de atributo para una coincidencia.
`sw`	Empieza por	El valor de operador completo debe ser una subcadena del valor de atributo, empezando por el principio del valor de atributo. Este criterio se cumple si las dos cadenas son idénticas.
`ew`	Termina con	El valor de operador completo debe ser una subcadena del valor de atributo, que coincida al final del valor de atributo. Este criterio se cumple si las dos cadenas son idénticas.
`pr`	Presente (tiene valor)	Si el atributo tiene un valor que no está vacío o si contiene un nodo que no está vacío para atributos complejos, hay una coincidencia.
`gt`	Mayor que	Si el valor del atributo es mayor que el valor del operador, hay una coincidencia. La comparación real depende del tipo de atributo. Para los tipos de atributos de cadena, se trata de una comparación lexicográfica y, para los tipos `DateTime`, se trata de una comparación cronológica.
`ge`	Mayor o Igual que	Si el valor del atributo es mayor o igual que el valor del operador, hay una coincidencia. La comparación real depende del tipo de atributo. Para los tipos de atributos de cadena, se trata de una comparación lexicográfica y, para los tipos `DateTime`, se trata de una comparación cronológica.
`lt`	Menor que	Si el valor del atributo es menor que el valor del operador, hay una coincidencia. La comparación real depende del tipo de atributo. Para los tipos de atributos de cadena, se trata de una comparación lexicográfica y, para los tipos `DateTime`, se trata de una comparación cronológica.
`le`	Menor o Igual que	Si el valor del atributo es menor o igual que el valor del operador, hay una coincidencia. La comparación real depende del tipo de atributo. Para los tipos de atributos de cadena, se trata de una comparación lexicográfica y, para los tipos `DateTime`, se trata de una comparación cronológica.

Puede combinar varias expresiones mediante los operadores lógicos and y or y negar una expresión precediéndola con el operador de atributo not. Utilice los paréntesis () para la agrupación de prioridad y los corchetes [] para la agrupación de filtros de atributos complejos.

Ejemplos de filtros de parámetros de consulta

Utilice los siguientes ejemplos de parámetros de consulta como punto de partida para las consultas en un dominio de identidad.

Ejemplos de usuario

Para buscar usuarios con el atributo userName igual a example, debe utilizar este filtro:

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

Este ejemplo de filtro busca un usuario con un valor userName que contenga jensen:

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

Este ejemplo de filtro busca un usuario con un valor userName que contenga example o que empiece por my:

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

Este ejemplo de filtro busca un usuario con el subatributo familyName de name que contiene jensen:

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

Este ejemplo de consulta de URL compleja devuelve todos los usuarios con un valor userName igual a example, muestra los atributos emails.value y name.familyName en el cuerpo de respuesta de JSON y devuelve un máximo de ocho usuarios por página de salida.

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

Este ejemplo de filtro busca usuarios mediante el parámetro de filtro en GET.

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

Este ejemplo de filtro devuelve los usuarios que tienen el atributo personalizado apto para búsqueda Nickname. Para obtener más información sobre los atributos personalizados que se pueden buscar, consulte Personalización de esquemas de usuario y Personalización de esquemas.

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

Este ejemplo de filtro devuelve usuarios cuyo atributo personalizado de búsqueda coincide con una cadena de texto. Para obtener más información sobre los atributos personalizados que se pueden buscar, consulte Personalización de esquemas de usuario y Personalización de esquemas.

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

Ejemplos de números de teléfono

Este ejemplo de filtro busca usuarios cuyo número de teléfono empiece por "+1"*.

Nota

Solo funciona con operaciones POST.


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

Este ejemplo de filtro busca usuarios cuyo número de teléfono particular contenga la cadena "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\""
}

O bien


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

Este ejemplo de filtro busca usuarios con variaciones de número de teléfono.

Nota

El parámetro de filtro de SCIM no soporta patrones RegEx. Debe haber incluido todas las variaciones posibles. Utilice el siguiente ejemplo para empezar.


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

Ejemplos de roles de aplicación

Este ejemplo de filtro busca todos los usuarios que tienen un AppRole específico:

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

Este ejemplo de filtro devuelve los miembros de AppRole mediante approleid.


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

Este ejemplo de filtro devuelve AppRoles para una aplicación específica mediante appid.


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

Documentación de Oracle Cloud Infrastructure