メインコンテンツへスキップ
Create Import Users Job エンドポイントを使用すると、ユーザーデータを Auth0 に一括インポートできます。一括インポートは、既存のデータベースやサービスから Auth0 へユーザーを移行する場合に役立ちます。
複数の移行方法 (たとえば、自動移行の後に一括ユーザーインポートを実行するなど) を併用すると、DUPLICATED_USER エラーが発生することがあります。このエラーは、ユーザーが Auth0 の内部ユーザーストアには存在する一方で、テナントには存在しないことを示します。このエラーを解消するには、Auth0 Management API の 接続ユーザーを削除 エンドポイントを使用してそのユーザーを削除してから、インポートを再試行してください。

​
前提条件

ユーザーのインポートジョブを開始する前に、次の準備を行ってください。
  • ユーザーのインポート先となるデータベース接続を設定し、少なくとも 1 つのアプリケーションで有効にします。
  • パスワードをインポートする場合は、サポートされているアルゴリズムのいずれかでハッシュ化されていることを確認してください。サポート対象外のアルゴリズムでハッシュ化されたパスワードを持つユーザーは、一括インポート後の初回ログイン時にパスワードをリセットする必要があります。
  • の登録情報をインポートする場合は、サポートされている種類 (email、phone、totp) であることを確認してください。
  • ジョブエンドポイントへのリクエスト用に Management API トークンを取得します。
Auth0 テナントのエクスポートファイルを使用する場合は、エクスポートしたファイルを ndjson から JSON に変換する必要があります。同じユーザー ID を維持するには、インポートするすべてのユーザー ID から auth0| prefix を削除する必要があります。インポート処理では、インポートしたユーザー ID に auth0| prefix が自動的に追加されます。インポート前に auth0| プレフィックスを削除しない場合、ユーザー ID は auth0|auth0|... として返されます。

​
ユーザー用の JSON ファイルを作成する

Auth0 にインポートするユーザーデータを含む JSON ファイルを作成します。ユーザーデータを JSON ファイルにエクスポートする方法は、既存のユーザーデータベースによって異なります。 エンドポイントは、JSON ファイル全体ではなく、JSON ファイルの各セクションを読み取ることを想定しています。そのため、fs.readFileSync ではなく fs.createReadStream を使用する必要があります。このエンドポイントでは、JSON ファイル全体ではなく、パイプされた読み取りストリームが必要です。 JSON ファイルのスキーマの詳細と例については、Bulk Import Database Schema and Examples を参照してください。
一括インポートのファイルサイズ上限は 500KB です。データがこのサイズを超える場合は、複数回に分けてインポートを開始する必要があります。

​
一括ユーザーインポートをリクエストする

一括ユーザーインポートジョブを開始するには、Create Import Users Job エンドポイントに POST リクエストを送信します。MGMT_API_ACCESS_TOKEN、USERS_IMPORT_FILE.json、CONNECTION_ID、EXTERNAL_ID の各プレースホルダー値は、必ずそれぞれ Management API 、ユーザーの JSON ファイル、データベースの 接続 ID、外部 ID に置き換えてください。
パラメーター説明
usersインポートするユーザーを含む JSON 形式のファイル。
connection_idユーザーの挿入先となる接続の ID。ID は GET /api/v2/connections エンドポイントで取得できます。
upsertブール値。デフォルトは false です。false に設定すると、メールアドレス、ユーザー ID、電話番号、または username が一致する既存ユーザーのインポートは失敗します。true に設定すると、メールアドレスが一致する既存ユーザーは更新されますが、更新できるのは upsert 可能な属性のみです。インポート時に upsert できるユーザープロファイルフィールドの一覧については、User Profile Structure: User profile attributes を参照してください。注: インポートファイルに重複するユーザーエントリが含まれていると、エラーが発生します。この場合、Auth0 は挿入後に更新を行うことはありません。
external_id省略可能なユーザー定義の文字列で、複数のジョブを関連付けるために使用できます。ジョブステータスレスポンスの一部として返されます。
send_completion_emailブール値。デフォルトは true です。true に設定すると、インポートジョブの完了時にすべてのテナント所有者へ完了メールが送信されます。メールを送信したくない場合は、このパラメーターを明示的に false に設定する必要があります。
リクエストが成功すると、次のようなレスポンスが返されます。 
{
  "status": "pending",
  "type": "users_import",
  "created_at": "",
  "id": "job_abc123",
  "connection_id": "CONNECTION_ID",
  "upsert": false,
  "external_id": "EXTERNAL_ID",
  "send_completion_email": true
}
返されるエンティティは、インポートジョブを表します。 ユーザーインポートジョブが完了し、send_completion_email が true に設定されている場合、テナント管理者に、そのジョブの成功または失敗を通知するメールが送信されます。たとえば、失敗したジョブに関するメールでは、ユーザーのインポート時にユーザー JSON ファイルを解析できなかったことが管理者に通知される場合があります。

​
同時実行されるインポートジョブ

Create Import Users Job エンドポイントでは、同時に実行できるインポートジョブは 2 件までです。保留中のジョブが 2 件ある状態でさらにジョブをリクエストすると、429 Too Many Requests レスポンスが返されます。 
{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "There are 2 active import users jobs, please wait until some of them are finished and try again
}

​
ジョブのステータスを確認する

