Aller au contenu principal

Recherche avancée d'utilisateurs

Utilisez directement Management API pour exploiter des conditions de recherche avancées d'utilisateurs.

Effectuer une requête de recherche

Utilisez GET /api/users pour rechercher des utilisateurs. Notez qu'il s'agit d'une Management API qui nécessite une authentification comme les autres. Voir Interagir avec Management API pour la recette d'interaction.

Exemple

Requête

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

Réponse

Un tableau d'entités User.

[
{
"id": "MgUzzDsyX0iB",
"username": "alice_123",
"primaryEmail": "[email protected]",
"primaryPhone": null,
"name": null,
"avatar": null
// ...
}
]

Paramètres

Une requête de recherche se compose des clés de paramètres suivantes :

  • Mots-clés de recherche : search, search.*
  • Mode de recherche pour les champs : mode, mode.* (valeur par défaut 'like', disponibles ['exact', 'like', 'similar_to', 'posix'])
  • Mode de jointure : joint ou jointMode (valeur par défaut 'or', disponibles ['or', 'and'])
  • Sensibilité à la casse : isCaseSensitive (valeur par défaut false)

Cette API a la pagination activée.

Passons-les en revue à travers quelques exemples. Tous les paramètres de recherche seront formatés comme un constructeur de URLSearchParams.

attention

Le mode de recherche est défini sur like par défaut, qui utilise la correspondance approximative de chaînes ("recherche floue").

remarque

Tous les modes de recherche floue ne prennent en charge la correspondance qu'avec une seule valeur par champ. Si vous devez faire correspondre plusieurs valeurs pour un seul champ, vous devez utiliser le mode "exact". Voir Correspondance exacte et sensibilité à la casse pour plus de détails.

Recherche floue de base

Si vous souhaitez effectuer une recherche floue sur tous les champs disponibles, fournissez simplement une valeur pour la clé search. Cela utilisera l'opérateur like en interne :

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

Cette recherche parcourra tous les champs disponibles dans une recherche d'utilisateur, c'est-à-dire id, primaryEmail, primaryPhone, username, name.

Spécifier les champs

Que faire si vous souhaitez limiter la recherche au champ name uniquement ? Pour rechercher quelqu'un qui inclut foo dans son nom, utilisez simplement le symbole . pour spécifier le champ :

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

Rappelez-vous que les champs imbriqués ne sont pas pris en charge, par exemple search.name.first entraînera une erreur.

Vous pouvez également spécifier plusieurs champs en même temps :

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

Cela signifie rechercher des utilisateurs qui ont foo dans le nom OU dont l'email se termine par @gmail.com.

Changer le mode de jointure

Si vous souhaitez que l'API ne retourne que le résultat qui satisfait TOUTES les conditions, définissez le mode de jointure sur and :

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

Cela signifie rechercher des utilisateurs qui ont foo dans le nom ET dont l'email se termine par @gmail.com.

Correspondance exacte et sensibilité à la casse

Disons que vous voulez rechercher dont le nom est exactement "Alice". Vous pouvez définir mode.name pour utiliser la correspondance exacte.

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

Vous pouvez constater qu'il a le même effet lorsque vous utilisez le mode like (par défaut) par rapport à la spécification exact. Une différence est que le mode exact utilise = pour comparer tandis que like utilise like ou ilike. Théoriquement, = devrait avoir de meilleures performances.

De plus, en mode exact, vous pouvez passer plusieurs valeurs pour la correspondance, et elles seront connectées avec or :

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

Cela correspondra aux utilisateurs avec le nom "Alice" OU "Bob".

Par défaut, la recherche n'est pas sensible à la casse. Pour être plus précis, définissez la recherche comme sensible à la casse :

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

Notez que isCaseSensitive est une configuration globale. Ainsi, CHAQUE champ le suivra.

Expression régulière (RegEx)

PostgreSQL prend en charge deux types d'expressions régulières, similar to et posix. Définissez mode sur similar_to ou posix pour rechercher par expressions régulières :

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

Notez que le mode similar_to ne fonctionne que dans les recherches sensibles à la casse.

Remplacement du mode de correspondance

Par défaut, tous les mots-clés hériteront du mode de correspondance de la recherche générale :

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

Pour remplacer pour un champ spécifique :

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