Aller au contenu principal

Recherche avancée d’utilisateurs

Utilisez directement Management API pour exploiter des conditions de recherche avancées sur les 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. Consultez Interagir avec Management API pour la recette d’intégration.

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": "alice@some.email.domain",
    "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', valeurs possibles ['exact', 'like', 'similar_to', 'posix'])
  • Mode de jointure : joint ou jointMode (valeur par défaut 'or', valeurs possibles ['or', 'and'])
  • Sensibilité à la casse : isCaseSensitive (valeur par défaut false)

Cette API dispose de la pagination.

Voyons-les à 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, ce qui utilise la correspondance approximative de chaînes ("recherche floue").

remarque:

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

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 itérera sur tous les champs disponibles dans une recherche utilisateur, c’est-à-dire id, primaryEmail, primaryPhone, username, name.

Spécifier les champs​

Et si vous souhaitez limiter la recherche uniquement au champ name ? Pour rechercher quelqu’un dont le nom contient foo, utilisez simplement le symbole . pour spécifier le champ :

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

N’oubliez pas 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 les utilisateurs qui ont foo dans le nom OU dont l’e-mail se termine par @gmail.com.

Changer le mode de jointure​

Si vous souhaitez que l’API ne retourne que les résultats qui satisfont 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 les utilisateurs qui ont foo dans le nom ET dont l’e-mail se termine par @gmail.com.

Correspondance exacte et sensibilité à la casse​

Supposons que vous souhaitez rechercher les utilisateurs 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 remarquerez peut-être que cela a le même effet que d’utiliser le mode like (par défaut) par rapport à la spécification de exact. Une différence est que le mode exact utilise = pour comparer tandis que like utilise like ou ilike. Théoriquement, = devrait offrir de meilleures performances.

De plus, en mode exact, vous pouvez passer plusieurs valeurs à faire correspondre, et elles seront reliées par or :

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

Cela correspondra aux utilisateurs dont le nom est "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, TOUS les champs la suivront.

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

Note : Le mode similar_to ne fonctionne que dans les recherches sensibles à la casse.

Surcharge 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 surcharger 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'],
]);

Recherche par identité externe​

Pour trouver l’utilisateur lié à une identité sociale ou SSO d’entreprise, passez les trois paramètres de requête suivants ensemble pour une recherche exacte :

  • identityType : social pour une identité de connecteur social, ou sso pour une identité SSO d’entreprise.
  • identityProvider : la cible du connecteur pour une identité sociale (par exemple, dingtalk), ou l’émetteur pour une identité SSO d’entreprise.
  • identityId : l’identifiant utilisateur délivré par le fournisseur d’identité externe.
// Trouver l’utilisateur lié à une identité sociale DingTalk
new URLSearchParams([
  ['identityType', 'social'],
  ['identityProvider', 'dingtalk'],
  ['identityId', 'dingtalk-open-id'],
]);
// Trouver l’utilisateur lié à une identité SSO d’entreprise
new URLSearchParams([
  ['identityType', 'sso'],
  ['identityProvider', 'https://example.com/issuer'],
  ['identityId', 'enterprise-user-id'],
]);

Le filtre d’identité est combiné avec les autres filtres de recherche en utilisant une logique AND. Par exemple, pour affiner davantage la recherche d’identité avec un mot-clé :

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