メインコンテンツまでスキップ

高度なユーザー検索

Management API を直接利用して、高度なユーザー検索条件を活用できます。

検索リクエストの実行​

ユーザー検索には GET /api/users を使用します。これは他の Management API と同様に認証が必要です。操作方法については Management API との連携 を参照してください。

サンプル​

リクエスト

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

レスポンス

User エンティティの配列が返されます。

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

パラメーター​

検索リクエストは以下のパラメーターキーで構成されます：

  • 検索キーワード: search, search.*
  • フィールドごとの検索モード: mode, mode.*（デフォルト値 'like'、利用可能値 ['exact', 'like', 'similar_to', 'posix']）
  • 結合モード: joint または jointMode（デフォルト値 'or'、利用可能値 ['or', 'and']）
  • 大文字小文字の区別: isCaseSensitive（デフォルト値 false）

この API には ページネーション が有効になっています。

いくつかの例を通して説明します。すべての検索パラメーターは URLSearchParams のコンストラクタ形式で記述します。

警告:

検索モードはデフォルトで like に設定されており、近似文字列検索（「あいまい検索」）を使用します。

注記:

すべてのあいまい検索モードは、各フィールドごとに 1 つの値のみマッチングをサポートします。1 つのフィールドで複数の値をマッチさせたい場合は「exact」モードを使用してください。詳細は 完全一致と大文字小文字の区別 を参照してください。

すべての利用可能なフィールドに対してあいまい検索を行いたい場合は、search キーに値を指定するだけです。内部的には the like operator が使われます：

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

この検索は、ユーザー検索で利用可能なすべてのフィールド（id, primaryEmail, primaryPhone, username, name）を対象にします。

フィールドの指定​

例えば name のみで検索を限定したい場合は、. 記号でフィールドを指定します。名前に foo を含むユーザーを検索するには：

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

ネストされたフィールドはサポートされていないため、search.name.first などはエラーになります。

複数のフィールドを同時に指定することも可能です：

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

これは、名前に foo を含む または メールアドレスが @gmail.com で終わるユーザーを検索します。

結合モードの変更​

すべての条件を満たす結果のみを返したい場合は、結合モードを and に設定します：

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

これは、名前に foo を含み かつ メールアドレスが @gmail.com で終わるユーザーを検索します。

完全一致と大文字小文字の区別​

例えば名前が正確に "Alice" のユーザーを検索したい場合、mode.name を exact に設定します。

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

デフォルトの like モードと exact を指定した場合で同じ効果が得られることもありますが、exact モードは比較に = を使い、like は like または ilike を使います。理論的には = の方がパフォーマンスが良いです。

さらに、exact モードでは複数の値を指定でき、それらは or で結合されます：

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

これは名前が "Alice" または "Bob" のユーザーにマッチします。

デフォルトでは検索は大文字小文字を区別しません。より厳密に検索したい場合は、検索を大文字小文字を区別するように設定できます：

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

isCaseSensitive はグローバル設定であるため、すべてのフィールドに適用されます。

正規表現 (RegEx)​

PostgreSQL では 2 種類の正規表現（similar to と posix）がサポートされています。mode を similar_to または posix に設定することで正規表現検索が可能です：

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

注意 similar_to モードは大文字小文字を区別する検索でのみ動作します。

マッチモードの上書き​

デフォルトでは、すべてのキーワードは一般検索のマッチモードを継承します：

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

特定のフィールドだけ上書きしたい場合：

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

外部アイデンティティによる検索​

ソーシャルまたはエンタープライズ SSO アイデンティティに紐づくユーザーを検索するには、以下の 3 つのクエリパラメーターを同時に指定して完全一致検索を行います：

  • identityType: ソーシャルコネクターアイデンティティの場合は social、エンタープライズ SSO アイデンティティの場合は sso。
  • identityProvider: ソーシャルアイデンティティの場合はコネクターターゲット（例：dingtalk）、エンタープライズ SSO アイデンティティの場合は発行者。
  • identityId: 外部アイデンティティプロバイダーによって発行されたユーザー識別子。
// DingTalk ソーシャルアイデンティティに紐づくユーザーを検索
new URLSearchParams([
  ['identityType', 'social'],
  ['identityProvider', 'dingtalk'],
  ['identityId', 'dingtalk-open-id'],
]);
// エンタープライズ SSO アイデンティティに紐づくユーザーを検索
new URLSearchParams([
  ['identityType', 'sso'],
  ['identityProvider', 'https://example.com/issuer'],
  ['identityId', 'enterprise-user-id'],
]);

アイデンティティフィルターは他の検索フィルターと AND ロジックで組み合わされます。例えば、キーワード検索でさらに絞り込む場合：

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