ユーザー管理エンドポイントの一括処理

一括管理 API エンドポイントを使用すると、一括ユーザー管理コレクションを通じて多数のユーザーを作成または更新できます。

この API は JSON ファイルの使用をサポートしています。テンプレート API を使用して JSON データを取得できます。

api_user 認証のみがサポートされています。API ユーザー トークンはパスワード変数に入力する必要があります。会社のシークレットを使用する以前の認証はサポートされていません。

アップロード API を介して JSON ファイルがアップロードされると、ジョブが作成され、JSON ファイルのスキーマが検証されます。

ユーザーの一括管理でサポートされているエンドポイントは次のとおりです。

バルクユーザー API を使用してユーザーの一括追加または更新を行う手順は次のとおりです。

  1. Template メソッドを呼び出して、JSON ファイルの生成に使用する JSON テンプレート オブジェクトを取得します。

  2. 一括追加を行うか一括更新を行うかに応じて、ファイルからユーザーを一括追加するメソッドまたはファイルからユーザーを一括更新するメソッドのいずれかを呼び出します。これにより、指定した JSON ファイルのスキーマが検証されます。

  3. JSON ファイルのスキーマが検証されたら、Proceed メソッドを呼び出します。これでジョブが開始されます。

  4. ジョブのステータスを確認するには、Jobs メソッドを呼び出します。

JSON ファイル形式

JSON ファイル形式を取得するには、テンプレート メソッドを呼び出します。

フィールド名 値 必須 検証
メール String(Email) ○ 有効なメールアドレスを入力してください。メールアドレスの列内で一意である必要があります（重複不可）。つまり、ファイルごとにメールアドレス 1 つにつき 1 回のみ更新できます。
new_email String(Email) × 有効なメールアドレスを入力してください。[New Email] 列のファイル内で一意である必要があります（重複不可）。つまり、ファイルごとにメールアドレス 1 つにつき 1 回のみ更新できます。
agent_number 文字列 × 検証なしの文字列
first_name 文字列 ○ 空でない文字列
last_name 文字列 ○ 空でない文字列
ステータス Active、Inactive、Empty × 「Active」、「Inactive」、または空である必要があります
ロケーション 場所の名前を表す文字列、空、Null × 既存の場所のいずれかと完全に一致している（大文字と小文字を区別しない）、Null、または空である必要があります
max_chat_limit 1 ～ X（X は構成された値）、空 × 1 ～ X（両端を含む）にするか、空にする必要があります
max_chat_limit_enabled 0、1、Empty × 0、1、または空にする必要があります
ロール name: ロール名 / value: 0、1、空 × 0、1、または空にする必要があります
チーム間の連携を促進する name: Team name / value: 0, 1, Empty × 0、1、または空にする必要があります

JSON ファイル アップロード API メソッドが成功すると、Proceed API メソッドを呼び出すことができ、ユーザーの作成または変更作業が処理されます。

アップロードと続行のメソッドは、Contact Center AI Platform（CCAI Platform）によって非同期で実行されます。ステータスを確認するには、jobs メソッドを呼び出して job_id を指定します。

ステータス フィールド

ジョブの status フィールドには、次のいずれかの値を指定できます。

ジョブ ステータス 説明
created ジョブが作成され、検証を待機しています。
valid_scheme スキームの検証に成功し、続行できます。
invalid_scheme スキームの検証に失敗しました。詳細情報は、Scheme エラーログ API で確認できます。
in_progress ユーザーの一括更新/作成を実行しています。
終了 ユーザーの一括更新/作成が完了しました。

テンプレート

エンドポイント:

Method: GET
Type: 
URL: https://{​subdomain}​.{​domain​}/apps/api/v1/bulk/users/template

リクエストとレスポンスの例

以降のセクションでは、エンドポイントに対するリクエストの例を示します。

テンプレートを取得する

この例では、テンプレートを取得する方法を示します。

リクエスト

本文: なし

