---
title: "DoveRunner Piracy Guard ✨ 서비스 API 가이드"
description: "이 문서는 DoveRunner Piracy Guard ✨를 고객 시스템과 통합하기 위한 서비스 API 사용법을 설명합니다."
---
> For the complete documentation index, see [llms.txt](/llms.txt).
import { LinkCard } from '@astrojs/starlight/components';
import { Steps } from '@astrojs/starlight/components';
import { Badge } from '@astrojs/starlight/components';
import { Tabs, TabItem } from '@astrojs/starlight/components';
import { Code } from '@astrojs/starlight/components';
import SectionExpander from '../../../../../../components/SectionExpander.astro';
import logListResponseExample from '/files/service-api-log-list-response-example.json?url&raw';
import dailyStatisticsResponseExample from '/files/service-api-daily-statistics-response-example.json?url&raw';
import topSuspiciousUsersResponseExample from '/files/service-api-top-suspicious-users-response-example.json?url&raw';
Piracy Guard는 RESTful 비즈니스 API를 통해 데이터를 제공하므로, 개발자가 해적 행위 인텔리전스를 워크플로우 및 도구에 직접 통합하기 쉽습니다. 이 가이드에서는 필수 요청 파라미터와 응답 데이터 구조를 포함하여 사용 가능한 엔드포인트를 안내합니다. 이 API를 통해 DRM 라이선스 활동에 대한 이상 감지 및 해적 행위 분석을 구현할 수 있습니다.
이 API를 사용하면 의심스러운 동작 로그를 조회하고, 일별 활동 지표를 모니터링하며, 심층 조사를 위해 사이트에서 가장 의심스러운 사용자를 확인할 수 있습니다.
:::tip
Piracy Guard는 현재 이상 징후 사건을 최대 3개월간 보관합니다.
:::
## 인증 및 권한 부여
모든 Piracy Guard API는 `Authorization` HTTP 요청 헤더에 유효한 JWT 토큰이 필요합니다. 토큰은 서비스 API 키로 발급되어야 하며 필수 페이로드 필드가 포함되어야 합니다.
이 API를 호출하기 전에 다음 사항을 확인하세요.
1. **Piracy Guard API를 사용할 수 있도록 계정에 권한이 부여되어 있어야 합니다.**
헬프데스크를 통해 DoveRunner 지원팀에 연락하여 접근 권한을 요청하세요.
2. **요청에 각 엔드포인트에 맞는 올바른 `api_code`를 포함해야 합니다.**
`api_code`는 계정의 인가된 권한에 대해 검증됩니다 — `api_code`가 누락되거나 인가되지 않은 요청은 거부됩니다.
요청에는 `UA003001040100`을 정적으로 사용할 수 있습니다.
## 언어 처리
일부 Piracy Guard REST API는 다음 우선순위에 따라 응답 언어를 결정합니다. `Accept-Language` 헤더 → `lang` 쿼리 파라미터 → 기본값 `en`. API는 먼저 `Accept-Language` 헤더에서 클라이언트의 선호 언어를 확인합니다. 헤더가 제공되지 않거나 지원되지 않는 경우, `lang` 쿼리 파라미터가 사용됩니다. 둘 다 지정되지 않은 경우 응답은 기본적으로 영어(`en`)로 반환됩니다.
## 서비스 API
### 로그 목록
지정된 기간의 이상 감지 로그 목록을 조회합니다.
```
GET /api/v2/drm/piracy-guard
```
#### HTTP 헤더
`Authorization` (필수)\
인코딩된 JWT 토큰. 자세한 내용은 [인증 및 권한 부여](#인증-및-권한-부여)를 참조하세요.
___
`Accept-Language`\
보고서 언어. 자세한 내용은 [언어 처리](#언어-처리) 섹션을 참조하세요.
#### 쿼리 파라미터
`api_code` string (필수)\
API의 고정 코드 (`UA003001040100`)
___
`site_id` string (필수)\
사이트의 고유 ID (네 자리 영숫자)
___
`from` string\
검색 기간 시작일. [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) 표준에 따른 `YYYY-MM-DD` 형식의 날짜
___
`to` string\
검색 기간 종료일. [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) 표준에 따른 `YYYY-MM-DD` 형식의 날짜. 날짜를 입력하지 않으면 오늘 날짜 기준으로 검색합니다.
___
`time_zone` string (기본값: `+00:00`)\
[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) 표준에 따른 `±[hh]:[mm]` 형식의 UTC 오프셋
___
`search_condition` string\
키워드 검색 카테고리
:::note
현재 유효한 값은 `user_id`만 사용 가능합니다.
:::
___
`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`)\
보고서 언어. 자세한 내용은 [언어 처리](#언어-처리) 섹션을 참조하세요.
#### 요청 예시
```bash
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 ' \
--H 'Accept-Language: en'
```
#### 응답
`count` long\
총 레코드 수
___
`data` array\
Piracy Guard 로그 항목 목록
`data[].anomaly` integer\
이상 감지 결과를 숫자로 표현한 플래그. 0은 정상, 1은 이상으로 판정된 항목을 의미합니다. `anomaly_status` 필드와 동일한 값이지만 정수형으로 제공됩니다.
| 플래그 | 의미 |
| - | - |
| `0` | 이상이 감지되지 않은 `normal` 항목 |
| `1` | `anomalous`로 판정된 항목 |
___
`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으로 설정됩니다.