一括ユーザー管理 API

一括ユーザー管理 API を使用すると、JSON ファイルの内容を使用して、1 回のオペレーションで複数のユーザーを作成または変更できます。

アップロードできるレコード数に上限はありませんが、リクエストは小さなバッチで実行することをおすすめします。

このプロセスは、ユーザーの一括管理の手順に沿って、CCAI Platform ポータルでも実行できます。

一括ユーザー同期ツールのリファレンス アプリケーションが提供されています。このアプリケーションは、Google Workspace グループや Microsoft Entra ID などのディレクトリと CCaaS の間でユーザーの同期を行います。このリファレンス アプリケーションは、一括ユーザー管理 API を活用しています。

ロールと権限

  • api_user を作成して Apps API を使用します。

  • api_user にはロールと権限がないため、すべての api_user が bulk_user management を実行できます。

  • api_user を使用する場合は詳細な権限を設定できないため、api_user はすべてのユーザー フィールドにアクセスできます。

API 認証情報を追加する

  1. CCAI Platform ポータルで、[設定] > [デベロッパー設定] > [API 認証情報の管理] に移動します。

  2. [+ Add API Credential] をクリックします。[API 認証情報を追加] メッセージが開きます。

  3. 認証情報の名前を入力します。

  4. [作成] をクリックします。

一括ユーザー管理 API を使用する

バルク ユーザー管理 API を使用するには、2 つの API 呼び出しが必要です。1 つは JSON ファイルをアップロードしてジョブを作成し、もう 1 つはそれを処理します。オプションの API 呼び出しを使用して、ジョブが正しく処理されるようにすることもできます。

  1. 省略可: JSON テンプレートを取得します。これにより、最新のテンプレートが取得されます。これには、前のテンプレートを取得した後に作成された追加のロールやチームが含まれます。この手順をおすすめします。

  2. 省略可: ユーザー構成データを取得します。これにより、ミラーリングするすべてのユーザー（またはメールアドレスを指定した場合は単一のユーザー）のリストが取得されます。

  3. JSON ファイルをアップロードします。ファイルで 1 人または複数のユーザーを追加または更新できます。ジョブ ID をメモしておきます。

  4. JSON ファイルのリクエスト処理。これにより、一括ジョブが開始されます。

  5. 省略可: ステータス チェックを取得します。ジョブ ID を指定して、処理ステータスを確認します。

  6. 省略可: 更新されたジョブリストを取得します。これにより、すべてのユーザーの一括管理ジョブのリストが取得されます。

  7. 省略可: スキーム エラーログを取得します。ジョブ ID を指定して、スキーマ エラーログを取得します。

  8. 省略可: エラーを取得します。エラーを取得します。

json ファイルをアップロードする

用途

json ファイルをアップロードする

URL

apps/api/v1/bulk/users/upload

メソッド

POST / PUT

リクエスト

content-type: multipart/form-data

{
  "id" : {job_id} #optional. Required in case of PUT method.
  "file": {json file}
}

レスポンス

ヘッダー:

Link: http://ujet.co/apps/api/v1/bulk/users_jobs/12345

本文

{
  "id": 12345, # job_id
  "status": "created"
  "link": "http://ujet.co/apps/api/v1/bulk/users_jobs/12345"
}

JSON テンプレートを取得する

用途

テンプレート

URL

apps/api/v1/bulk/users/template

メソッド

GET

リクエスト

（空）

レスポンス

 
[
{
"email":"user1@yourcompany.co",
"new_email":user1@yourcompany.cx",
"agent_number":"A-001",
"first_name":"John",
"last_name":"aa",
"status":"Active",
"location":"Mexico",
"max_chat_limit":2,
"max_chat_limit_enabled":0,
"roles": [
{"name":"Admin","value": 0 },
{"name":"Manager","value": 1 },
{"name":"Agent","value": 0 },
{"name":Developer","value": 1 }
]
},
 ...
]

ユーザーを無効にする

ユーザーを無効にするには、status の値を Inactive に変更します（例: "status":"Inactive"）。

現在の json ファイルの処理をリクエストする

用途

現在の JSON ファイルの処理をリクエストする

URL

/v1/bulk/users/proceed

メソッド

POST

リクエスト

 
{
   "id": 12345  # job_id
}

レスポンス

ヘッダー:

Link: http://ujet.co/apps/api/v1/bulk/users_jobs/12345

本文

1{"id": 12345 # job_id3 "status": "valid_scheme",4 "link": "http://ujet.co/apps/api/v1/bulk/users_jobs/12345"5}

ステータスを確認する

用途

ステータスを確認する

URL

apps/api/v1/bulk/users/jobs/#{job_id}

メソッド

GET

リクエスト

パス変数 - job_id

レスポンス

 
{
    "id": 12345,
    "created_at": "2022-01-07T06:40:34.000Z",
    "process_requested_at": "2022-01-07T06:45:34.000Z",
    "filename": "100row.json",
    "total_rows": 100,
    "affected_rows": 52,
    "failed_rows": 0,
    "status": "in_progress",
    "uploaded_user_name": null,
    "proceed_user_name": null,
    "uploaded_api_user_name": "api_user_name_1",
    "proceed_api_user_name": "api_user_name_2",
    "scheme_errors": []
    "update_errors": []
}

更新されたジョブリストを取得する

用途

更新ジョブのリストを取得する

URL

apps/api/v1/bulk/users/jobs

メソッド

GET

リクエスト

 
{
  "page": 1,
  "per_page": 20
}

レスポンス

ヘッダー

Link: <next link>
Total: 12345
Per-Page: 201

本文

[
    {
        "id": 12345,
        "created_at": "2022-01-07T06:21:10.000Z",
        "process_requested_at": "2022-01-07T06:22:25.000Z",
        "filename": "100row.json",
        "total_rows": 100,
        "affected_rows": 52,
        "failed_rows": 0,
        "status": "in_progress",
        "uploaded_user_name": null,
        "proceed_user_name": null,
        "uploaded_api_user_name": "api_user_name_1",
        "proceed_api_user_name": "api_user_name_2",
        "scheme_errors": [],
        "update_errors": []
    },
    ...
]

注

出力は job_id の逆順に並べ替えられるため、最新のデータが最初に表示されます。

スキーム エラーログを取得する

用途

スキームのエラーログを取得する

URL

/v1/bulk/users/errors/scheme/#{job_id}

メソッド

GET

リクエスト

パス変数 - job_id

レスポンス

content-type: application/json

[
  {
    "message": "Must be a valid email",
    "column": 1,
    "row": null
  },
  {
    "message": "Non-empty string",
    "column": 10,
    "row": 10
  }
]

エラーを取得する

用途

アップデート エラーログを取得する

URL

/v1/bulk/users/errors/update/#{job_id}

メソッド

GET

リクエスト

パス変数 - job_id

レスポンス

content-type: application/json

1[2 {3 "message": "Must be a valid email",4 "column": 1,5 "row": null,6 "error_type": "warning"7 },8 {9 "message": "Non-empty string",10 "column": 10,11 "row": 10,12 "error_type": "error"13 } 14]