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

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

ページ分割

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

ページサイズを設定する

デフォルトでは、Manager API エンドポイントは 100 件のレコードを含むページを返します。この数は、per クエリ パラメータを使用して変更できます。

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

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

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

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

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

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

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

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

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

デフォルトでは、Manager API はレスポンス ページに 100 件のレコードを返しますが、ページサイズを設定することで、1 ページあたりのレコード数を変更できます。ページ分割をサポートするエンドポイントの場合、 レスポンス ヘッダーには使用可能なレコードの合計数が含まれます。その数がページサイズを超える場合は、API を複数回呼び出してすべてのレコードを取得する必要があります。Manager API は、返されるレコードが他にもあることを明示的に示しません。

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

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

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

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

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

最適な結果を保証できないため、通話、チャット、 およびエージェント アクティビティの API エンドポイントでページ分割を使用することはおすすめしません。代わりに、更新されたレコードのこれらの API エンドポイントをテーリングすることをおすすめします。API エンドポイントのテーリングとは、前回のリクエスト以降に新規または更新されたレコードを取得するために、エンドポイントを継続的に呼び出すことを意味します。

Calls API エンドポイントをテーリングする

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

Calls API エンドポイントを 60 分ごとにテーリングするには、次の操作を行います。

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 エンドポイントを呼び出すときに取得するチャット レコードを指定できます。

Chats API エンドポイントを 60 分ごとにテーリングするには、次の操作を行います。

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 エンドポイントをテーリングする

チャット レコードや通話レコードとは異なり、エージェント アクティビティ ログは更新されないため、updated_at タイムスタンプはありません。started_at タイムスタンプを使用して、Agent Activity API エンドポイントを呼び出すときに取得するアクティビティ レコードを指定できます。

Agent Activity API エンドポイントを 60 分ごとにテーリングするには、次の操作を行います。

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