Apps API 旨在检索用户配置数据。无论用户的角色或状态如何，您都可以读取所有用户或单个用户的当前用户配置。此输出中包含系统角色和自定义角色。
此端点不同于批量用户上传过程中使用的端点，并提供支持批量操作的必要信息。如需详细了解如何执行批量用户管理流程，请参阅批量用户 管理 API。
API 功能和限制
检索用户数据时，您可以添加参数以根据需要定制 API 响应。支持以下参数：
特定用户
- ID 选项：电子邮件、系统 ID 或自定义用户 ID。用户可以指定一个或多个 ID。如果多个用户 ID 指向同一用户，则该用户在响应中应仅显示一次。
分页
用户可以按分页集检索结果，以便管理大型数据集。 API 响应应指明是否还有其他页面需要检索。
用户可以使用 API 参数请求特定页面的结果。
用户可以指定页面大小。默认页面大小为 100，最大为 1,000。如果提供了特定页码，则请求中不能包含用户 ID。
API 响应包含所有用户个人资料和配置字段，但“状态”字段除外。API 将提供 deactivated_at 字段，而不是“状态”字段。此字段将包含：
活跃用户没有值。
用户停用的日期和时间。
下表列出了将包含在 API 响应中的用户个人资料字段：
表 1. 用户个人资料字段表
| 顺序 | 列类型 | 列数 | 列名称 | 有效值 |
| 1 | 电子邮件 | 1 | 电子邮件 | 电子邮件 |
| 2 | 智能体 ID | 1 | 智能体 ID | 字符串 |
| 3 | 名字 | 1 | 名字 | 字符串 |
| 4 | 姓氏 | 1 | 姓氏 | 字符串 |
| 5 | 别名 | 1 | 别名 | 字符串 |
| 6 | 停用时间 | 1 | 停用时间 | 无值、日期/时间 |
| 7 | 位置 | 1 | 位置 | 表示位置名称的字符串、空（无更改）、Null（移除当前位置）。 |
| 8 | Chat 并发数 | 1 | Chat 并发数 | 1 到 X（其中 X 是配置的值）、空 |
| 9 | Chat 并发状态 | 1 | Chat 并发状态 | 0、1、空 |
| 10 | 无限制的国际通话 | 1 | 无限制的国际通话 | （True/False） |
| 11 | 外部用户 | 1 | 外部用户 | （是/否） |
| 12 | 外部 SIP URI | 1 | 外部 SIP URI | 字符串 |
| 13 | UCaaS 用户名 | 1 | UCaaS 用户名 | 字符串 |
| 14 | 智能体扩展程序 | 1 | 智能体扩展程序 | |
| 15 | 角色 | 多个 | 角色：角色名称 A 角色：角色名称 B 角色：角色名称 C 等 | 0、1、空 |
| 16 | 团队 | 多个 | 团队：团队名称 A、
团队：团队名称 B、 团队：团队名称 C 等 |
0、1、空 |
| 17 | 电话号码 | 多个 | 直接拨入号码：1、
直接拨入号码：2、 直接拨入号码：3 |
E. 164 格式的电话号码 |
| 18 | 过滤条件 | 单个 | 过滤条件 | 字符串 |
| 19 | 过滤条件超时 | 单个 | 过滤条件超时 | 介于 0 到 1,440 之间的数值 |
限制
每个请求仅支持一种类型的用户 ID。
每个 API 请求的 ID 数上限为 1,000。
用户无法在单个 API 请求中同时提供用户 ID 和页码请求。API 将根据请求返回所有用户，最多 1,000 个。
API 错误消息
对于特定场景，API 将提供以下错误消息：
页面大小：“超出最大页面大小请求（最大值为 1,000）”
页面大小（数字输入要求）：“页面大小请求无效；必须 为数值”
用户 ID 和分页请求组合：“不支持用户 ID 和 分页请求组合”
用户 ID（超出）：“超出用户 ID 数上限（最大值为 1,000）”
请求和响应示例
此示例演示了如何检索第一页用户，每页 100 个用户。响应正文包含一个用户对象数组，每个对象都包含详细的用户配置数据。
请求：
Method: GET
Type:
URL: https://{{subdomain}}.{{domain}}/apps/api/v1/users?page=1&per_page=100
响应：
[
{
"email": "email",
"agent_number": "number",
"first_name": "first",
"last_name": "last",
"status": "Active",
"location": "location",
"max_chat_limt": 3,
"max_chat_limit_enabled": true,
"deleted_at": "2024-07-16T15:57:12.000Z",
"ucaas_user_name": "username",
"external_user": true,
"ucaas_sip_uri": "sip uri",
"unrestricted_international_calling": false,
"roles": [
{ "name": "Admin" },
{ "name": "Manager" }
],
"teams": [
{ "name": "name" }
],
"phone_numbers": [
"123-456-7890",
"098-765-4321"
]
},
...
]
此示例演示了如何通过传递电子邮件参数来检索单个用户的详细信息。响应正文包含一个用户对象，其中包含详细的用户配置数据。
请求：
Method: GET
Type:
URL: https://{{subdomain}}.{{domain}}/apps/api/v1/users?email[]=email
响应：
[
{
"email": "email",
"agent_number": "number",
"first_name": "first",
"last_name": "last",
"status": "Active",
"location": "location",
"max_chat_limt": 3,
"max_chat_limit_enabled": true,
"deleted_at": "2024-07-16T15:57:12.000Z",
"ucaas_user_name": "username",
"external_user": true,
"ucaas_sip_uri": "sip uri",
"unrestricted_international_calling": false,
"roles": [
{ "name": "Admin" },
{ "name": "Manager" }
],
"teams": [
{ "name": "name" }
],
"phone_numbers": [
"123-456-7890",
"098-765-4321"
]
}
]