大量使用者管理 API

您可以使用 Bulk User Management API，透過 JSON 檔案的內容，在單一作業中建立或修改多位使用者。

上傳的記錄數量沒有限制，但建議以較小的批次執行要求。

您也可以在 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 入口網站中，依序前往「Settings」(設定) >「Developer Settings」(開發人員設定) >「API Credential management」(API 憑證管理)。

2. 按一下「+ Add API Credential」(新增 API 憑證)。系統會開啟「新增 API 憑證」訊息。

3. 輸入憑證的名稱。

4. 點選「建立」。

使用大量使用者管理 API

使用大量使用者管理 API 時，需要進行兩次 API 呼叫。其中一個上傳 JSON 檔案並建立工作，另一個則處理該工作。您也可以使用選用的 API 呼叫，確保作業正確處理。

1. 選用：擷取 JSON 範本。這會擷取最新範本，包括您擷取前一個範本後建立的任何其他角色或團隊。Google 建議您採取這項步驟。

2. 選用：取得使用者設定資料。這會擷取所有使用者 (或單一使用者，如果您指定電子郵件地址) 的清單，以進行鏡像作業。

3. 上傳 json 檔案。您可以在檔案中新增或更新一或多位使用者。請務必記下工作 ID。

4. 處理 JSON 檔案的要求。這樣就會啟動大量作業。

5. 選用：查看狀態。提供工作 ID，即可查看處理狀態。

6. 選用：擷取更新的工作清單。這會擷取所有大量使用者管理工作的清單。

7. 選用：擷取架構錯誤記錄。指定工作 ID，即可取得架構錯誤記錄。

8. 選用：擷取錯誤。取得錯誤。

上傳 JSON 檔案

用量	上傳 JSON 檔案
網址	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 範本

用量	範本
網址	apps/api/v1/bulk/users/template
方法	GET
要求	(空白)
回應	[ { "email":"[e-mail]", "new_email":[e-mail]", "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 檔案
網址	/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}

查看狀態

用量	查看狀態
網址	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": [] }

擷取更新後的工作清單

用量	取得更新的工作清單
網址	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 遞減排序，因此最新的資料會顯示在最前面。

擷取架構錯誤記錄

用量	取得架構錯誤記錄
網址	/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 } ]

擷取錯誤

用量	取得更新錯誤記錄
網址	/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]