回答: テンプレート
[
    {
        "email": "user1@somedomain.com",
        "new_email": "user1@somedomain.com",
        "agent_number": "A-001",
        "first_name": "James",
        "last_name": "Bond",
        "status": "Active",
        "location": "Mexico",
        "max_chat_limit": "2",
        "max_chat_limit_enabled": "0",
        "roles": [
            {
                "name": "Admin",
                "value": 0
            },
            {
                "name": "Manager",
                "value": 0
            },
            {
                "name": "Agent",
                "value": 0
            },
            {
                "name": "Developer",
                "value": 0
            },
            {
                "name": "Manager Admin",
                "value": 0
            },
            {
                "name": "Manager Team",
                "value": 0
            },
            {
                "name": "Manager Data",
                "value": 0
            }
        ],
        "teams": [
            {
                "name": "test team_1",
                "value": 0
            },
            {
                "name": "test Team 2",
                "value": 0
            },
            {
                "name": "test team 3",
                "value": 0
            }
        ]
    },
    {
        "email": "user2@somedomain.com",
        "new_email": "user3@somedomain.com",
        "agent_number": "A-002",
        "first_name": "John",
        "last_name": "Doe",
        "status": "Inactive",
        "location": "",
        "max_chat_limit": "",
        "max_chat_limit_enabled": "1",
        "roles": [
            {
                "name": "Admin",
                "value": 0
            },
            {
                "name": "Manager",
                "value": 0
            },
            {
                "name": "Agent",
                "value": 0
            },
            {
                "name": "Developer",
                "value": 0
            },
            {
                "name": "Manager Admin",
                "value": 0
            },
            {
                "name": "Manager Team",
                "value": 0
            },
            {
                "name": "Manager Data",
                "value": 0
            }
        ],
        "teams": [
            {
                "name": "test team_1",
                "value": 0
            },
            {
                "name": "test Team 2",
                "value": 0
            },
            {
                "name": "test team 3",
                "value": 0
            }
        ]
    },
    {
        "email": "user3@somedomain.com",
        "new_email": "user2@somedomain.com",
        "agent_number": "A-003",
        "first_name": "Jane",
        "last_name": "Doe",
        "status": "",
        "location": "null",
        "max_chat_limit": "1",
        "max_chat_limit_enabled": "",
        "roles": [
            {
                "name": "Admin",
                "value": 0
            },
            {
                "name": "Manager",
                "value": 0
            },
            {
                "name": "Agent",
                "value": 0
            },
            {
                "name": "Developer",
                "value": 0
            },
            {
                "name": "Manager Admin",
                "value": 0
            },
            {
                "name": "Manager Team",
                "value": 0
            },
            {
                "name": "Manager Data",
                "value": 0
            }
        ],
        "teams": [
            {
                "name": "test team_1",
                "value": 0
            },
            {
                "name": "test Team 2",
                "value": 0
            },
            {
                "name": "test team 3",
                "value": 0
            }
        ]
    }
]

ステータス コード: 200

ジョブ

エンドポイント:

Method: GET
Type: 
URL: https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/bulk/users/jobs/{job_id}​

リクエストとレスポンスの例

以降のセクションでは、エンドポイントに対するリクエストの例を示します。

ジョブの詳細

この例では、特定のジョブのジョブの詳細を取得する方法を示します。この例では、ジョブ ID は 1 です。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

クエリ:

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
レスポンス: ジョブの詳細
{
    "id": 1,
    "created_at": "2022-01-07T06:06:45.000Z",
    "process_requested_at": null,
    "filename": "100row.csv",
    "total_rows": 100,
    "affected_rows": 0,
    "failed_rows": 0,
    "status": "created",
    "uploaded_user_name": null,
    "proceed_user_name": null,
    "uploaded_api_user_name": "zdco_admin",
    "proceed_api_user_name": null,
    "scheme_errors": [],
    "update_errors": []
}

ステータス コード: 200

ジョブリスト

この例では、すべてのジョブを取得する方法を示します。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

クエリ:

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/
レスポンス: ジョブリスト
[
    {
        "id": 3,
        "created_at": "2022-01-07T06:21:10.000Z",
        "process_requested_at": "2022-01-07T06:22:25.000Z",
        "filename": "100row_new.csv",
        "total_rows": 100,
        "affected_rows": 0,
        "failed_rows": 0,
        "status": "in_progress",
        "uploaded_user_name": null,
        "proceed_user_name": null,
        "uploaded_api_user_name": "zdco_admin",
        "proceed_api_user_name": "zdco_admin",
        "scheme_errors": [],
        "update_errors": []
    },
    {
        "id": 2,
        "created_at": "2022-01-07T06:17:09.000Z",
        "process_requested_at": null,
        "filename": "100row.csv",
        "total_rows": 100,
        "affected_rows": 0,
        "failed_rows": 0,
        "status": "created",
        "uploaded_user_name": null,
        "proceed_user_name": null,
        "uploaded_api_user_name": "zdco_admin",
        "proceed_api_user_name": null,
        "scheme_errors": [],
        "update_errors": []
    },
    {
        "id": 1,
        "created_at": "2022-01-07T06:06:45.000Z",
        "process_requested_at": null,
        "filename": "100row.csv",
        "total_rows": 100,
        "affected_rows": 0,
        "failed_rows": 0,
        "status": "created",
        "uploaded_user_name": null,
        "proceed_user_name": null,
        "uploaded_api_user_name": "zdco_admin",
        "proceed_api_user_name": null,
        "scheme_errors": [],
        "update_errors": []
    }
]

