大量使用者管理端點

您可以使用大量管理 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 檔案格式。

欄位名稱 值 必填 驗證
電子郵件 字串(電子郵件) 是 必須輸入有效的電子郵件地址。電子郵件地址欄位中的檔案必須是唯一的 (不得重複)，因此每個檔案中每個電子郵件地址只能更新一次
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}`

要求和回應範例

下列各節提供端點的要求範例。

繼續操作成功

這個範例顯示成功執行的工作程序。

要求

標題：

鍵 值 說明
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