Parámetros de Consulta

Puede incluir parámetros de consulta en solicitudes a la API de REST de dominios de identidad. Estos parámetros son útiles para buscar recursos con atributos o valores de atributos 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 parámetros y filtros avanzados que desea utilizar.

Mostrar 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.
Permite limitar 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 resultados de búsqueda. Consulte Consulta de parámetros con GET.
POST: para filtrar los resultados de búsqueda utilizando los parámetros del cuerpo de la solicitud (por motivos de seguridad). Consulte Parámetros de Consulta con Cuerpo de Solicitud POST /.search.

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 una URL. Se proporcionan ejemplos con caracteres codificados de 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 un 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. Cuando busque información confidencial, como nombres de usuario, donde 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 la 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 sólo son significativos para los métodos de búsqueda y son ignorados por otros métodos.


Parámetro de consulta HTTP	Descripción
`attributes=attribute1,attribute2`	Especifica una lista de cadenas con 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 identificador de esquema de extensión como nombre de atributo válido. La inclusión del identificador de esquema de extensión en los atributos devuelve 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) Siempre (devuelve todos los atributos marcados como siempre en el esquema) por defecto (devuelve todos los atributos por defecto) solicitud (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. El valor predeterminado de un número negativo es 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 la consulta. Un valor menor que 1 se interpreta como 1.
`filter=Expression`	La búsqueda devuelve todos los recursos del punto final especificado para los 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 del 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 `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 temas 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 de operador deben ser idénticos para una coincidencia.
`ne`	Distinto	Los valores de atributo y operador no son idénticos.
`co`	Contiene	Todo el valor de operador debe ser una subcadena del valor de atributo para una coincidencia.
`sw`	Empieza por	Todo el valor de operador 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 en	Todo el valor de operador 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 no vacío o si contiene un nodo no 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 atributo de cadena, se trata de una comparación lexicográfica y para los tipos `DateTime`, es 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 atributo de cadena, se trata de una comparación lexicográfica y para los tipos `DateTime`, es 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 atributo de cadena, se trata de una comparación lexicográfica y para los tipos `DateTime`, es 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 atributo de cadena, se trata de una comparación lexicográfica y para los tipos `DateTime`, es una comparación cronológica.

Puede combinar varias expresiones mediante los operadores lógicos and y or y negar una expresión anteponiéndola al 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 filtro 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 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 que utilizan 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 de búsqueda Nickname. Para obtener más información sobre los atributos personalizados con capacidad de búsqueda, 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 apto para búsqueda coincide con una cadena de texto. Para obtener más información sobre los atributos personalizados con capacidad de búsqueda, 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úmero de teléfono

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

Nota

Sólo 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 contiene 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 admite 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 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