ページネーションとテーリング

このページでは、マネージャー API のエンドポイントを呼び出すときに、ページネーションとテーリングを使用する方法について説明します。

ページ分け

ページネーションは、マネージャー API のほとんどのエンドポイントでサポートされています。例外については、更新されたレコードのエンドポイントをテーリングするをご覧ください。

ページサイズを設定する

デフォルトでは、マネージャー API エンドポイントは 100 件のレコードを含むページを返します。この数は、per クエリ パラメータを使用して変更できます（最大 100）。これより大きい値は 100 に減らされます。

ページサイズを設定するには、次のエンドポイントを使用します。

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

これにより、ページサイズが 50 レコードに設定されます。

特定のページをリクエストする

page クエリ パラメータを使用して、特定のレコードページをリクエストできます。

特定のページをリクエストするには、次のエンドポイントを使用します。

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

これにより、レコードの 2 ページ目が返されます。

利用可能なすべてのレコードを取得する

デフォルトでは、マネージャー API はレスポンス ページに 100 件のレコードを返しますが、ページサイズを設定することで、ページ内のレコード数を変更できます。ページネーションをサポートするエンドポイントの場合、レスポンス ヘッダーには使用可能なレコードの合計数が含まれます。この数がページサイズを超える場合は、API を複数回呼び出してすべてのレコードを取得する必要があります。ページ分けをサポートするエンドポイントの場合、レスポンスには RFC 5988 に従って Link ヘッダーが含まれます。rel="next" リンクは、さらにレコードがある場合に表示されます。rel="last" リンクは、最後のページの番号を示します。レスポンスには Total ヘッダーと Per-Page ヘッダーも含まれます。

利用可能なすべてのレコードを取得するには、次の操作を行います。

1. ページ分けをサポートするマネージャー API エンドポイントを呼び出します。詳しくは、ページネーションをご覧ください。レスポンス ヘッダーは、返されるレコードの数を示します。

2. 返されるレコード数をページサイズと比較します。返されるレコード数がページサイズより少ない場合、すべてのレコードが返されています。それ以外の場合は、次のステップに進みます。

3. レコードの次のページを指定して、エンドポイントを再度呼び出します。詳細については、特定のページをリクエストするをご覧ください。すべてのレコードが返されるまで、この手順を繰り返します。

更新されたレコードのエンドポイントを tail する

Google では、call、chat、agent activity API エンドポイントにページネーションを使用しないことをおすすめします。最適な結果が得られるとは限らないためです。代わりに、これらの API エンドポイントをテーリングして、更新されたレコードを取得することをおすすめします。API エンドポイントをテーリングするとは、エンドポイントを継続的に呼び出して、前回の呼び出し以降に新規作成または更新されたレコードを取得することを意味します。

Calls API エンドポイントを tail する

通話レコードが変更されるたびに、updated_at タイムスタンプが更新されます。タイムスタンプを使用すると、Calls API エンドポイントを呼び出すときに取得する通話記録を指定できます。

Calls API エンドポイントを 60 分ごとに tail する手順は次のとおりです。

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 エンドポイントを tail する

このレスポンスの最後のオブジェクトの updated_at タイムスタンプを、エンドポイントへの次の呼び出しのタイムスタンプに使用します。updated_at[from] フィルタは包括的であるため、次のレスポンスではそのタイムスタンプのレコードが繰り返されます。レコード ID で重複除去するか、そのタイムスタンプですでに処理された ID を記録してスキップします。

チャットの記録が変更されるたびに、updated_at タイムスタンプが更新されます。タイムスタンプを使用すると、Chats API エンドポイントを呼び出すときに取得するチャットレコードを指定できます。

Chats API エンドポイントを 60 分ごとに tail する手順は次のとおりです。

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 エンドポイントを tail する

チャットと通話のレコードとは異なり、エージェント アクティビティ ログは更新されないため、updated_at タイムスタンプはありません。started_at タイムスタンプを使用すると、Agent Activity API エンドポイントを呼び出すときに取得するアクティビティ レコードを指定できます。started_at[from] フィルタは包括的であるため、次のレスポンスではそのタイムスタンプのレコードが繰り返されます。レコード ID で重複除去するか、そのタイムスタンプですでに処理された ID を記録してスキップします。

Agent Activity API エンドポイントを 60 分ごとに tail する手順は次のとおりです。

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. 前の手順を繰り返して、エンドポイントのテーリングを続行します。