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
oujointMode
(valeur par défaut'or'
, disponibles['or', 'and']
) - Sensibilité à la casse :
isCaseSensitive
(valeur par défautfalse
)
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
.
Le mode de recherche est défini sur like
par défaut, qui utilise la correspondance approximative de chaînes ("recherche floue").
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'],
]);