콘텐츠로 이동
DoveRunner Docs

DoveRunner Piracy Guard ✨ 서비스 API 가이드

Piracy Guard는 RESTful 비즈니스 API를 통해 데이터를 제공하므로, 개발자가 해적 행위 인텔리전스를 워크플로우 및 도구에 직접 통합하기 쉽습니다. 이 가이드에서는 필수 요청 파라미터와 응답 데이터 구조를 포함하여 사용 가능한 엔드포인트를 안내합니다. 이 API를 통해 DRM 라이선스 활동에 대한 이상 감지 및 해적 행위 분석을 구현할 수 있습니다.

이 API를 사용하면 의심스러운 동작 로그를 조회하고, 일별 활동 지표를 모니터링하며, 심층 조사를 위해 사이트에서 가장 의심스러운 사용자를 확인할 수 있습니다.

인증 및 권한 부여

Section titled “인증 및 권한 부여”

모든 Piracy Guard API는 Authorization HTTP 요청 헤더에 유효한 JWT 토큰이 필요합니다. 토큰은 서비스 API 키로 발급되어야 하며 필수 페이로드 필드가 포함되어야 합니다.

DoveRunner 서비스 API 가이드 - JWT 구조 인증을 위한 JWT 생성에 대한 세부 정보

이 API를 호출하기 전에 다음 사항을 확인하세요.

  1. Piracy Guard API를 사용할 수 있도록 계정에 권한이 부여되어 있어야 합니다.

    헬프데스크를 통해 DoveRunner 지원팀에 연락하여 접근 권한을 요청하세요.

  2. 요청에 각 엔드포인트에 맞는 올바른 api_code를 포함해야 합니다.

    api_code는 계정의 인가된 권한에 대해 검증됩니다 — api_code가 누락되거나 인가되지 않은 요청은 거부됩니다.

    요청에는 UA003001040100을 정적으로 사용할 수 있습니다.

언어 처리

Section titled “언어 처리”

일부 Piracy Guard REST API는 다음 우선순위에 따라 응답 언어를 결정합니다. Accept-Language 헤더 → lang 쿼리 파라미터 → 기본값 en. API는 먼저 Accept-Language 헤더에서 클라이언트의 선호 언어를 확인합니다. 헤더가 제공되지 않거나 지원되지 않는 경우, lang 쿼리 파라미터가 사용됩니다. 둘 다 지정되지 않은 경우 응답은 기본적으로 영어(en)로 반환됩니다.

서비스 API

Section titled “서비스 API”

GET 로그 목록

Section titled “ 로그 목록”

지정된 기간의 이상 감지 로그 목록을 조회합니다.

GET /api/v2/drm/piracy-guard

HTTP 헤더

Section titled “HTTP 헤더”

Authorization (필수)
인코딩된 JWT 토큰. 자세한 내용은 인증 및 권한 부여를 참조하세요.

Accept-Language
보고서 언어. 자세한 내용은 언어 처리 섹션을 참조하세요.

쿼리 파라미터

Section titled “쿼리 파라미터”

api_code string (필수)
API의 고정 코드 (UA003001040100)

site_id string (필수)
사이트의 고유 ID (네 자리 영숫자)

from string
검색 기간 시작일. ISO 8601 표준에 따른 YYYY-MM-DD 형식의 날짜

to string
검색 기간 종료일. ISO 8601 표준에 따른 YYYY-MM-DD 형식의 날짜. 날짜를 입력하지 않으면 오늘 날짜 기준으로 검색합니다.

time_zone string (기본값: +00:00)
ISO 8601 표준에 따른 ±[hh]:[mm] 형식의 UTC 오프셋

search_condition string
키워드 검색 카테고리

search_keyword string
정의된 search_condition 카테고리에 대한 검색 값

report_violation_primary_code string
위반 유형별 필터. 가능한 값은 다음과 같습니다.

  • license_farming
  • bot_automation
  • token_replay
  • content_ripping
  • account_sharing

page_unit integer (기본값: 25, 최대: 1000)
응답에 포함할 항목 수

page_index integer
page_unit 크기 단위로 이 페이지 수만큼 오프셋

lang string (기본값: en)
보고서 언어. 자세한 내용은 언어 처리 섹션을 참조하세요.

요청 예시

Section titled “요청 예시”
Terminal window
curl --L 'https://service.doverunner.com/api/v2/drm/piracy-guard?api_code=UA003001040100&site_id=DEMO&from=2026-01-01&to=2026-01-31' \
--H 'Authorization: Bearer <your_jwt_token>' \
--H 'Accept-Language: en'

