批量用户管理端点

借助批量管理 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 否 必须与现有位置（不区分大小写）之一完全一致，或者为 Null 或空
max_chat_limit 1 到 X（其中 X 是配置的值），空 否 必须介于 1 到 X 之间（含边界值），或留空
max_chat_limit_enabled 0、1、空 否 必须为 0、1 或空值
角色 name: 角色名称 / value: 0、1、空 否 必须为 0、1 或空值
teams name: 团队名称 / value: 0、1、空 否 必须为 0、1 或空值

JSON 文件上传 API 方法成功执行后，即可调用 Proceed API 方法，然后系统会处理用户创建或修改工作。

上传和继续方法由 Contact Center AI 平台 (CCAI 平台) 异步执行。您可以通过调用 jobs 方法并指定 job_id 来检查状态。

状态字段

作业 status 字段可以具有以下任意值：

作业状态 说明
已创建 作业已创建，正在等待验证。
valid_scheme 方案验证成功，可以继续。
invalid_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}`
响应：继续成功
{
    "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