Get Users エンドポイントを使用してユーザー一覧を取得する

get_users エンドポイントを使用してユーザー一覧を取得する方法を説明します。

GET /api/v2/users エンドポイントを使用すると、ユーザーの一覧を取得できます。このエンドポイントでは、次のことが可能です。

• さまざまな条件で検索する
• 返されるフィールドを選択する
• 返される結果を並べ替える

このエンドポイントは結果整合性であるため、既存ユーザーの表示名の変更など、バックオフィス処理に使用することを推奨します。

​

リクエストの例

ユーザーを検索するには、/api/v2/users エンドポイントに GET リクエストを送信します。リクエストには、Management API アクセストークンを含める必要があります。検索クエリは q パラメーターに指定し、search_engine パラメーターは v3 に設定します。

たとえば、メールアドレスが [e-mail] に完全に一致するユーザーを検索するには、q=email:"[e-mail]" を使用します。

成功した場合、次のようなレスポンスが返されます。

[
  {
    "email": "[e-mail]",
    "email_verified": false,
    "username": "janedoe",
    "phone_number": "[phone]",
    "phone_verified": false,
    "user_id": "auth0|5457edea1b8f22891a000004",
    "created_at": "",
    "updated_at": "",
    "identities": [
      {
        "connection": "Initial-Connection",
        "user_id": "5457edea1b8f22891a000004",
        "provider": "auth0",
        "isSocial": false
      }
    ],
    "app_metadata": {},
    "user_metadata": {},
    "picture": "",
    "name": "",
    "nickname": "",
    "multifactor": [
      ""
    ],
    "last_ip": "",
    "last_login": "",
    "logins_count": 0,
    "blocked": false,
    "given_name": "",
    "family_name": ""
  }
]

​

クエリの例

以下に、Management API で実行できるクエリの例を示します。

ユースケース	クエリ
名前に “john” を含むすべてのユーザーを検索する	name:\*john\*
名前が完全に “jane” と一致するすべてのユーザーを検索する	name:"jane"
名前が “john” で始まるすべてのユーザーを検索する	name:john*
名前が “jane” で始まり “smith” で終わるユーザーを検索する	name:jane*smith
メールアドレスが完全に “[e-mail]” と一致するすべてのユーザーを検索する	email:"[e-mail]"
OR を使用して、メールアドレスが完全に “[e-mail]” または “[e-mail]” と一致するすべてのユーザーを検索する	email:("[e-mail]" OR "[e-mail]")
メールアドレスが未検証のユーザーを検索する	email_verified:false OR NOT \_exists_\:email_verified
user_metadata の full_name フィールドの値が “John Smith” であるユーザーを検索する	user_metadata.full_name:"John Smith"
特定の接続のユーザーを検索する	identities.connection:"google-oauth2"
一度もログインしたことがないすべてのユーザーを検索する	(NOT \_exists_\:logins_count OR logins_count:0)
2018 年より前にログインしたすべてのユーザーを検索する	last_login:[* TO 2017-12-31]
最終ログインが 2017 年 12 月だったすべてのユーザーを検索する	last_login:[2017-11 TO 2017-12], last_login:[2017-12-01 TO 2017-12-31]
ログイン回数が >= 100 かつ <= 200 のすべてのユーザーを検索する	logins_count:[100 TO 200]
ログイン回数が >= 100 のすべてのユーザーを検索する	logins_count:[100 TO *]
ログイン回数が > 100 かつ < 200 のすべてのユーザーを検索する	logins_count:\{100 TO 200}
メールアドレスのドメインが “exampleco.com” であるすべてのユーザーを検索する	email.domain:"exampleco.com"

​

制限事項

• クエリに一致するユーザーがさらに存在する場合でも、このエンドポイントが返すユーザーは最大 50 件です。

• 50 件を超えるユーザーを返す必要がある場合は、page パラメーターを使用して結果ページを追加で表示します。各ページには 50 人のユーザーが含まれます。たとえば、&page=2 を指定すると結果 51～100 が表示され、&page=3 を指定すると結果 101～150 が表示されます。以降も同様です。ただし、ページングを使用しても、このエンドポイントが同じ検索条件で合計 1000 人を超えるユーザーを返すことはありません。

• ユーザー検索エンドポイント でインデックス化、クエリ、および返却できるユーザーデータには、ユーザーごとに 1 MB の上限があります。これが 1 MB を超えるカスタムメタデータにどのように影響するかについて詳しくは、Metadata Field Names and Data Types を参照してください。サイズ上限を超えるユーザープロファイルのすべてのユーザー属性を取得するには、get user エンドポイント を使用する必要があります。

• デフォルトでは、GET /api/v2/users エンドポイントは決定的な順序で結果を返すため、同じクエリでは毎回、論理的に同じ順序の結果が返されます。この動作は、primary_order クエリパラメーターで制御されます。

  • primary_order=true (デフォルト): 同一のクエリでは、結果が常に一貫した順序で返されます。
  • primary_order=false: 結果は非決定的な順序で返されるため、複雑なクエリではパフォーマンスが向上する場合があります。

• アプリケーションで検索結果の一貫した順序が不要で、クエリが短くページネーションに依存しない場合は、クエリパフォーマンスを向上させるために primary_order=false を設定してください。

• すべてのユーザーの完全なエクスポートが必要な場合は、export job または User Import / Export 拡張機能を使用してください。

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

このエンドポイントを次の用途に使用することは推奨しません。

• 即時整合性が必要な操作。代わりに、Get Users by Email エンドポイント または Get Users by ID エンドポイント を使用してください。
• ユーザーのエクスポート。代わりに、User Export エンドポイント を使用してください。
• 認証プロセスの一部としてユーザー検索が必要な操作。代わりに、Get Users by Email エンドポイント または Get Users by ID エンドポイント を使用してください。
• メールアドレスによる Account Linking のためのユーザー検索。代わりに、Get Users by Email エンドポイント を使用してください。

​

詳しくはこちら

• ユーザー検索クエリの構文
• 検索結果の並べ替え
• ページ単位での検索結果の表示
• ユーザーの一括エクスポート