응답

Section titled “응답”

count long
총 레코드 수

data array
Piracy Guard 로그 항목 목록

자세히 보기

data[].anomaly integer
이상 감지 결과를 숫자로 표현한 플래그. 0은 정상, 1은 이상으로 판정된 항목을 의미합니다. anomaly_status 필드와 동일한 값이지만 정수형으로 제공됩니다.

플래그의미
0이상이 감지되지 않은 normal 항목
1anomalous로 판정된 항목

data[].site_id string
DRM 요청이 발생한 서비스 사이트의 고유 식별자 (네 자리 영숫자)

data[].user_id string
DRM 라이선스 요청을 발생시킨 최종 사용자의 고유 식별자

data[].unique_key string
user_id와 집계 기간을 기반으로 한 고유 해시 키. 동일 사용자의 중복 레코드를 구분하는 데 사용됩니다.

data[].start_date string
해당 로그의 집계 시작일. YYYY-MM-DD 형식 (ISO 8601)

data[].end_date string
해당 로그의 집계 종료일. YYYY-MM-DD 형식 (ISO 8601)

data[].log_date string
해당 로그 레코드가 생성된 시각. YYYYMMDDhhmmss 형식의 타임스탬프

data[].license_cnt integer
24시간 동안 해당 사용자가 발급받은 DRM 라이선스 요청의 총 횟수. 일반적인 시청 패턴을 크게 초과하는 경우 자동화된 대량 요청이나 계정 공유를 의심할 수 있습니다.

data[].req_unique_hour_cnt integer
24시간(0–23시) 중 실제로 DRM 라이선스 요청이 발생한 시간대의 수. 값이 클수록 하루 종일 지속적으로 요청이 이루어졌음을 의미하며, 봇이나 자동화된 접근의 지표가 될 수 있습니다.

data[].device_id_diversity_score float
24시간 동안 사용된 디바이스 ID의 다양성을 나타내는 점수 (0.0 = 모두 동일, 1.0 = 모두 상이). 값이 높을수록 여러 개의 서로 다른 디바이스에서 요청이 발생했음을 의미하며, 계정 공유나 크리덴셜 남용의 징후일 수 있습니다.

data[].device_model_diversity_score float
사용된 디바이스 모델(예: iPhone 12, Galaxy S21)의 다양성 점수 (0.0 = 모두 동일, 1.0 = 모두 상이). 단일 계정에서 매우 다양한 기기 모델이 관찰될 경우 비정상적인 접근을 의심할 수 있습니다.

data[].device_type_diversity_score float
사용된 디바이스 유형(예: Phone, Tablet, TV, Mac 등)의 다양성 점수 (0.0 = 모두 동일, 1.0 = 모두 상이). 단일 사용자가 매우 다양한 디바이스 유형에서 동시에 접근하는 경우 계정 공유를 시사할 수 있습니다.

data[].device_category_unique_cnt integer
24시간 동안 사용된 디바이스 카테고리(PC, Mobile, TV, Others)의 종류 수. 최대값은 4이며, 값이 클수록 다양한 환경에서 동시 접근이 이루어졌음을 나타냅니다.

data[].device_category_pc_ratio float
전체 DRM 라이선스 요청 중 PC 디바이스에서 발생한 요청의 비율 (0.0–1.0)

data[].device_category_mobile_ratio float
전체 DRM 라이선스 요청 중 모바일 디바이스(스마트폰, 태블릿 등)에서 발생한 요청의 비율 (0.0–1.0)

data[].device_category_tv_ratio float
전체 DRM 라이선스 요청 중 TV 디바이스에서 발생한 요청의 비율 (0.0–1.0)

data[].device_category_others_ratio float
전체 DRM 라이선스 요청 중 PC, Mobile, TV로 분류되지 않은 기타 디바이스에서 발생한 요청의 비율 (0.0–1.0)

data[].drm_type_unique_cnt integer
24시간 동안 사용된 DRM 방식(Widevine, FairPlay, PlayReady)의 종류 수. iOS는 FairPlay, Android/Windows는 Widevine 또는 PlayReady를 사용하므로, 복수의 DRM이 관찰되는 것은 다양한 디바이스 환경을 반영할 수 있습니다.

data[].drm_type_widevine_ratio float
전체 DRM 라이선스 요청 중 Widevine DRM을 사용한 요청의 비율 (0.0–1.0). Android 및 Windows Chrome 환경에서 주로 사용됩니다.

