GET /api/v2/usersエンドポイントを使うと、ユーザーのリストを取得できます。このエンドポイントを使用すると、次の操作を実行できます。
- さまざまな基準に基づいて検索する
- 返されるフィールドを選択する
- 返された結果を並べ替える
要求例
ユーザーを検索するには、/api/v2/usersエンドポイントにGET要求を送信します。要求にはManagement APIのアクセストークンが含まれている必要があります。検索クエリをqパラメータに渡し、search_engineパラメータをv3に設定します。
たとえば、メールアドレスがjane@exampleco.comと完全一致するユーザーを検索するには、q=email:"jane@exampleco.com"を使用します。
成功すると、次のような応答を受け取ります。
クエリの例
以下の例は、を使用して実行できるクエリの種類を紹介するものです。制限事項
エンドポイントは、クエリに一致するユーザーがさらにいる場合でも、最大50人のユーザーを返します。 50人を超えるユーザーを返す必要がある場合は、pageパラメータを使用して、より多くの結果ページを表示します。各ページには50人のユーザーが含まれます。たとえば、&page=2を指定して51～100人目の結果を表示し、&page=3を指定して101～150人目の結果を表示するなどできます。ただし、このエンドポイントは、ページを使用しても、同じ検索条件で合計1000人を超えるユーザーを返すことはありません。
ユーザー検索エンドポイントでインデックス作成、クエリ、返却できるユーザーデータには1ユーザーあたり1MBの制限があります。1MBを超えるカスタムメタデータにこれがどのように影響するかについては、「メタデータフィールド名とデータタイプ」を参照してください。オーバーサイズのユーザープロファイルについては、すべてのユーザー属性を取得するために、ユーザー取得エンドポイントを使用する必要があります。
すべてのユーザーを完全にエクスポートする必要がある場合は、エクスポートジョブまたはユーザーインポート/エクスポート拡張機能を使用します。
エラー414 Request-URI Too Large（要求のURIが長すぎる）が発生した場合は、クエリ文字列がサポートされている長さを超過していることを意味します。その場合には、検索を絞り込みます。
このエンドポイントを次の目的に使用することはお勧めしません 。
- 即時一貫性が必要な操作。代わりに、メールでのユーザー取得エンドポイントまたはIDでのユーザー取得エンドポイントを使用してください。
- ユーザーのエクスポート。代わりに、ユーザーエクスポートエンドポイントを使用してください。
- 認証プロセスの一部としてユーザー検索が必要な操作。代わりに、メールでのユーザー取得エンドポイントまたはIDでのユーザー取得エンドポイントを使用してください。
- メールでのアカウントリンクのユーザー検索。代わりに、メールでのユーザー取得エンドポイントを使用してください。