検索クエリを使用してユーザーを一覧表示・検索する方法

すべてのユーザープロファイルの一覧を取得し、Lucene 検索クエリ文字列で結果を絞り込みます。

Auth0 Dashboard または Management API を使用すると、ユーザー一覧を取得し、指定した検索条件で結果を絞り込むことができます。

​

ユーザーの一覧表示と検索

Auth0 Dashboard

ユーザーの一覧を表示するには、Auth0 Dashboard > User Management > Usersに移動します。

ページ上部の検索フィールドとドロップダウンメニューで、次のプロパティを指定して検索できます。

• ユーザー
• メール
• アイデンティティプロバイダー
• 接続
• 組織ID
• ログイン回数
• 最終ログイン
• 電話番号

Lucene Syntax (Advanced) を選択して、検索条件を指定することもできます。検索クエリ構文リファレンスでは、サポートされている検索機能とクエリの例について詳しく説明しています。

Management API

Management API の List or Search Users endpoint (GET /users) は最終的整合性 (eventually consistent) であるため、直近に完了した書き込み操作の結果がすぐに反映されない場合があります。既存ユーザーの表示名の変更など、厳密な即時性が求められない操作にはこのエンドポイントの使用を推奨します。

List または Search Users エンドポイントを使用する場合

• このエンドポイントは、authentication プロセスの一環、account linking、または即時整合性が必要な場合には使用しないでください。代わりに、Management API エンドポイントを使用して、ID またはメールアドレスでユーザーを取得してください。

• List または Search Users エンドポイントをユーザーのエクスポートに使用しないでください。代わりに、一括ユーザーエクスポートを使用してください。

Management API ですべてのユーザーを一覧表示するには、List or Search Users endpoint (GET /users) を呼び出します。ユーザーを検索するには、q クエリパラメータとLucene 検索クエリ文字列を使用して検索条件を指定します。

たとえば、名前が example と完全に一致するユーザーを検索するには:

検索クエリが2秒以内に完了しない場合、タイムアウトし (HTTP ステータスコード 503) 、処理が中断されます。検索クエリがタイムアウトする場合、それは処理負荷の高いクエリであるか、時間内に完了しないエラーが含まれている可能性があります。

エラー 414 Request-URI Too Large は、クエリ文字列がサポートされている最大長を超えていることを示します。この場合は、検索条件を絞り込んでください。

検索クエリ構文リファレンスには、サポートされている検索機能とクエリの例に関する詳細が記載されています。

​

結果を並べ替える

Auth0 Dashboard

Auth0 Dashboard では、ユーザー一覧に表示される列を選択して、結果を並べ替えることができます。

• 名前
• ユーザー ID
• 接続
• ログイン数
• 最終ログイン

列の見出しを1回選択すると昇順に、もう一度選択すると降順に並べ替えられます。ほかのフィールドで結果を並べ替えるには、Management API を使用します。

Management API

ユーザー検索結果を並べ替えるには、sort クエリパラメータをfield:orderの値に設定します。各要素は次のとおりです。

• field は並べ替えに使用するフィールド名です
• order は昇順の場合は 1、降順の場合は -1 です。

たとえば、作成日時の昇順でユーザーを並べ替えるには、sort パラメータに created_at:1 を指定します。

​

パフォーマンスに関する推奨事項

ユーザー検索のパフォーマンスを向上させるには、次のガイドラインに従ってください。

• Management API の List または Search Users エンドポイント は、決定論的な順序で結果を返します。そのため、同じクエリでは毎回、論理的に同じ順序の結果が返されます。非決定論的検索の方が高速なため、ユースケースで決定論的検索が不要な場合は、primary_order=false を設定して非決定論的検索を使用してください。

• スペース文字はエスケープしてください (例: q=name:John Doe は q=name:John\ Doe と記述します) 。

• 特に大規模なデータセットでは、ワイルドカードの使用を最小限に抑えてください。ワイルドカードを使用する場合は、検索タームの接頭辞ではなく接尾辞として使用してください。

• 1,000 件を超える結果を返す検索条件は避けてください。

• 存在クエリ (例: 「値にかかわらず、特定のプロパティを持つすべてのユーザーを返す」) は避けてください。

• app_metadata および user_metadata のユーザー定義属性については、次の点に注意してください。

  • メタデータフィールドは 2 KB 以下にしてください。

  • メタデータプロパティには、一貫したデータ型と固定の名前を使用してください。

  • 大きなスキーマや深い構造は避けてください。

• post-login Actions などのログインフローの拡張ポイント内でユーザー検索を行うことは避けてください。

• 検索 API をポーリングしないでください。

​

制限

• 検索では、クエリに一致するユーザーが1,000人を超える場合でも、返されるのは最大1,000人です。API を使用する場合、大量の結果はページネーションされます。

• Management API の List または Search Users エンドポイントでは、インデックス化、クエリ、返却できるユーザーデータのサイズは、ユーザーあたり最大1 MBです。サイズの大きいユーザープロファイルのすべてのユーザー属性を取得するには、ID またはメールアドレスでユーザーを取得してください。

• Management API の List または Search Users エンドポイントでは、app_metadata または user_metadata による並べ替えはサポートされていません。