本页面介绍了如何在调用 Manager API 的端点时使用分页和跟踪。
分页
Manager API 的大多数端点都支持分页。如需了解例外情况,请参阅跟踪端点以获取更新后的记录。
设置页面大小
默认情况下,Manager API 端点会返回包含 100 条记录的页面。您可以使用 per 查询参数更改此数量,最多可更改为 100。较大的值会缩减为 100。
如需设置页面大小,请使用以下端点:
/manager/api/v1/agents?per=50
这会将页面大小设置为 50 条记录。
请求特定页面
您可以使用 page 查询参数请求特定页面的记录。
如需请求特定页面,请使用以下端点:
/manager/api/v1/agents?page=2
这将返回第二页记录
获取所有可用记录
默认情况下,Manager API 会在响应页面中返回 100 条记录,但您可以通过设置页面大小来更改页面中的记录数。对于支持分页的端点,响应标头包含可用记录的总数。如果该数量超过了您的页面大小,您需要多次调用 API 才能获取所有记录。对于支持分页的端点,响应包含遵循 RFC 5988 的 Link 标头。只要有更多记录可用,就会显示 rel="next" 链接,而 rel="last" 链接会显示最后一页的页码。响应还包含 Total 和 Per-Page 标头。
如需获取所有可用记录,请执行以下操作:
调用支持分页的 Manager API 端点。如需了解详情,请参阅分页。响应标头会指明要返回的记录数。
将要返回的记录数与页面大小进行比较。如果要返回的记录数小于页面大小,则所有记录都已返回。否则,请继续执行下一步。
再次调用该端点,并指定下一页记录。如需了解详情,请参阅请求特定页面。重复此步骤,直到返回所有记录。
跟踪端点以获取更新后的记录
Google 建议不要对通话、聊天和客服人员活动 API 端点使用分页,因为我们无法保证最佳结果。相反,我们建议您跟踪这些 API 端点以获取更新后的记录。跟踪 API 端点意味着持续调用该端点,以获取自上次请求以来新增或更新的记录。
跟踪 Calls API 端点
每当通话记录被修改时,其 updated_at 时间戳都会更新。您可以使用时间戳指定在调用 Calls API 端点时要检索的通话记录。
如需每 60 分钟跟踪一次 Calls API 端点,请按以下步骤操作:
向 Calls API 端点 (
/manager/api/v1/calls) 发出请求,并指定以下查询参数:updated_at[from]。指定您希望获取在此时间或之后更新的记录。sort_column。指定要作为记录排序依据的字段。sort_direction。指定响应中记录的排序方向。
以下是使用
curl命令的 Bash 脚本示例:# 1. Define your environment variables (usually set in your shell or .env file) export API_HOSTNAME="ccaip-host.uc1.ccaiplatform.com/" export API_USER="ccaip-host" export API_PASS="CCAI Platform API Key" # 2. Calculate the timestamp for 60 minutes ago in ISO 8601 format (UTC) # For macOS (BSD date): # TIMESTAMP=$(date -v-60M -u +"%Y-%m-%dT%H:%M:%SZ") # For Linux (GNU date): TIMESTAMP=$(date --date='60 minutes ago' -u +"%Y-%m-%dT%H:%M:%SZ") # 3. Execute the curl command # -u handles the Base64 encoding for Basic Auth automatically curl -g -u "${API_USER}:${API_PASS}" \ "https://${API_HOSTNAME}/manager/api/v1/calls?updated_at[from]=${TIMESTAMP}&sort_column=updated_at&sort_direction=asc" | jqCalls API 会返回类似于如下所示的响应:
[ { "id": 100, ... "updated_at": "2025-01-01T00:00:00Z" }, { "id": 98, ... "updated_at": "2025-01-02T00:00:00Z" }, { "id": 150, ... "updated_at": "2025-01-03T00:00:00Z" } ]系统会返回在您指定的时间戳当天或之后更新的响应对象,并按日期升序排序。在下次调用端点时,请使用此响应中最后一个对象的时间戳
updated_at。from过滤条件是包含性的,因此下一个响应会重复该时间戳处的记录。对记录 ID 进行去重,或记录在该时间戳已处理的 ID 并跳过它们。60 分钟后调用 Call API 端点。系统会返回自您上次请求以来更新的通话记录。
重复上一步,继续跟踪端点。
跟踪 Chats API 端点
在下次调用端点时,请使用此响应中最后一个对象的 updated_at 时间戳。updated_at[from] 过滤条件是包含性的,因此下一个响应会重复该时间戳处的记录。根据记录 ID 进行去重,或记录已在该时间戳处理的 ID 并跳过它们。
每当修改聊天记录时,其 updated_at 时间戳都会更新。您可以使用时间戳指定在调用 Chats API 端点时要检索的聊天记录。
如需每 60 分钟跟踪一次 Chats API 端点,请按以下步骤操作:
向 Chats API 端点 (
/manager/api/v1/chats) 发出请求,并指定以下查询参数:updated_at[from]。指定您希望获取在此时间或之后更新的记录。sort_column。指定要作为记录排序依据的字段。sort_direction。指定响应中记录的排序方向。
以下是使用
curl命令的 Bash 脚本示例:# 1. Define your environment variables (usually set in your shell or .env file) export API_HOSTNAME="ccaip-host.uc1.ccaiplatform.com/" export API_USER="ccaip-host" export API_PASS="CCAI Platform API Key" # 2. Calculate the timestamp for 60 minutes ago in ISO 8601 format (UTC) # For macOS (BSD date): # TIMESTAMP=$(date -v-60M -u +"%Y-%m-%dT%H:%M:%SZ") # For Linux (GNU date): TIMESTAMP=$(date --date='60 minutes ago' -u +"%Y-%m-%dT%H:%M:%SZ") # 3.. Execute the curl command # -u handles the Base64 encoding for Basic Auth automatically curl -g -u "${API_USER}:${API_PASS}" \ "https://${API_HOSTNAME}/manager/api/v1/chats?updated_at[from]=${TIMESTAMP}&sort_column=updated_at&sort_direction=asc" | jqChats API 会返回类似于如下所示的响应:
[ { "id": 100, ... "updated_at": "2025-01-01T00:00:00Z" }, { "id": 98, ... "updated_at": "2025-01-02T00:00:00Z" }, { "id": 150, ... "updated_at": "2025-01-03T00:00:00Z" } ]系统会返回在指定时间戳当天或之后更新的响应对象,并按日期升序排序。在下次调用端点时,请使用此响应中最后一个对象的
updated_at时间戳作为时间戳。60 分钟后再次调用 API 端点。系统会返回自您上次请求以来更新的聊天记录。
重复上一步,继续跟踪端点。
跟踪 Agent Activity API 端点
与 Chat 和通话记录不同,代理活动日志不会更新,因此没有 updated_at 时间戳。您可以使用 started_at 时间戳指定在调用 Agent Activity API 端点时要检索的活动记录。started_at[from] 过滤条件是包含性的,因此下一个响应会重复该时间戳处的记录。对记录 ID 进行去重,或记录已在该时间戳处理的 ID 并跳过它们。
如需每 60 分钟跟踪一次 Agent Activity API 端点,请按以下步骤操作:
向 Agent Activity API 端点 (
/manager/api/v1/agent_activity_logs) 发出请求,并指定以下查询参数:started_at[from]。指定您希望获取在此时间或之后开始的活动日志。ended_at[from]。指定您希望获取在此时间或之后结束的活动日志。请使用此字段(而非started_at[from])来捕获在时间范围之前开始但在时间范围内结束的会话。page。添加此参数,以便响应返回分页标头。如果没有page,响应将限制为默认页面大小(100 条记录),而不返回Link、Total或Per-Page标头。sort_column。指定要作为记录排序依据的字段。sort_direction。指定响应中记录的排序方向。
以下是使用
curl命令的 Bash 脚本示例:# 1. Define your environment variables (usually set in your shell or .env file) export API_HOSTNAME="ccaip-host.uc1.ccaiplatform.com" export API_USER="ccaip-host" export API_PASS="CCAI Platform API Key" # 2. Calculate the timestamp for 60 minutes ago in ISO 8601 format (UTC) # For macOS (BSD date): # TIMESTAMP=$(date -v-60M -u +"%Y-%m-%dT%H:%M:%SZ") # For Linux (GNU date): TIMESTAMP=$(date --date='60 minutes ago' -u +"%Y-%m-%dT%H:%M:%SZ") # 3. Execute the curl command # -u handles the Base64 encoding for Basic Auth automatically curl -g -u "${API_USER}:${API_PASS}" \ "https://${API_HOSTNAME}/manager/api/v1/agent_activity_logs?started_at[from]=${TIMESTAMP}&sort_column=started_at&sort_direction=asc" | jqAgent Activity API 会返回类似于如下所示的响应:
[ { "id": 100, ... "started_at": "2025-01-01T00:00:00Z" }, { "id": 98, ... "started_at": "2025-01-02T00:00:00Z" }, { "id": 150, ... "started_at": "2025-01-03T00:00:00Z" } ]系统会返回在指定时间戳或之后开始的响应对象,并按日期升序排序。在下次调用端点时,请使用此响应中最后一个对象的
started_at时间戳作为时间戳。60 分钟后再次调用 Agent Activity API 端点。系统会返回自您上次请求以来更新的代理活动日志记录。
重复上一步,继续跟踪端点。