ステータス コード: 200

ジョブが作成されました

この例では、作成された一括ユーザー リクエスト ジョブを取得する方法を示します。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

クエリ:

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
レスポンス: ジョブが作成されました
{
    "id": 1,
    "created_at": "2022-01-07T06:39:59.000Z",
    "process_requested_at": null,
    "filename": "100row_new.csv",
    "total_rows": 100,
    "affected_rows": 0,
    "failed_rows": 0,
    "status": "created",
    "uploaded_user_name": null,
    "proceed_user_name": null,
    "uploaded_api_user_name": "zdco_admin",
    "proceed_api_user_name": null,
    "scheme_errors": [],
    "update_errors": []
}

ステータス コード: 200

ジョブの検証が成功しました

この例では、ジョブが成功したことを検証する方法を示します。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

クエリ:

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
レスポンス: ジョブの検証が成功しました
{
    "id": 1,
    "created_at": "2022-01-07T06:40:34.000Z",
    "process_requested_at": null,
    "filename": "100row_new.csv",
    "total_rows": 100,
    "affected_rows": 0,
    "failed_rows": 0,
    "status": "valid_scheme",
    "uploaded_user_name": null,
    "proceed_user_name": null,
    "uploaded_api_user_name": "zdco_admin",
    "proceed_api_user_name": null,
    "scheme_errors": [],
    "update_errors": []
}

ステータス コード: 200

ジョブの検証が失敗する

この例では、失敗したジョブを特定する方法を示します。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

クエリ:

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
回答: ジョブの検証に失敗する
{
    "id": 1,
    "created_at": "2022-01-07T06:40:34.000Z",
    "process_requested_at": null,
    "filename": "100row_new.csv",
    "total_rows": 100,
    "affected_rows": 0,
    "failed_rows": 0,
    "status": "invalid_scheme",
    "uploaded_user_name": null,
    "proceed_user_name": null,
    "uploaded_api_user_name": "zdco_admin",
    "proceed_api_user_name": null,
    "scheme_errors": [
        "scheme error detail 1",
        "scheme error detail 2",
        "scheme error detail 3"
    ],
    "update_errors": []
}

ステータス コード: 200

ジョブの更新

この例では、更新中のジョブを特定する方法を示します。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

クエリ:

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
レスポンス: ジョブの更新
{
    "id": 1,
    "created_at": "2022-01-07T06:40:34.000Z",
    "process_requested_at": "2022-01-07T06:42:59.000Z",
    "filename": "100row_new.csv",
    "total_rows": 100,
    "affected_rows": 52,
    "failed_rows": 0,
    "status": "in_progress",
    "uploaded_user_name": null,
    "proceed_user_name": null,
    "uploaded_api_user_name": "zdco_admin",
    "proceed_api_user_name": "zdco_admin",
    "scheme_errors": [],
    "update_errors": []
}

ステータス コード: 200

エラーなしでジョブの更新が完了する

この例では、エラーなしで完了したジョブを特定する方法を示します。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

クエリ:

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
レスポンス: エラーなしでジョブの更新が完了しました
{
    "id": 1,
    "created_at": "2022-01-07T06:40:34.000Z",
    "process_requested_at": "2022-01-07T06:42:59.000Z",
    "filename": "100row_new.csv",
    "total_rows": 100,
    "affected_rows": 100,
    "failed_rows": 0,
    "status": "finished",
    "uploaded_user_name": null,
    "proceed_user_name": null,
    "uploaded_api_user_name": "zdco_admin",
    "proceed_api_user_name": "zdco_admin",
    "scheme_errors": [],
    "update_errors": []
}

ステータス コード: 200

ジョブの更新がエラーで終了する

この例では、エラーで終了したジョブを特定する方法を示します。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

クエリ:

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
レスポンス: ジョブの更新がエラーで終了しました
{
    "id": 1,
    "created_at": "2022-01-07T06:40:34.000Z",
    "process_requested_at": "2022-01-07T06:42:59.000Z",
    "filename": "100row_new.csv",
    "total_rows": 100,
    "affected_rows": 100,
    "failed_rows": 0,
    "status": "finished",
    "uploaded_user_name": null,
    "proceed_user_name": null,
    "uploaded_api_user_name": "zdco_admin",
    "proceed_api_user_name": "zdco_admin",
    "scheme_errors": [],
    "update_errors": [
        "update error detail 1",
        "update error detail 2",
        "update error detail 3"
    ]
}