data[].drm_type_fairplay_ratio float
전체 DRM 라이선스 요청 중 FairPlay DRM을 사용한 요청의 비율 (0.0–1.0). iOS 및 macOS Safari 환경에서 주로 사용됩니다.

data[].drm_type_playready_ratio float
전체 DRM 라이선스 요청 중 PlayReady DRM을 사용한 요청의 비율 (0.0–1.0). Windows 및 일부 스마트 TV 환경에서 주로 사용됩니다.

data[].os_type_unique_cnt integer
24시간 동안 DRM 요청에 사용된 운영체제(OS)의 종류 수. iOS, Android, Windows를 함께 사용하는 경우 값이 3이 되는 것은 일반적인 멀티 디바이스 이용 패턴일 수 있습니다.

data[].os_type_ios_ratio float
전체 DRM 라이선스 요청 중 iOS 환경에서 발생한 요청의 비율 (0.0–1.0)

data[].os_type_android_ratio float
전체 DRM 라이선스 요청 중 Android 환경에서 발생한 요청의 비율 (0.0–1.0)

data[].os_type_mac_ratio float
전체 DRM 라이선스 요청 중 macOS 환경에서 발생한 요청의 비율 (0.0–1.0)

data[].os_type_windows_ratio float
전체 DRM 라이선스 요청 중 Windows 환경에서 발생한 요청의 비율 (0.0–1.0)

data[].os_type_web_ratio float
전체 DRM 라이선스 요청 중 웹 브라우저 환경(Web 런타임)에서 발생한 요청의 비율 (0.0–1.0)

data[].os_type_others_ratio float
전체 DRM 라이선스 요청 중 iOS, Android, macOS, Windows, Web으로 분류되지 않은 기타 운영체제 환경에서 발생한 요청의 비율 (0.0–1.0)

data[].region_unique_cnt integer
DRM 라이선스 요청이 유입된 AWS 리전의 종류 수 (예: 서울, 프랑크푸르트). 값이 높을수록 지리적으로 분산된 환경에서 접근이 이루어졌음을 의미하며, VPN이나 프록시를 통한 계정 공유의 징후일 수 있습니다.

data[].cid_diversity_score float
24시간 동안 요청된 콘텐츠 ID의 다양성 점수 (0.0 = 동일 콘텐츠 반복 요청, 1.0 = 모두 서로 다른 콘텐츠). 값이 낮고 요청 수가 많다면 특정 콘텐츠에 대한 반복적인 라이선스 발급을 의심할 수 있습니다.

data[].scheme_unique_cnt integer
DRM 라이선스 요청 URL에 사용된 프로토콜 스킴의 종류 수 (예: http, https). 최대값은 2이며, 일반적으로 값이 1이어야 정상입니다.

data[].path_unique_cnt integer
24시간 동안 DoveRunner Multi-DRM 라이선스 서버로 전송된 고유 URL 경로의 수. 경로가 다양할수록 여러 라이선스 엔드포인트에 접근했음을 의미합니다.

data[].ip_pattern_unique_cnt integer
DRM 라이선스 요청 경로에서 관찰된 고유 IP 홉 패턴의 수 (예: 4홉 경로와 5홉 경로는 2개의 패턴으로 집계). 패턴 수가 많을수록 네트워크 경로가 다양하다는 의미로, 여러 네트워크 환경에서 접근하거나 프록시를 경유했을 가능성을 시사합니다.

data[].security_level_unique_cnt integer
24시간 동안 DRM 라이선스 요청에 사용된 서로 다른 보안 등급의 수. Widevine의 L1/L3, PlayReady의 SL150/SL3000 등 DRM 유형마다 보안 등급이 다르며, 여러 디바이스나 환경에서 동시에 접근할수록 이 값이 높아집니다.

data[].security_policy_diversity_score float
적용된 DRM 보안 정책 설정의 다양성 점수 (0.0 = 모두 동일, 1.0 = 모두 상이). 서비스 정책이 표준화된 경우 이 값이 0.0에 가까운 것은 정상이며, 이상 여부를 단독으로 판단하는 지표로 사용하지 않습니다.

data[].playback_policy_diversity_score float
적용된 DRM 재생 정책 설정의 다양성 점수 (0.0 = 모두 동일, 1.0 = 모두 상이). 보안 정책과 마찬가지로, 서비스 전반에 걸쳐 표준화된 재생 정책이 적용되는 경우 이 값이 낮은 것은 자연스러운 현상입니다.

