分页和尾随

本页介绍了在调用管理 API 的端点时如何使用分页和尾随。

分页

经理账号 API 的大多数端点都支持分页。如需了解例外情况，请参阅跟踪端点以获取更新后的记录。

设置页面大小

默认情况下，管理 API 端点会返回包含 100 条记录的页面。您可以使用 per 查询参数更改此数量。

如需设置页面大小，请使用以下端点：

/manager/api/v1/agents?per=50

这会将页面大小设置为 50 条记录。

请求特定网页

您可以使用 page 查询参数请求特定页面的记录。

如需请求特定网页，请使用以下端点：

/manager/api/v1/agents?page=2

此示例会返回第二页记录

获取所有可用记录

默认情况下，管理 API 会在一个响应页面中返回 100 条记录，不过您可以设置页面大小来更改一个页面中的记录数。对于支持分页的端点，响应标头会包含可用的记录总数。如果该数量超过了您的页面大小，您需要多次调用该 API 才能获取所有记录。管理器 API 未明确指明是否还有其他记录要返回。

如需获取所有可用记录，请执行以下操作：

1. 调用支持分页的管理器 API 端点。如需了解详情，请参阅分页。响应标头会指明要返回的记录数。

2. 将要返回的记录数与您的页面大小进行比较。如果要返回的记录数小于您的页面大小，则表示已返回所有记录。否则，请继续下一步。

3. 再次调用该端点，指定下一页记录。如需了解详情，请参阅请求特定页面。重复此步骤，直到返回您的所有记录。

跟踪端点以获取更新后的记录

Google 建议不要对通话、聊天和客服人员活动 API 端点使用分页功能，因为我们无法保证获得最佳结果。我们建议您跟踪这些 API 端点，以获取更新后的记录。跟踪 API 端点是指持续调用该端点，以获取自上次请求以来新增或更新的记录。

跟踪 Calls API 端点

每当通话记录被修改时，其 updated_at 时间戳都会更新。您可以使用时间戳在调用 Calls API 端点时指定要检索的通话记录。

如需每 60 分钟跟踪一次 Calls API 端点，请按以下步骤操作：

1. 向 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" | jq
   

   Calls 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 时间戳作为您下次调用相应端点时的时间戳。

2. 60 分钟后调用 Call API 端点。系统会返回自您上次请求以来更新的通话记录。

3. 重复上一步，继续跟踪端点。

跟踪 Chats API 端点

每当聊天记录被修改时，其 updated_at 时间戳都会更新。在调用 Chats API 端点时，您可以使用时间戳指定要检索的聊天记录。

如需每 60 分钟跟踪一次 Chats API 端点，请按以下步骤操作：

1. 向 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" | jq
   

   Chats 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 时间戳作为您下次调用相应端点时的时间戳。

2. 60 分钟后再次调用该 API 端点。系统会返回自您上次请求以来更新的聊天记录。

3. 重复上一步，继续跟踪端点。

跟踪 Agent Activity API 端点

与 Chat 记录和通话记录不同，客服人员活动日志不会更新，因此没有 updated_at 时间戳。您可以使用 started_at 时间戳来指定在调用 Agent Activity API 端点时要检索的活动记录。

如需每 60 分钟跟踪一次 Agent Activity API 端点，请按以下步骤操作：

1. 向代理活动 API 端点 (/manager/api/v1/agent_activity_logs) 发出请求，并指定以下查询参数：

   • started_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/agent_activity_logs?started_at[from]=${TIMESTAMP}&sort_column=started_at&sort_direction=asc" | jq
   

   Agent 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 时间戳作为您下次调用相应端点时的时间戳。

2. 60 分钟后再次调用 Agent Activity API 端点。系统会返回自您上次请求以来更新的客服人员活动日志记录。

3. 重复上一步，继续跟踪端点。