페이지로 나누기 및 테일링

이 페이지에서는 관리자 API의 엔드포인트를 호출할 때 페이지로 나누기 및 테일링을 사용하는 방법을 설명합니다.

페이지로 나누기

페이지 매김은 관리자 API의 대부분의 엔드포인트에서 지원됩니다. 예외는 업데이트된 레코드의 엔드포인트 추적을 참조하세요.

페이지 크기 설정

기본적으로 관리자 API 엔드포인트는 레코드 100개가 포함된 페이지를 반환합니다. per 쿼리 매개변수를 사용하여 이 숫자를 최대 100개까지 변경할 수 있습니다. 더 큰 값은 100으로 줄어듭니다.

페이지 크기를 설정하려면 다음 엔드포인트를 사용합니다.

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

이렇게 하면 페이지 크기가 레코드 50개로 설정됩니다.

특정 페이지 요청

page 쿼리 매개변수를 사용하여 특정 레코드 페이지를 요청할 수 있습니다.

특정 페이지를 요청하려면 다음 엔드포인트를 사용합니다.

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

그러면 레코드의 두 번째 페이지가 반환됩니다.

사용 가능한 모든 기록 가져오기

기본적으로 관리자 API는 응답 페이지에 100개의 레코드를 반환하지만 페이지 크기를 설정하여 페이지의 레코드 수를 변경할 수 있습니다. 페이지로 나누기를 지원하는 엔드포인트의 경우 응답 헤더에 사용 가능한 총 레코드 수가 포함됩니다. 이 숫자가 페이지 크기를 초과하면 API를 여러 번 호출하여 모든 레코드를 가져와야 합니다. 페이지 매김을 지원하는 엔드포인트의 경우 응답에 RFC 5988에 따른 Link 헤더가 포함됩니다. 사용 가능한 레코드가 더 있으면 rel="next" 링크가 표시되고 rel="last" 링크는 마지막 페이지의 번호를 제공합니다. 응답에는 Total 및 Per-Page 헤더도 포함됩니다.

사용 가능한 모든 레코드를 가져오려면 다음 단계를 따르세요.

  1. 페이지 매김을 지원하는 관리자 API 엔드포인트를 호출합니다. 자세한 내용은 페이지로 나누기를 참조하세요. 응답 헤더는 반환할 레코드 수를 나타냅니다.

  2. 반환할 레코드 수를 페이지 크기와 비교합니다. 반환할 레코드 수가 페이지 크기보다 작으면 모든 레코드가 반환된 것입니다. 그렇지 않으면 다음 단계로 진행합니다.

  3. 다음 레코드 페이지를 지정하여 엔드포인트를 다시 호출합니다. 자세한 내용은 특정 페이지 요청을 참조하세요. 모든 레코드가 반환될 때까지 이 단계를 반복합니다.

업데이트된 레코드의 엔드포인트 추적

Google은 최적의 결과를 보장할 수 없으므로 통화, 채팅, 에이전트 활동 API 엔드포인트에 페이지 매김을 사용하지 않는 것이 좋습니다. 대신 업데이트된 레코드에 대해 이러한 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 엔드포인트 추적

채팅 및 통화 기록과 달리 상담사 활동 로그는 업데이트되지 않으므로 updated_at 타임스탬프가 없습니다. started_at 타임스탬프를 사용하여 에이전트 활동 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가 없으면 응답은 Link, Total 또는 Per-Page 헤더를 반환하지 않고 기본 페이지 크기인 100개 레코드로 제한됩니다.

    • 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. 이전 단계를 반복하여 엔드포인트를 계속 추적합니다.