Búsqueda avanzada de usuarios

Uso directo de 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 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 habilitada la paginación.

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

aviso:

El modo de búsqueda está configurado como 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.

Búsqueda difusa básica

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 en @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 en @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 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%'],
]);

Buscar por datos personalizados

Para encontrar usuarios por los valores exactos almacenados en sus datos personalizados, pasa uno o más parámetros de consulta customData a GET /api/users. Cada valor debe ser un objeto JSON codificado en URL:

curl \
  --get \
  --data-urlencode 'customData={"qq":114514}' \
  'http://<your-logto-endpoint>/api/users'

--data-urlencode codifica el objeto JSON por ti. La URL de solicitud equivalente es GET /api/users?customData=%7B%22qq%22%3A114514%7D.

nota:

Las búsquedas por datos personalizados pueden ser más lentas cuando un tenant tiene un gran número de usuarios. Combina customData con otro filtro selectivo, como search o una búsqueda de identidad, para acotar la consulta.

Logto compara el valor con el custom_data del usuario usando JSONB containment. Solo las claves incluidas en el valor deben coincidir; otras claves en los datos personalizados del usuario se ignoran.

Los tipos son estrictos: el número 114514 no coincide con la cadena "114514".
Las cadenas distinguen entre mayúsculas y minúsculas.
null solo coincide con un JSON null explícito, no con una clave ausente.
Los objetos anidados se comparan recursivamente.
Los arrays se comparan por elemento, sin importar el orden o duplicados.

Todas las claves dentro de un objeto JSON deben coincidir (AND). Si pasas customData más de una vez, un usuario coincide cuando cualquiera de los objetos coincide (OR):

curl \
  --get \
  --data-urlencode 'customData={"qq":114514}' \
  --data-urlencode 'customData={"wechat":"logto"}' \
  'http://<your-logto-endpoint>/api/users'

El filtro de datos personalizados siempre se combina con otros filtros usando AND, incluyendo search, búsqueda de identidad (identityType, identityProvider y identityId), excludeRoleId y excludeOrganizationId. Por ejemplo, la siguiente solicitud devuelve usuarios cuyo qq es 114514 y cuyo nombre de usuario contiene alice:

curl \
  --get \
  --data-urlencode 'customData={"qq":114514}' \
  --data-urlencode 'search.username=%alice%' \
  'http://<your-logto-endpoint>/api/users'

Los parámetros mode, joint y isCaseSensitive solo afectan a las búsquedas por palabra clave y no tienen efecto en customData.

La API devuelve 400 Bad Request cuando un valor de customData no es un objeto JSON válido (por ejemplo, [] o 114514), es un objeto vacío {}, o contiene un objeto o array vacío en cualquier nivel (por ejemplo, {"profile":{}} o {"tags":[]}). Los nombres de parámetros anidados como customData.qq, customData[qq] y mode.customData también se rechazan con 400.

Realizar una solicitud de búsqueda​

Ejemplo​

Parámetros​

Búsqueda difusa básica​

Especificar campos​

Cambiar el modo de unión​

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

Expresión regular (RegEx)​

Sobrescribir el modo de coincidencia​

Buscar por identidad externa​

Buscar por datos personalizados​