Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

페이지로 나누기 및 테일링

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

페이지로 나누기

관리자 API의 대부분의 엔드포인트에서 페이지로 나누기가 지원됩니다. 예외는 업데이트된 레코드의 엔드포인트 테일링을 참고하세요.

페이지 크기 설정

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

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

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

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

특정 페이지 요청

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

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

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

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

사용 가능한 모든 레코드 가져오기

기본적으로 관리자 API는 응답 페이지에 100개의 레코드를 반환하지만 페이지 크기를 설정하여 페이지의 레코드 수를 변경할 수 있습니다. 페이지로 나누기를 지원하는 엔드포인트의 경우 응답 헤더에 사용 가능한 총 레코드 수가 포함됩니다. 이 숫자가 페이지 크기를 초과하면 모든 레코드를 가져오기 위해 API를 여러 번 호출해야 합니다. 관리자 API는 반환할 추가 레코드가 있음을 명시적으로 나타내지 않습니다.

사용 가능한 모든 레코드를 가져오려면 다음을 실행하세요.

페이지로 나누기를 지원하는 관리자 API 엔드포인트를 호출합니다. 자세한 내용은 페이지로 나누기를 참고하세요. 응답 헤더는 반환할 레코드 수를 나타냅니다.
반환할 레코드 수를 페이지 크기와 비교합니다. 반환할 레코드 수가 페이지 크기보다 작으면 모든 레코드가 반환된 것입니다. 그렇지 않으면 다음 단계로 진행합니다.
레코드의 다음 페이지를 지정하여 엔드포인트를 다시 호출합니다. 자세한 내용은 특정 페이지 요청을 참고하세요. 모든 레코드가 반환될 때까지 이 단계를 반복합니다.

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

Google에서는 최적의 결과를 보장할 수 없으므로 통화, 채팅, 상담사 활동 API 엔드포인트에 페이지로 나누기를 사용하지 않는 것이 좋습니다. 대신 업데이트된 레코드에 대해 이러한 API 엔드포인트를 테일링하는 것이 좋습니다. API 엔드포인트를 테일링한다는 것은 마지막 요청 이후 새로 생성되거나 업데이트된 레코드를 가져오기 위해 엔드포인트를 지속적으로 호출한다는 의미입니다.

Calls API 엔드포인트 테일링

통화 기록이 수정될 때마다 updated_at 타임스탬프가 업데이트됩니다. 타임스탬프를 사용하여 Calls API 엔드포인트를 호출할 때 가져올 통화 기록을 지정할 수 있습니다.

60분마다 Calls API 엔드포인트를 테일링하려면 다음 단계를 따르세요.

다음 쿼리 매개변수를 지정하여 통화 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 타임스탬프를 엔드포인트에 대한 다음 호출의 타임스탬프로 사용합니다.

60분 후에 Call API 엔드포인트를 호출합니다. 마지막 요청 이후 업데이트된 통화 기록이 반환됩니다.
이전 단계를 반복하여 엔드포인트를 계속 추적합니다.

Chats API 엔드포인트 테일링

채팅 기록이 수정될 때마다 updated_at 타임스탬프가 업데이트됩니다. 타임스탬프를 사용하여 Chats API 엔드포인트를 호출할 때 가져올 채팅 기록을 지정할 수 있습니다.

60분마다 Chats API 엔드포인트를 테일링하려면 다음 단계를 따르세요.

다음 쿼리 매개변수를 지정하여 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 타임스탬프를 엔드포인트에 대한 다음 호출의 타임스탬프로 사용합니다.

60분 후에 API 엔드포인트를 다시 호출합니다. 마지막 요청 이후 업데이트된 채팅 기록이 반환됩니다.
이전 단계를 반복하여 엔드포인트를 계속 추적합니다.

Agent Activity API 엔드포인트 테일링

채팅 및 통화 기록과 달리 상담사 활동 로그는 업데이트되지 않으므로 updated_at 타임스탬프가 없습니다. started_at 타임스탬프를 사용하여 Agent Activity API 엔드포인트를 호출할 때 가져올 활동 기록을 지정할 수 있습니다.

60분마다 에이전트 활동 API 엔드포인트를 테일링하려면 다음 단계를 따르세요.

다음 쿼리 매개변수를 지정하여 상담사 활동 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 타임스탬프를 엔드포인트에 대한 다음 호출의 타임스탬프로 사용합니다.

60분 후에 에이전트 활동 API 엔드포인트를 다시 호출합니다. 마지막 요청 이후 업데이트된 상담사 활동 로그 레코드가 반환됩니다.
이전 단계를 반복하여 엔드포인트를 계속 추적합니다.

페이지로 나누기 및 테일링 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.