分页和尾随

本页面介绍了如何在调用 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 标头。

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

  1. 调用支持分页的 Manager 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。from 过滤条件是包含性的,因此下一个响应会重复该时间戳处的记录。对记录 ID 进行去重,或记录在该时间戳已处理的 ID 并跳过它们。

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

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

跟踪 Chats API 端点

在下次调用端点时,请使用此响应中最后一个对象的 updated_at 时间戳。updated_at[from] 过滤条件是包含性的,因此下一个响应会重复该时间戳处的记录。根据记录 ID 进行去重,或记录已在该时间戳处理的 ID 并跳过它们。

每当修改聊天记录时,其 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 端点时要检索的活动记录。started_at[from] 过滤条件是包含性的,因此下一个响应会重复该时间戳处的记录。对记录 ID 进行去重,或记录已在该时间戳处理的 ID 并跳过它们。

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

  1. 向 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" | 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. 重复上一步,继续跟踪端点。