Saltar al contenido principal

Búsqueda avanzada de usuarios

Utiliza directamente la Management API para aprovechar condiciones avanzadas de búsqueda de usuarios.

Realizar una solicitud de búsqueda​

Utiliza GET /api/users para buscar usuarios. Ten en cuenta que es una Management API que requiere autenticación como las demás. Consulta Interactuar con Management API para la receta de interacción.

Ejemplo​

Solicitud

curl \
  --location \
  --request GET \
  'http://<your-logto-endpoint>/api/users?search=%25alice%25'

Respuesta

Un array de entidades User.

[
  {
    "id": "MgUzzDsyX0iB",
    "username": "alice_123",
    "primaryEmail": "alice@some.email.domain",
    "primaryPhone": null,
    "name": null,
    "avatar": null
    // ...
  }
]

Parámetros​

Una solicitud de búsqueda consta de las siguientes claves de parámetro:

  • Palabras clave de búsqueda: search, search.*
  • Modo de búsqueda para los campos: mode, mode.* (valor predeterminado 'like', disponibles ['exact', 'like', 'similar_to', 'posix'])
  • Modo de unión: joint o jointMode (valor predeterminado 'or', disponibles ['or', 'and'])
  • Es sensible a mayúsculas y minúsculas: isCaseSensitive (valor predeterminado false)

Esta API tiene paginación habilitada.

Vamos a repasarlos con algunos ejemplos. Todos los parámetros de búsqueda estarán formateados como un constructor de URLSearchParams.

aviso:

El modo de búsqueda se establece en like por defecto, que utiliza coincidencia aproximada de cadenas ("búsqueda difusa").

nota:

Todos los modos de búsqueda difusa solo admiten la coincidencia de un valor por campo. Si necesitas hacer coincidir varios valores para un solo campo, debes usar el modo "exact". Consulta Coincidencia exacta y sensibilidad a mayúsculas y minúsculas para más detalles.

Si deseas realizar una búsqueda difusa en todos los campos disponibles, solo proporciona un valor para la clave search. Utilizará el operador like internamente:

new URLSearchParams([['search', '%foo%']]);

Esta búsqueda iterará sobre todos los campos disponibles en una búsqueda de usuario, es decir, id, primaryEmail, primaryPhone, username, name.

Especificar campos​

¿Qué pasa si quieres limitar la búsqueda solo en name? Para buscar a alguien que incluya foo en su nombre, solo usa el símbolo . para especificar el campo:

new URLSearchParams([['search.name', '%foo%']]);

Recuerda que los campos anidados no son compatibles, por ejemplo, search.name.first dará como resultado un error.

También puedes especificar varios campos al mismo tiempo:

new URLSearchParams([
  ['search.name', '%foo%'],
  ['search.primaryEmail', '%@gmail.com'],
]);

Significa buscar usuarios que tengan foo en el nombre O cuyo correo electrónico termine con @gmail.com.

Cambiar el modo de unión​

Si deseas que la API solo devuelva el resultado que cumpla TODAS las condiciones, establece el modo de unión en and:

new URLSearchParams([
  ['search.name', '%foo%'],
  ['search.primaryEmail', '%@gmail.com'],
  ['joint', 'and'],
]);

Significa buscar usuarios que tengan foo en el nombre Y cuyo correo electrónico termine con @gmail.com.

Coincidencia exacta y sensibilidad a mayúsculas y minúsculas​

Supón que quieres buscar cuyo nombre sea exactamente "Alice". Puedes establecer mode.name para usar coincidencia exacta.

new URLSearchParams([
  ['search.name', 'Alice'],
  ['mode.name', 'exact'],
]);

Puedes notar que tiene el mismo efecto al usar el modo like (predeterminado) frente a especificar exact. Una diferencia es que el modo exact utiliza = para comparar mientras que like utiliza like o ilike. Teóricamente, = debería tener un mejor rendimiento.

Además, en el modo exact, puedes pasar varios valores para la coincidencia, y se conectarán con or:

new URLSearchParams([
  ['search.name', 'Alice'],
  ['search.name', 'Bob'],
  ['mode.name', 'exact'],
]);

Coincidirá con los usuarios cuyo nombre sea "Alice" O "Bob".

Por defecto, la búsqueda no distingue entre mayúsculas y minúsculas. Para ser más preciso, configura la búsqueda como sensible a mayúsculas y minúsculas:

new URLSearchParams([
  ['search.name', 'Alice'],
  ['search.name', 'Bob'],
  ['mode.name', 'exact'],
  ['isCaseSensitive', 'true'],
]);

Ten en cuenta que isCaseSensitive es una configuración global. Por lo tanto, TODOS los campos la seguirán.

Expresión regular (RegEx)​

PostgreSQL admite dos tipos de expresiones regulares, similar to y posix. Establece mode en similar_to o posix para buscar mediante expresiones regulares:

new URLSearchParams([
  ['search', '^T.?m Scot+$'],
  ['mode', 'posix'],
]);

Nota: El modo similar_to solo funciona en búsquedas sensibles a mayúsculas y minúsculas.

Sobrescribir el modo de coincidencia​

Por defecto, todas las palabras clave heredarán el modo de coincidencia de la búsqueda general:

new URLSearchParams([
  ['search', '^T.?m Scot+$'],
  ['mode', 'posix'],
  ['search.primaryEmail', 'tom%'], // Modo posix
  ['joint', 'and'],
]);

Para sobrescribirlo para un campo específico:

new URLSearchParams([
  ['search', '^T.?m Scot+$'],
  ['mode', 'posix'],
  ['search.primaryEmail', 'tom%'], // Modo like
  ['mode.primaryEmail', 'like'],
  ['search.phone', '0{3,}'], // Modo posix
  ['joint', 'and'],
]);

Buscar por identidad externa​

Para encontrar el usuario vinculado a una identidad social o SSO empresarial, pasa los siguientes tres parámetros de consulta juntos para una búsqueda exacta:

  • identityType: social para una identidad de conector social, o sso para una identidad de SSO empresarial.
  • identityProvider: el conector objetivo para una identidad social (por ejemplo, dingtalk), o el emisor para una identidad SSO empresarial.
  • identityId: el identificador de usuario emitido por el proveedor de identidad externo.
// Buscar el usuario vinculado a una identidad social de DingTalk
new URLSearchParams([
  ['identityType', 'social'],
  ['identityProvider', 'dingtalk'],
  ['identityId', 'dingtalk-open-id'],
]);
// Buscar el usuario vinculado a una identidad SSO empresarial
new URLSearchParams([
  ['identityType', 'sso'],
  ['identityProvider', 'https://example.com/issuer'],
  ['identityId', 'enterprise-user-id'],
]);

El filtro de identidad se combina con otros filtros de búsqueda usando lógica AND. Por ejemplo, para acotar aún más la búsqueda de identidad con una palabra clave:

new URLSearchParams([
  ['identityType', 'social'],
  ['identityProvider', 'dingtalk'],
  ['identityId', 'dingtalk-open-id'],
  ['search', '%foo%'],
]);