ステータス コード: 200

エラー: 無効なジョブ ID

この例は、ジョブ ID が無効な失敗リクエストを示しています。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

クエリ:

Method: GET
Type: 
URL: https://{subdomain}.{domain}/apps/api/v1/bulk/users/jobs/1
レスポンス: エラー: ジョブ ID が無効です
{
    "message": "Not Found"
}

ステータス コード: 404

ファイルからユーザーを一括で追加、編集する

ヘッダー:

キー 値 説明
Content-Type multipart/form-data

エンドポイント:

Method: POST
Type: FORM DATA
URL: https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/bulk/users/upload

本文:

キー 値 説明
ファイル

リクエストとレスポンスの例

以降のセクションでは、エンドポイントに対するリクエストの例を示します。

ジョブが作成されました

この例では、ジョブを送信する方法を示します。

リクエスト

本文:

キー 値 説明
ファイル
レスポンス: ジョブが作成されました
{
    "id": 1,
    "status": "created",
    "link": "https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/bulk/users/jobs/1"
}

ステータス コード: 200

続行

この API エンドポイントは、開始された ipport ジョブを続行するために使用されます。

エンドポイント:

Method: POST
Type: FORM DATA
URL: https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/bulk/users/proceed

ヘッダー:

キー 値 説明
Content-Type multipart/form-data

本文:

キー 値 説明
id `[job_id}`

リクエストとレスポンスの例

以降のセクションでは、エンドポイントに対するリクエストの例を示します。

Proceed success

この例は、成功したジョブの進行状況を示しています。

リクエスト

ヘッダー:

キー 値 説明
Content-Type multipart/form-data

クエリ:

キー 値 説明
id `[job_id}`
レスポンス: Proceed success
{
    "id": 1,
    "status": "valid_scheme",
    "link": "https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/bulk/users/jobs/1"
}

ステータス コード: 200

エラー: 検証前に続行

この例では、検証が完了する前に続行しています。

リクエスト

ヘッダー:

キー 値 説明
Content-Type multipart/form-data

クエリ:

キー 値 説明
id `[job_id}`
レスポンス: エラー: 検証前に続行
{
    "message": "This job cannot proceed update. status: created"
}

ステータス コード: 400

エラー: 進行中の場合は続行

この例は、ジョブがすでに処理中の場合に続行する方法を示しています。

リクエスト

ヘッダー:

キー 値 説明
Content-Type multipart/form-data

クエリ:

キー 値 説明
id `[job_id}`
レスポンス: エラー: 進行中の場合は続行
{
    "message": "Update is already in progress."
}

ステータス コード: 400

スキームエラー

エンドポイント:

Method: GET
Type: 
URL: https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/bulk/users/errors/scheme/​{job_id}​

リクエストとレスポンスの例

以降のセクションでは、エンドポイントに対するリクエストの例を示します。

スキームエラー

この例では、スキーマ エラーを取得する方法を示します。

リクエスト

本文: なし

レスポンス: スキームエラー
[
    {
        "message": "scheme error message 1",
        "column": null,
        "row": 1
    },
    {
        "message": "scheme error message 2",
        "column": null,
        "row": 2
    }
]

ステータス コード: 200

エラーなし

この例は、エラーのないスキーマエラーを取得する方法を示しています。

リクエスト

本文: なし

レスポンス: エラーなし
[]

ステータス コード: 200

更新エラー

エンドポイント:

Method: GET
Type: 
URL: https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/bulk/users/errors/update/{job_id}​

リクエストとレスポンスの例

以降のセクションでは、エンドポイントに対するリクエストの例を示します。

更新エラー

この例では、更新エラーとともにスキーマ エラーを取得する方法を示します。

リクエスト

本文: なし

レスポンス: 更新エラー
[
    {
        "message": "update error message 1",
        "column": 1,
        "row": 1,
        "error_type": "error"
    },
    {
        "message": "update error message 2",
        "column": null,
        "row": 2,
        "error_type": "error"
    },
    {
        "message": "update warning message 1",
        "column": 3,
        "row": 3,
        "error_type": "warning"
    },
    {
        "message": "update warning message 2",
        "column": null,
        "row": 4,
        "error_type": "warning"
    }
]

ステータス コード: 200

エラーなし

この例は、エラーのないスキーマエラーを取得する方法を示しています。

リクエスト

本文: なし

レスポンス: エラーなし
[]

ステータス コード: 200