Zum Hauptinhalt springen

Erweiterte Benutzersuche

Direkte Nutzung der Management API, um erweiterte Suchbedingungen für Benutzer zu nutzen.

Eine Suchanfrage durchführen​

Verwende GET /api/users, um nach Benutzern zu suchen. Beachte, dass es sich um eine Management API handelt, die wie andere eine Authentifizierung benötigt. Siehe Interaktion mit Management API für das Interaktionsrezept.

Beispiel​

Anfrage

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

Antwort

Ein Array von User-Entitäten.

[
  {
    "id": "MgUzzDsyX0iB",
    "username": "alice_123",
    "primaryEmail": "alice@some.email.domain",
    "primaryPhone": null,
    "name": null,
    "avatar": null
    // ...
  }
]

Parameter​

Eine Suchanfrage besteht aus den folgenden Parameter-Schlüsseln:

  • Suchbegriffe: search, search.*
  • Suchmodus für Felder: mode, mode.* (Standardwert 'like', verfügbar: ['exact', 'like', 'similar_to', 'posix'])
  • Verknüpfungsmodus: joint oder jointMode (Standardwert 'or', verfügbar: ['or', 'and'])
  • Groß- / Kleinschreibung beachten: isCaseSensitive (Standardwert false)

Diese API unterstützt Paginierung.

Gehen wir sie anhand einiger Beispiele durch. Alle Suchparameter werden als Konstruktor von URLSearchParams formatiert.

warnung:

Der Suchmodus ist standardmäßig auf like gesetzt, was ungefähres String-Matching („unscharfe Suche“) verwendet.

hinweis:

Alle unscharfen Suchmodi unterstützen nur das Matching eines Wertes pro Feld. Wenn du mehrere Werte für ein einzelnes Feld abgleichen möchtest, solltest du den Modus "exact" verwenden. Siehe Exakte Übereinstimmung und Groß- / Kleinschreibung für Details.

Wenn du eine unscharfe Suche über alle verfügbaren Felder durchführen möchtest, gib einfach einen Wert für den Schlüssel search an. Es wird der like-Operator im Hintergrund verwendet:

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

Diese Suche iteriert über alle verfügbaren Felder in einer Benutzersuche, d. h. id, primaryEmail, primaryPhone, username, name.

Felder angeben​

Was ist, wenn du die Suche nur auf name beschränken möchtest? Um jemanden zu suchen, dessen Name foo enthält, verwende einfach das Symbol . zur Feldangabe:

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

Beachte, dass verschachtelte Felder nicht unterstützt werden, z. B. führt search.name.first zu einem Fehler.

Du kannst auch mehrere Felder gleichzeitig angeben:

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

Das bedeutet, Benutzer zu suchen, die foo im Namen haben ODER deren E-Mail-Adresse mit @gmail.com endet.

Den Verknüpfungsmodus ändern​

Wenn du möchtest, dass die API nur Ergebnisse zurückgibt, die ALLE Bedingungen erfüllen, setze den Verknüpfungsmodus auf and:

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

Das bedeutet, Benutzer zu suchen, die foo im Namen haben UND deren E-Mail-Adresse mit @gmail.com endet.

Exakte Übereinstimmung und Groß- / Kleinschreibung​

Angenommen, du möchtest nach Benutzern suchen, deren Name genau "Alice" ist. Du kannst mode.name auf exakte Übereinstimmung setzen.

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

Du wirst feststellen, dass es denselben Effekt hat, wenn du den Modus like (Standard) gegenüber exact angibst. Ein Unterschied ist, dass der Modus exact = zum Vergleichen verwendet, während like like oder ilike nutzt. Theoretisch sollte = eine bessere Performance haben.

Außerdem kannst du im Modus exact mehrere Werte zum Abgleich übergeben, die mit or verbunden werden:

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

Es werden Benutzer mit dem Namen "Alice" ODER "Bob" gefunden.

Standardmäßig ist die Suche nicht groß- / kleinschreibungssensitiv. Um präziser zu sein, setze die Suche auf groß- / kleinschreibungssensitiv:

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

Beachte, dass isCaseSensitive eine globale Konfiguration ist. Daher gilt sie für JEDES Feld.

Regulärer Ausdruck (RegEx)​

PostgreSQL unterstützt zwei Arten von regulären Ausdrücken, similar to und posix. Setze mode auf similar_to oder posix, um mit regulären Ausdrücken zu suchen:

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

Hinweis: Der Modus similar_to funktioniert nur bei groß- / kleinschreibungssensitiven Suchen.

Match-Modus überschreiben​

Standardmäßig übernehmen alle Suchbegriffe den Match-Modus aus der allgemeinen Suche:

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

Um ihn für ein bestimmtes Feld zu überschreiben:

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

Nach externer Identität suchen​

Um den Benutzer zu finden, der mit einer Social- oder Enterprise-SSO-Identität verknüpft ist, übergib die folgenden drei Abfrageparameter gemeinsam für eine exakte Suche:

  • identityType: social für eine Social Connector-Identität oder sso für eine Enterprise SSO-Identität.
  • identityProvider: das Connector-Ziel für eine Social-Identität (zum Beispiel dingtalk) oder der Aussteller für eine Enterprise SSO-Identität.
  • identityId: die vom externen Identitätsanbieter ausgegebene Benutzerkennung.
// Finde den Benutzer, der mit einer DingTalk Social-Identität verknüpft ist
new URLSearchParams([
  ['identityType', 'social'],
  ['identityProvider', 'dingtalk'],
  ['identityId', 'dingtalk-open-id'],
]);
// Finde den Benutzer, der mit einer Enterprise SSO-Identität verknüpft ist
new URLSearchParams([
  ['identityType', 'sso'],
  ['identityProvider', 'https://example.com/issuer'],
  ['identityId', 'enterprise-user-id'],
]);

Der Identitätsfilter wird mit anderen Suchfiltern per UND-Logik kombiniert. Um zum Beispiel die Identitätssuche mit einer Stichwortsuche weiter einzuschränken:

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