data[].token_avg_time_diff float
DRM 라이선스 토큰이 발급된 시점부터 실제 라이선스 요청이 이루어진 시점까지의 평균 시간 간격 (초). 일반적인 클라이언트는 토큰 발급 후 수 초 이내에 라이선스를 요청합니다. 10초를 크게 초과하면 토큰을 수집해 두었다가 나중에 재사용하는 토큰 리플레이 공격을 의심할 수 있습니다.

data[].req_avg_time_diff float
동일 사용자의 연속된 DRM 라이선스 요청 사이의 평균 시간 간격 (초). 일반적인 시청 패턴에서는 약 5,000–6,000초 수준이며, 이보다 매우 짧은 경우 봇이나 자동화된 대량 요청을 의심할 수 있습니다. 단, 콘텐츠를 탐색하거나 여러 콘텐츠를 빠르게 샘플링하는 정상적인 이용 행태에서도 짧은 간격이 나타날 수 있습니다.

data[].hash_duplication_score float
라이선스 토큰의 해시 값 중복도를 나타내는 점수 (0.0 = 모두 고유, 1.0 = 모두 동일). 0.0보다 높은 값은 동일한 라이선스 토큰이 재사용되었음을 의미하며, 값이 높을수록 토큰 리플레이 또는 라이선스 파밍 가능성이 높아집니다.

data[].session_id_duplication_score float
라이선스 요청에 사용된 세션 ID의 중복도를 나타내는 점수 (0.0 = 모두 고유, 1.0 = 모두 동일). 값이 높을수록 동일한 세션이 반복적으로 재사용된 것을 의미하며, 자동화된 접근이나 세션 재사용 공격의 징후일 수 있습니다.

data[].anomaly_status string
이상 감지 결과를 문자열로 표현한 상태값. normal은 정상, abnormal은 이상으로 판정된 항목을 나타냅니다. anomaly 필드와 동일한 판정 결과이지만 사람이 읽기 쉬운 형식으로 제공됩니다.

data[].report_incident_report string
분석 결과를 바탕으로 작성된 이상 행위 사건 요약 보고서. license_cnt 수치를 명시하고, avg_delay_between_requests가 일반적인 5,000–6,000초 범위에서 얼마나 벗어났는지, 짧은 시간 내 다양한 DRM 유형 요청 여부, region_unique_cnt 수준 등을 근거로 해당 행동이 비정상적인 이유를 설명합니다.

data[].report_reasoning string
이상 판정의 근거를 항목별로 나열한 추론 목록. license_cnt 비정상 수치, avg_delay_between_requests 단축, device_id_diversity_score 상승 등 판정에 영향을 미친 개별 피처와 그 의미를 각각 설명합니다. 문자열로 직렬화된 JSON 배열 형식으로 제공됩니다.

data[].report_risk_level string
탐지된 이상 행위의 전반적인 위험 수준. high(높음), medium(중간), low(낮음) 중 하나의 값을 가집니다.

data[].report_violation_notes string
이상 판정의 주요 증거와 위반 유형을 연결하는 간결한 기술 메모. 실제 피처명과 수치를 직접 인용하여 작성됩니다. 예: avg_delay_between_requests=35초(40초로 버킷팅), session_id_duplication_score=0.80, region_unique_cnt=3.

data[].report_violation_primary_code string
가장 가능성이 높은 위반 유형의 코드. 가능한 값은 license_farming, bot_automation, token_replay, content_ripping, account_sharing 등 입니다.

data[].report_violation_primary string
주요 위반 유형의 상세 정보를 담은 JSON 객체(문자열 형식). 위반 코드(code), 영문 설명(en), 한국어 설명(ko), 신뢰도 점수(confidence)를 포함합니다. 이상이 없는 경우 code는 none, confidence는 0.0으로 설정됩니다.

data[].report_violation_primary_confidence float
주요 위반 유형 판정에 대한 신뢰도 점수 (0.0–1.0). 값이 높을수록 해당 위반 유형으로의 판정 확신도가 높으며, 이상이 없는 경우에는 0.0으로 설정됩니다.

GET 일별 통계

Section titled “ 일별 통계”

지정된 월의 일별 의심 활동 통계 목록을 조회합니다. 현재 월을 요청하는 경우, 반환된 결과에는 현재 월의 첫째 날부터 어제까지의 항목이 포함됩니다.

GET /api/v2/drm/piracy-guard/statistics

HTTP 헤더

Section titled “HTTP 헤더”

