分頁和尾隨

本頁面說明呼叫 Manager API 的端點時，如何使用分頁和結尾功能。

分頁

Manager API 的大部分端點都支援分頁功能。如需例外狀況，請參閱「追蹤端點以取得更新記錄」。

設定頁面大小

根據預設，管理員 API 端點會傳回包含 100 筆記錄的頁面。您可以使用 per 查詢參數變更這個數字，最多可達 100。如果值大於 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. 呼叫支援分頁的管理員 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 和 Call 記錄不同，Agent Activity Logs 不會更新，因此沒有 updated_at 時間戳記。呼叫 Agent Activity API 端點時，您可以使用 started_at 時間戳記指定要擷取的活動記錄。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. 重複上述步驟，繼續追蹤端點。