ジョブのステータスを確認するには、Get a Job エンドポイントに GET リクエストを送信します。MGMT_API_ACCESS_TOKEN と JOB_ID のプレースホルダーは、それぞれ Management API アクセストークンとユーザーインポートジョブ ID に置き換えてください。 ユーザーインポートジョブのステータスに応じて、次のいずれかのようなレスポンスが返されます。 保留中 
{
  "status": "pending",
  "type": "users_import",
  "created_at": "",
  "id": "job_abc123",
  "connection_id": "CONNECTION_ID",
  "external_id": "EXTERNAL_ID"
}
完了 ジョブが完了すると、ジョブステータスのレスポンスには、成功、失敗、挿入、更新されたレコードの合計数が含まれます。 
{
  "status": "completed",
  "type": "users_import",
  "created_at": "",
  "id": "job_abc123",
  "connection_id": "CONNECTION_ID",
  "external_id": "EXTERNAL_ID",
  "summary": {
    "failed": 0,
    "updated": 0,
    "inserted": 1,
    "total": 1
  }
}
失敗 ジョブでエラーが発生した場合、ステータスは failed として返されます。ただし、無効なメールアドレスなど、ユーザー情報に不備があっても、ジョブ全体が失敗するわけではありません。 
{
  "status": "failed",
  "type": "users_import",
  "created_at": "",
  "id": "job_abc123",
  "connection_id": "CONNECTION_ID",
  "external_id": "EXTERNAL_ID",
}
失敗したエントリの詳細については、以下の失敗したエントリの取得を参照してください。

​
ジョブのタイムアウト

すべてのユーザーインポートジョブは、2 時間でタイムアウトします。この時間内にジョブが完了しない場合、そのジョブは失敗としてマークされます。 また、ジョブ関連のデータはすべて 24 時間後に自動的に削除され、その後はアクセスできなくなります。そのため、任意のストレージ手段を使用してジョブの結果を保存することを強く推奨します。

​
失敗したエントリを取得する

ジョブ関連のデータはすべて 24 時間後に自動的に削除され、それ以降はアクセスできなくなります。そのため、任意の保存方法を使用してジョブの結果を保存することを強く推奨します。
ユーザーインポートジョブでエラーが発生した場合は、Get Job Error Details エンドポイントに GET リクエストを送信して、エラーの詳細を取得できます。MGMT_API_ACCESS_TOKEN と JOB_ID のプレースホルダーは、それぞれ Management API アクセストークンとユーザーインポートジョブ ID に置き換えてください。 リクエストが成功すると、次のようなレスポンスが返されます。レスポンスでは、hash.value などの機密フィールドはマスクされます。 
[
    {
        "user": {
            "email": "test@test.io",
            "user_id": "7af4c65cb0ac6e162f081822422a9dde",
            "custom_password_hash": {
                "algorithm": "ldap",
                "hash": {
                    "value": "*****"
                }
            }
        },
        "errors": [
            {
                "code": "...",
                "message": "...",
                "path": "..."
            }
        ]
    }
]
各エラーオブジェクトには、エラー code と、エラーの詳細を説明するメッセージが含まれます。想定されるエラー code は次のとおりです。
  • ANY_OF_MISSING
  • ARRAY_LENGTH_LONG
  • ARRAY_LENGTH_SHORT
  • CONFLICT
  • CONFLICT_EMAIL
  • CONFLICT_USERNAME
  • CONNECTION_NOT_FOUND
  • DUPLICATED_USER
  • ENUM_MISMATCH
  • FORMAT
  • INVALID_TYPE
  • MAX_LENGTH
  • MAXIMUM
  • MFA_FACTORS_FAILED
  • MIN_LENGTH
  • MINIMUM
  • NOT_PASSED
  • OBJECT_REQUIRED
  • PATTERN

​
大規模移行のベストプラクティス

多数のユーザーをインポートする場合 (10 件以上のジョブが必要な場合) は、移行を成功させるために次の推奨事項に従ってください。

​
ファイルサイズとチャンク化

ユーザーレコードは、1ファイルあたり400KB未満の小さなチャンクに分割してください。こうすることで、500KBのファイルサイズ上限を十分下回りつつ、ユーザーごとのメタデータフィールド数が10未満であれば、1ジョブあたり約1,000ユーザーを処理できます。

​
ジョブのスケジューリングと同時実行

Auth0 では、ユーザーのインポートはテナントごとに同時に実行できるジョブ数が 2 つまでに制限されているため、ジョブスケジューラーフレームワーク (Bull や Agenda など) を使用して、次を行います。
  • インポートジョブを計画的にスケジュールする
  • 必要な同時実行数の上限を適用する
  • 中断された場合に途中から再開できるよう、インポートの進行状況を追跡する
  • ジョブの履歴と現在のステータスを維持する

​
エラー処理戦略

  • 1 人のユーザーの失敗でインポート処理を中断しないでください。すべてのユーザーをインポートし、問題は後で対処します。
  • 生成されたすべてのジョブを確認し、失敗したレコードを新しいファイルにまとめる「finalizer」ジョブを実装します。
  • 収集した失敗レコードのエラーを修正し、新しいジョブとしてインポートします。
  • ネットワーク接続の切断や一時的な障害に対処できるよう、再試行戦略を含めます。

​
Upsert モードに関する注意事項

upsert モードを有効にする際は注意してください。
  • upsert を使用したインポートは、標準のインポートよりも低速です。
  • Upsert モードでは、user_metadata や app_metadata のマージはサポートされません。既存のメタデータは新しい値で完全に上書きされます。
  • Upsert モードは、既存のユーザーを更新する必要があり、これらの制限を理解している場合にのみ使用してください。

​
データ保持期間

ジョブ関連のデータは、24時間後にすべて自動的に削除されることに注意してください。長期的な追跡や分析を行う場合は、ジョブの結果とエラーの詳細を独自のストレージ機構に保存してください。

​
詳細情報