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 nécessitant 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 prend en charge 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.

Recherche floue basique

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 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 pour 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, transmettez 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 d’autres filtres de recherche en 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%'],
]);

Recherche par données personnalisées

Pour trouver des utilisateurs par les valeurs exactes stockées dans leurs données personnalisées, transmettez un ou plusieurs paramètres de requête customData à GET /api/users. Chaque valeur doit être un objet JSON encodé en URL :

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

--data-urlencode encode l’objet JSON pour vous. L’URL de requête équivalente est GET /api/users?customData=%7B%22qq%22%3A114514%7D.

remarque:

Les recherches sur les données personnalisées peuvent être plus lentes lorsqu’un tenant possède un grand nombre d’utilisateurs. Combinez customData avec un autre filtre sélectif, tel que search ou une recherche d’identité, pour affiner la requête.

Logto compare la valeur avec le champ custom_data de l’utilisateur en utilisant la contient JSONB. Seules les clés incluses dans la valeur doivent correspondre ; les autres clés dans les données personnalisées de l’utilisateur sont ignorées.

Les types sont stricts : le nombre 114514 ne correspond pas à la chaîne "114514".
Les chaînes sont sensibles à la casse.
null ne correspond qu’à un JSON null explicite, pas à une clé manquante.
Les objets imbriqués sont comparés récursivement.
Les tableaux sont comparés par élément, quel que soit l’ordre ou les doublons.

Toutes les clés dans un même objet JSON doivent correspondre (AND). Si vous transmettez customData plusieurs fois, un utilisateur correspond si l’un des objets correspond (OR) :

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

Le filtre sur les données personnalisées est toujours combiné avec les autres filtres en AND, y compris search, la recherche d’identité (identityType, identityProvider et identityId), excludeRoleId et excludeOrganizationId. Par exemple, la requête suivante retourne les utilisateurs dont le qq est 114514 et dont le nom d’utilisateur contient alice :

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

Les paramètres mode, joint et isCaseSensitive n’affectent que les recherches par mots-clés et n’ont aucun effet sur customData.

L’API retourne 400 Bad Request lorsqu’une valeur customData n’est pas un objet JSON valide (par exemple, [] ou 114514), est un objet vide {}, ou contient un objet ou un tableau vide à n’importe quel niveau (par exemple, {"profile":{}} ou {"tags":[]}). Les noms de paramètres imbriqués tels que customData.qq, customData[qq] et mode.customData sont également rejetés avec 400.

Effectuer une requête de recherche​

Exemple​

Paramètres​

Recherche floue basique​

Spécifier les champs​

Changer le mode de jointure​

Correspondance exacte et sensibilité à la casse​

Expression régulière (RegEx)​

Surcharge du mode de correspondance​

Recherche par identité externe​

Recherche par données personnalisées​