ユーザーの一括エクスポート

ユーザーのリストとユーザーメタデータをエクスポートする方法を説明します。

POST /api/v2/jobs/users-exports エンドポイントを使用して、接続に関連付けられたすべてのユーザー、またはテナント内のすべてのユーザーをエクスポートするジョブを作成できます。

エクスポート可能なユーザープロフィールのフィールド一覧については、User Profile Structureを参照してください。

ジョブを作成する際は、次の情報を指定する必要があります。

• ユーザーのエクスポート元となる接続の ID (省略可能)
• エクスポートファイルの形式 (CSV または JSON 互換)
• エクスポートするユーザーレコードの最大数 (省略可能。省略した場合はすべてのレコードがエクスポートされます)
• エクスポートに含めるユーザー関連フィールド (ユーザー ID や名前など)

また、有効な Management API アクセストークン も必要です。

​

リクエストボディを作成する

必要に応じて、Auth0 Dashboard で connection_id と Auth0 テナントのドメイン名を確認してください。次に、以下のリクエストボディを記述した新しいテキストファイルを作成してください。

{
   "connection_id":"connection_id",
   "format":"csv",
   "limit":20,
   "fields":[
      {
         "name":"user_id"
      },
      {
         "name":"email"
      },
      {
         "name":"user_metadata.country"
      }
   ]
}

connection_id を使用するデータベース接続IDに更新するか、テナント内のすべてのユーザーをエクスポートする場合は削除してください。

​

リクエストの例

必要なスコープ: read:users

レスポンスは次のようになります。

{
  "type": "users_export",
  "status": "pending",
  "connection_id": "con_0000000000000001",
  "format": "csv",
  "limit": 5,
  "fields": [
    {
      "name": "user_id"
    },
    {
      "name": "name"
    },
    {
      "name": "email"
    },
    {
      "name": "identities[0].connection",
      "export_as": "provider"
    }
  ],
  "connection": "Username-Password-Authentication",
  "created_at": "2017-11-02T23:34:03.803Z",
  "id": "job_coRQCC3MHztpuTlo"
}

​

エクスポートする CSV にユーザーメタデータを含める

ユーザーデータを CSV 形式でエクスポートする際にメタデータ情報も含める場合は、エクスポートする各メタデータフィールドを指定します。エクスポートできるフィールド数は最大 30 個です。

app_metadata または user_metadata 全体を CSV にエクスポートすることはできません。メタデータオブジェクト内のフィールドを明示的に指定する必要があります。

app_metadata または user_metadata を単一のオブジェクトとしてエクスポートするには、JSON互換形式を使用し、リクエスト本文の fields パラメーターに目的のフィールドを含めます。例:

{"name":"app_metadata"}

エクスポートできるフィールド数は最大 30 個までのため、ユーザーデータに多数のフィールドがある場合は JSON 形式の使用を推奨します。

たとえば、メタデータが次のような構造になっている場合:

{
  "consent": {
      "given": true,
      "date": "01/23/2019",
      "text_details": "{yourURL}"
  }
}

3 つのフィールドすべてを対象としたエクスポートリクエストは、次のようになります。

ユーザーエクスポートの CSV ファイルでは、CSV インジェクション対策に関する OWASP 標準に準拠するため、文字列データ型を次のようにエスケープします。

• 二重引用符文字の前に、さらに二重引用符文字を付加します。
• 各文字列の先頭に、単一引用符文字を付加します。
• 各文字列を二重引用符で囲みます。

これは、Auth0 が生成する ISO 8601 形式の日付には適用されません。

​

JSON互換形式

JSON互換形式でデータをエクスポートする場合、指定する必要があるのはルートプロパティだけです。各内部プロパティは自動的に含まれるため、それぞれを個別に指定する必要はありません。

Auth0 のエクスポートファイルはサイズが大きいため、NDJSON 形式を使用します。一方、インポート機能では JSON ファイルが必要です。

Auth0 が生成したエクスポートファイルを使ってユーザーをインポートするには、任意のライブラリ (jq など) を使用して、ファイルを NDJSON から JSON に変換する必要があります。

この場合、前と同じ例を使うと、リクエストは次のようになります。

​

エクスポートステータスを確認する

ユーザーをエクスポートするジョブを作成したら、Get a Job エンドポイントを使用してそのステータスを確認できます。

ジョブのID (ジョブ作成時のレスポンスで受け取ったもの) を指定します。以下のサンプルリクエストを使用する場合は、プレースホルダー {yourJobId} をIDの値に置き換えてください。

