大量使用者管理端點

您可以使用大量管理 API 端點，透過大量使用者管理集合建立或更新大量使用者。

API 支援使用 JSON 檔案。您可以使用範本 API 取得 JSON 資料。

系統僅支援 api_user 驗證。您必須在密碼變數中輸入 API 使用者權杖。系統不支援使用公司密鑰的舊版驗證。

透過上傳 API 上傳 JSON 檔案時，系統會建立作業並驗證 JSON 檔案結構定義。

大量使用者管理作業支援的端點包括：

如要使用大量使用者 API 大量新增或更新使用者，請按照下列步驟操作：

  1. 呼叫 Template 方法，取得用於產生 JSON 檔案的 JSON 範本物件。

  2. 視要大量新增或更新使用者而定，呼叫「Bulk add users from file」(從檔案大量新增使用者) 方法或「Bulk update users from file」(從檔案大量更新使用者) 方法。這會驗證您提供的 JSON 檔案結構定義。

  3. 驗證 JSON 檔案結構定義後，請呼叫「Proceed」方法。這會啟動工作。

  4. 如要判斷工作狀態，請呼叫 Jobs 方法。

JSON 檔案格式

您可以呼叫範本方法，取得 JSON 檔案格式。

欄位名稱 值 必填 驗證
電子郵件 字串(電子郵件) 是 必須輸入有效的電子郵件地址。電子郵件地址欄位中的檔案必須是唯一的 (不得重複)，因此每個檔案中每個電子郵件地址只能更新一次
new_email 字串(電子郵件) 否 必須輸入有效的電子郵件地址。在「新電子郵件地址」欄中，每個電子郵件地址必須是唯一的 (不得重複)，因此每個檔案中，每個電子郵件地址只能更新一次
agent_number 字串 否 沒有驗證的字串
first_name 字串 是 非空白字串
last_name 字串 是 非空白字串
狀態 有效、無效、空白 否 必須是「有效」、「無效」或空白
位置 地點名稱字串、空白、空值 否 必須與現有位置完全相符 (不區分大小寫)，或為 Null 或空白
max_chat_limit 1 至 X (其中 X 是設定值)、空白 否 必須介於 1 到 X 之間 (含首尾)，也可以留空
max_chat_limit_enabled 0、1、空白 否 必須為 0、1 或空白
角色 name: Role name / value: 0, 1, Empty 否 必須為 0、1 或空白
團隊 name: Team name / value: 0, 1, Empty 否 必須為 0、1 或空白

JSON 檔案上傳 API 方法成功後，即可呼叫「繼續」API 方法，然後處理使用者建立或修改作業。

上傳和繼續作業是由 Contact Center AI 平台 (CCAI 平台) 執行，您可以呼叫 jobs 方法並指定 job_id，藉此檢查狀態。

狀態欄位

工作 status 欄位可包含下列任一值：

工作狀態 說明
已建立 系統已建立工作，正在等待驗證。
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}`
回應：程序成功
{
    "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