Authorization (필수)
인코딩된 JWT 토큰. 자세한 내용은 인증 및 권한 부여를 참조하세요.

쿼리 파라미터

Section titled “쿼리 파라미터”

api_code string (필수)
API의 고정 코드 (UA003001040100)

site_id string (필수)
사이트의 고유 ID (네 자리 영숫자)

target_date string (필수)
기준 날짜. ISO 8601 표준에 따른 YYYY-MM-DD 형식의 날짜

요청 예시

Section titled “요청 예시”
Terminal window
curl --L 'https://service.doverunner.com/api/v2/drm/piracy-guard/statistics?api_code=UA003001040100&site_id=DEMO&target_date=2025-11-01' \
--H 'Authorization: Bearer <your_jwt_token>'

응답

Section titled “응답”

count long
총 레코드 수

data array
Piracy Guard 일별 통계 항목 목록

자세히 보기

data[].target_date integer
해당 월의 목표 일자

data[].site_suspicious_cnt long
일별 의심 활동 수

data[].risk_level_distribution object
위험 수준별 일별 분포. 값이 0인 키는 응답 데이터에 포함되지 않습니다.

자세히 보기

data[].risk_level_distribution.high integer
높은 위험으로 표시된 위반 수

data[].risk_level_distribution.medium integer
중간 위험으로 표시된 위반 수

data[].risk_level_distribution.low integer
낮은 위험으로 표시된 위반 수

data[].violation_type_distribution object
위반 유형별 일별 분포. 값이 0인 키는 응답 데이터에 포함되지 않습니다.

자세히 보기

data[].risk_level_distribution.license_farming integer
license_farming 위반 발생 횟수

data[].risk_level_distribution.bot_automation integer
bot_automation 위반 발생 횟수

data[].risk_level_distribution.token_replay integer
token_replay 위반 발생 횟수

data[].risk_level_distribution.content_ripping integer
content_ripping 위반 발생 횟수

data[].risk_level_distribution.account_sharing integer
account_sharing 위반 발생 횟수

data[].site_suspicious_acc_cnt long
월별 누적 의심 활동 수

data[].risk_level_acc_distribution object
위험 수준별 월별 누적 분포. 값이 0인 키는 응답 데이터에 포함되지 않습니다.

자세히 보기

data[].risk_level_distribution.high integer
높은 위험으로 표시된 위반 수

data[].risk_level_distribution.medium integer
중간 위험으로 표시된 위반 수

data[].risk_level_distribution.low integer
낮은 위험으로 표시된 위반 수

data[].violation_type_acc_distribution object
위반 유형별 월별 누적 분포. 값이 0인 키는 응답 데이터에 포함되지 않습니다.

자세히 보기

data[].violation_type_acc_distribution.license_farming integer
license_farming 위반 발생 횟수.

data[].violation_type_acc_distribution.bot_automation integer
bot_automation 위반 발생 횟수.

data[].violation_type_acc_distribution.token_replay integer
token_replay 위반 발생 횟수.

data[].violation_type_acc_distribution.content_ripping integer
content_ripping 위반 발생 횟수.

data[].violation_type_acc_distribution.account_sharing integer
account_sharing 위반 발생 횟수.

GET 상위 의심 사용자

Section titled “ 상위 의심 사용자”

월별 의심 활동 수를 기준으로 상위 사용자 목록을 조회합니다.

GET /api/v2/drm/piracy-guard/users/top

HTTP 헤더

Section titled “HTTP 헤더”

Authorization (필수)
인코딩된 JWT 토큰. 자세한 내용은 인증 및 권한 부여를 참조하세요.

쿼리 파라미터

Section titled “쿼리 파라미터”

api_code string (필수)
API의 고정 코드 (UA003001040100)

site_id string (필수)
사이트의 고유 ID (네 자리 영숫자)

target_date string (필수)
기준 날짜. ISO 8601 표준에 따른 YYYY-MM-DD 형식의 날짜

요청 예시

Section titled “요청 예시”
Terminal window
curl --L 'https://service.doverunner.com/api/v2/drm/piracy-guard/users/top?api_code=UA003001040100&site_id=DEMO&target_date=2025-11-01' \
--H 'Authorization: Bearer <your_jwt_token>'

응답

Section titled “응답”

count long
총 레코드 수

data array
월별 상위 의심 사용자 목록

자세히 보기

data[].user_id string
최종 사용자의 고유 ID

data[].site_suspicious_cnt long
의심 활동 발생 횟수