必要なスコープ: create:users, read:users, create:passwords_checking_job

次のようなレスポンスが返されます。

{
  "type": "users_export",
  "status": "completed",
  "connection_id": "con_lCvO...a",
  "format": "csv",
  "limit": 5,
  "fields": [
    {
      "name": "user_id"
    },
    {
      "name": "name"
    },
    {
      "name": "email"
    },
    {
      "name": "identities[0].connection",
      "export_as": "provider"
    }
  ],
  "location": "pus3-auth0-export-users-us-east-2.s3.us-east-2.amazonaws.com/job_coRQCC3MHztpuTlo/auth0docs2.csv.gz?Expires=1509725589&Key-Pair-Id=APKAJPL62IJALBDMSSCA&Signature=l2JaFXP~BATnfagb64PK-qbX9QaZREDYNW0q5QeHuV-MaDpZjpABDXfHHLh2SsCMQz~UO-QsCSfI81l0lvCKzZPZL6cZHK7f~ixlZOK~MHKJuvMqsUZMbNluNAwhFmgb2fZ86yrB1c-l2--H3lMELAk7hKUwwSrNBlsfbMgQ-i41nMNnsYdy3AVlNVQkwZyx~w-IEHfJDHsqyjia-jfDbIOLQvr8~D9PwZ-xOzROxDwgxrt3undtz80bkgP5hRKOAbHC7Y-iKWa2bzNZYHqzowTrlh7Ta60cblJR46NfF9cNqn9jqRGVv-lsvUD9FxnImCCk~DL6npJnzNLjHvn4-CaWq6KdQnwWgCnZ3LZkxXDVWLLIQQaoc6i~xbuGnnbtKRePFSnpqbt2mAUYasdxTOWuUVK8wHhtfZmRYtCpwZcElXFO9Qs~PTroYZEiS~UHH5byMLt2x4ChkHnTG7pIhLAHN~bCOLk8BN2lOkDBUASEVtuJ-1i6cKCDqI2Ro9YaKZcCYzeQvKwziX6cgnMchmaZW77~RMOGloi2EffYE31OJHKiSVRK7RGTykaYN5S2Sg7W0ZOlLPKBtCGRvGb8rJ6n3oPUiOC3lSp7v0~dkx1rm-jO8mKWZwVtC0~4DVaXsn8KXNbj0LB4mjKaDHwXs16uH1-aCfFnMK7sZC2VyCU_",
  "connection": "Username-Password-Authentication",
  "created_at": "2017-11-02T23:34:03.803Z",
  "id": "job_coRQCC3MHztpuTlo"
}

​

エクスポートデータを取得する

エクスポートファイルには、location パラメーターの値として提供される URL からアクセスできます。テナント名がそのままファイル名になります。たとえば、テナント名が auth0docs の場合、ファイル名は auth0docs.csv または auth0docs.json になります。URL にアクセスすると、ファイルのダウンロードが自動的に開始されます。

ダウンロードリンクは 60 秒間有効です。この時間を過ぎた場合でも、ジョブの有効期限が切れるまでは、24 時間以内であれば再度 URL を呼び出すことができます。

​

ジョブのクリーンアップ

ジョブ関連のデータはすべて24時間後に自動的に削除され、その後はアクセスできなくなります。そのため、任意の保存先を使用してジョブの結果を保存することを強く推奨します。

​

フィルターの例

エクスポートした .csv ファイルから、アプリケーションへのユーザーの最終ログイン日時など、特定のデータだけを絞り込みたい場合があります。

1. Management API の Create export user’s job エンドポイントに POST リクエストを送信し、ユーザーを .csv ファイルにエクスポートします。

   1. 新しいジョブを作成します。

      curl -L 'https://{account.namespace}/api/v2/jobs/users-exports' \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json' \
      -H 'Authorization: Bearer MGMT_API_TOKEN' \
      -d '{"format":"csv"}'
      

   2. ステータスを確認します。

      curl -L 'https://{account.namespace}/api/v2/jobs/JOB_ID' \
      -H 'Accept: application/json' \
      -H 'Authorization: Bearer MGMT_API_TOKEN'
      

2. ローカルマシンのダウンロードフォルダーにあるファイルを開きます。

3. コマンドラインツールを使用してフィルターを追加します。この例では、Miller を使用します。

   mlr --csv filter '$last_login >= "2024-01-01T00:00:00Z"' file.csv > filtered.csv