세션 매니저 API 가이드

워터마크 전처리를 마친 ‘0’과 ‘1’ 두 버전의 콘텐츠(DASH 또는 HLS)는 사용자의 재생 요청 시에 실시간으로 조합되어 클라이언트에 전달됩니다. PallyCon 포렌식 워터마킹 서비스에서 제공하는 세션 매니저는 해당 재생 세션의 정보와 조합할 콘텐츠 URL을 입력받아, 최종 사용자에게 전달될 세션 URL을 생성합니다.

서비스 사이트는 아마존 CloudFront 또는 아카마이 CDN의 워터마크 연동을 통해 세션 URL에 따라 조합된 콘텐츠를 클라이언트에 스트리밍할 수 있습니다.

sequenceDiagram
    participant A as 서비스 사이트
    participant B as PallyCon 클라우드
    A ->> B: 콘텐츠URL, 세션 정보 전달
    Note right of B: 세션 매니저
    B -->> B: 세션 키(Payload) 생성 및 세션 정보 저장
    B ->> A: 세션 URL 전달

PallyCon HTTP API 규격

PallyCon 서비스에서 사용하는 각종 HTTP API 요청시 아래 규격을 따릅니다.

API 요청 규격에 대한 샘플 코드는 샘플 다운로드 페이지에서 확인하시기 바랍니다.

요청 규격

Param key Value
pallycon-apidata base64 Encoding ( JSON string )

요청 데이터 JSON 포맷

{
    "data":"{각 API 별 `API 데이터` JSON 값을 aes256 cbc 암호화한 base64 문자열}",
    "timestamp":"{yyyy-mm-ddThh:mm:ssZ}",
    "hash":"{아래 'SHA256 입력 포맷'의 문자열 값을 sha256 해시 처리한 base64 문자열}"
}

요청 데이터 명세

Key Type Required Description
data String Y 각 API마다 정의된 규격으로 생성한 JSON 문자열을 AES 암호화하고, 결과값을 base64 문자열로 입력
timestamp String Y GMT 시간대 기준으로 요청 시점의 시간을 “yyyy-mm-ddThh:mm:ssZ” 포맷으로 입력
hash String Y 아래 규격에 따라 생성한 해시값을 입력

AES256 Encryption

aes256 Encryption/Decryption 처리는 PallyCon Cloud 서비스 사이트 생성 시 발급 되는 Site 키 값을 이용하여 아래와 같이 처리 합니다. ( PallyCon 콘솔 사이트에서 확인 )

  • mode : CBC
  • AES key : 32 byte (PallyCon 콘솔 사이트에서 발급 되는 site key)
  • AES IV : fixed 16 byte (0123456789abcdef)
  • padding : pkcs7

SHA256 message Format

SHA256 해시의 입력값은 다음과 같은 문자열을 조합해 입력합니다.

[site access key] + [site_id] + [json.data] + [json.timestamp]
  • site access key: PallyCon Cloud 서비스 사이트 생성 시 발급 되는 access key 값이며 PallyCon 콘솔 사이트에서 확인 가능합니다.
  • sha256 해시 함수의 결과 값은 문자열로 변환하지 않고 바이너리 데이터 형태 그대로 base64 함수에 입력되어야 합니다.

세션 URL API

클라이언트에서 재생할 세션 URL(DASH mpd 또는 HLS m3u8 주소)을 받아오는 API입니다. 패키징 단계에서 A/B로 전처리된 결과물의 URL과 워터마크로 삽입될 세션 정보(forensic mark)를 입력값으로 전달합니다.

요청 규격

  • PallyCon HTTP API 규격으로 호출
  • URL : https://watermark.pallycon.com/api/v2/session/watermarkUrl/{site_id}
  • Method: GET

URL의 ‘site_id’ 부분은 PallyCon 콘솔 사이트에서 발급된 실제 사이트 ID를 입력해야 합니다.

API 데이터 JSON 포맷

{
    "domain": {domain},
    "output_path": {output_path},
    "cid": {cid},
    "streaming_format": {streaming_format},
    "forensic_mark": {forensic_mark},
    "wmt_type": {aes/jwt}
} 

API 데이터 명세

Key Type Required Description
domain String Y 재생할 콘텐츠 URL의 도메인 부분. 일반적으로 CDN이 적용된 콘텐츠 URL 도메인을 입력. (예: xxxx.cloudfront.net)
output_path String Y 워터마크 패키징 요청 시 입력한 출력 경로
cid String Y 콘텐츠의 고유 ID
streaming_format String Y 콘텐츠의 스트리밍 유형 (dash 또는 hls)
forensic_mark String Y 워터마크로 적용될 세션 데이터 (사용자 ID, 클라이언트 정보 등), 최대 254 byte
wmt_type String Y 세션 URL에 사용되는 워터마크 데이터 형식 (기본값: aes)
- aes: CloudFront CDN 연동에 사용되는 PallyCon 고유 규격
- jwt: Akamai, Fastly 등의 CDN 연동에 사용되는 JWT 토큰 규격

응답 규격

응답 데이터 JSON 포맷

{
    "error_code": {error_code},
    "error_message": {message},
    "data": {watermark_session_url}
} 

응답 데이터 명세

Key Type Description
error_code String “0000” : 성공, 에러인 경우 영문/숫자로 정의된 에러코드
error_message String 에러 메세지 내용
data String 성공한 경우, 변환된 세션 URL (워터마크 URL) 리턴

세션 URL 형식: 아래 설명 참조

워터마크 세션 URL 형식

  • CloudFront용 URL (aes type): <content CDN domain>/dldzkdpsxmdnjrtm/<encrypted payload>/<output_path>/<cid>/<stream_format>/<manifest file>

  • Akamai, Fastly용 URL (jwt type): <content CDN domain>/<WMT>/<output_path>/<cid>/<stream_format>/<manifest file>

  • 세션 URL 구성

    항목 설명
    content CDN domain 콘텐츠를 서비스하는 CDN의 도메인명. 요청 데이터의 도메인 값을 기준으로 설정됨
    dldzkdpsxmdnjrtm 미리 정의된 고정 키워드 (CloudFront 연동 용)
    encrypted payload 세션 매니저에서 생성된 세션 키(Payload)를 암호화한 데이터 (CloudFront 연동 용)
    WMT 세션 매니저에서 생성된 세션 키(Payload)가 포함된 JWT 토큰 (Akamai, Fastly 연동 용)
    output_path 콘텐츠가 저장된 경로. 요청 데이터의 콘텐츠 URL을 기준으로 설정됨
    cid 콘텐츠의 고유 ID (ContentID)
    stream_format 콘텐츠의 스트리밍 유형에 따라 dash 또는 hls 입력됨
    manifest file 스트리밍 유형에 따라 stream.mpd 또는 master.m3u8 입력됨

워터마크 토큰 API

세션 URL에서 사용되는 워터마크 토큰 데이터(Encrypted payload 또는 WMT)를 직접 요청하는 API입니다. 콘텐츠 경로와 CID, 스트리밍 유형 등의 형식이 고정된 세션 URL API를 사용하는 대신, 직접 임의의 규격으로 세션 URL을 구성하려는 경우에 사용할 수 있습니다.

워터마크 토큰 API를 통해 임의로 구성한 세션 URL을 재생하려면 CDN 엣지의 워터마크 임베딩 (A/B Switching) 로직을 직접 구현해야 합니다. 따라서 토큰 API는 고객사에서 직접 CDN의 워터마크 임베딩을 구현하거나 커스터마이징하는 경우에만 사용 가능합니다.

PallyCon에서 기본 제공하는 CloudFront 샘플이나 Akamai CDN 연동을 이용하는 경우에는 토큰 API 대신 세션 URL API의 사용을 권장합니다.

요청 규격

  • PallyCon HTTP API 규격으로 호출
  • URL : https://watermark.pallycon.com/api/v2/session/watermarkData/{site_id}
  • Method: GET

URL의 ‘site_id’ 부분은 PallyCon 콘솔 사이트에서 발급된 실제 사이트 ID를 입력해야 합니다.

API 데이터 JSON 포맷

{
    "forensic_mark": {forensic_mark},
    "wmt_type": {aes/jwt}
} 

API 데이터 명세

Key Type Required Description
forensic_mark String Y 워터마크로 적용될 세션 데이터 (사용자 ID, 클라이언트 정보 등), 최대 254 byte
wmt_type String Y 세션 URL에 사용되는 워터마크 데이터 형식 (기본값: aes)
- aes: CloudFront CDN 연동에 사용되는 PallyCon 고유 규격
- jwt: Akamai, Fastly 등의 CDN 연동에 사용되는 JWT 토큰 규격

응답 규격

응답 데이터 JSON 포맷

{
    "error_code": {error_code},
    "error_message": {message},
    "data": {watermark_token_data}
} 

응답 데이터 명세

Key Type Description
error_code String “0000” : 성공, 에러인 경우 영문/숫자로 정의된 에러코드
error_message String 에러 메세지 내용
data String 성공한 경우, 요청 데이터의 wmt_type 값에 따라 CloudFront 연동용 Encrypted Payload 또는 Akamai/Fastly 연동용 WMT 토큰 값을 리턴

세션 목록 API

세션 URL API를 통해 생성된 세션 정보를 조회할 수 있는 API입니다. PallyCon Console 사이트에서도 동일한 정보를 조회할 수 있습니다.

요청 규격

  • PallyCon HTTP API 규격으로 호출
  • URL : https://watermark.pallycon.com/api/v2/session/list/{site_id}
  • Method: GET

URL의 ‘site_id’ 부분은 PallyCon 콘솔 사이트에서 발급된 실제 사이트 ID를 입력해야 합니다.

API 데이터 JSON 포맷

{
    "keyword": {search keyword},
    "search_keyword_type": {watermark, sessionKey},
    "from": {yyyymmddhhmmss},
    "to": {yyyymmddhhmmss},
    "page_unit": {long value},
    "last_key": {string},
    "last_created_time": {yyyymmddhhmmss}
}

API 데이터 명세

Key Type Required Description
keyword String N 결과값에 대한 키워드 검색 시, 아래 검색 유형에 해당하는 키워드를 입력
search_keyword_type String N 키워드 검색 유형 (watermark 또는 sessionKey 입력)
from String Y 세션 API 요청 시간을 기준으로 한 검색 시작 날짜 (yyyyMMddHHmmss 형식 GMT 시간)
to String Y 검색 종료 날짜 (yyyyMMddHHmmss 형식 GMT 시간)
page_unit Long Y 조회할 항목 갯수
last_key String N 마지막으로 조회한 세션키
last_created_time String N 마지막으로 조회한 세션키의 생성 시간 (yyyyMMddHHmmss 형식 GMT 시간)

응답 규격

응답 데이터 JSON 포맷

{
    "error_code": {error_code},
    "error_message": {message},
    "count": {watermark_url},
    "lastKey": {
        "key": {sessionKey},
        "createdTime": {YYMMDDhhmmss}
    },
    "data": [{
        "key": {sessionKey},
        "forensicMark": {watermark},
        "createdTime": {YYMMDDhhmmss}
    }]
} 

응답 데이터 명세

Key Type Description
error_code String “0000” : 성공, 에러인 경우 영문/숫자로 정의된 에러코드
error_message String 에러 메세지 내용
count String 조회된 항목 갯수
lastKey Json 마지막으로 조회된 세션키 정보
data Json Array 조회된 세션 정보 목록

lastKey 항목 명세

Key Type Description
key String 마지막으로 조회된 세션키
createdTime String 마지막 조회된 세션키의 생성 날짜 (yyyyMMddHHmmss 형식 GMT 시간)

data 항목 명세

Key Type Description
key String 마지막 조회된 세션키
forensicMark String 세션 API 요청 데이터를 통해 입력된 워터마크 정보 (예: 최종 사용자 ID, IP주소 등)
createdTime String 마지막 조회된 세션키의 생성 날짜 (yyyyMMddHHmmss 형식 GMT 시간)

API 에러 코드

Code Description
0000 성공
A1000 잘못된 파라미터 값이 입력됨
A1002 Timestamp 형식이 잘못됨
A1003 Site ID를 찾을 수 없음
A1006 해당 사이트 키로 복호화에 실패함
A1007 해시 검증이 실패함
A4002 워터마크 데이터의 저장이 실패함
A4003 워터마크 데이터의 생성이 실패함
A5001 아카마이 인증서 키 등록 필요
A5002 아카마이 워터마크 토큰 오류
A7008 API 데이터 파싱 오류
A7009 API 버전이 맞지 않음
A7010 날짜 형식이 맞지 않음
A7011 Mixed manifest 생성 실패
A7012 Manifest 획득 실패
A7013 지원되지 않는 스트리밍 형식
A7014 Property 키 파일 값이 맞지 않음
A7015 빈 입력값은 허용되지 않음
A7016 forensic_mark 길이 254 바이트 초과
A7017 트라이얼 계정의 세션 API 호출 제한 초과 (1,000회)

단계 별 예제 (세션 URL API)

아래 가이드는 세션 URL API에 대해 요청 데이터를 생성하고 응답을 얻는 방법을 단계 별로 보여줍니다. 세션 목록 요청 API 등의 다른 API의 경우에도 유사한 방법으로 적용할 수 있습니다.

예제에서 사용된 입력값들은 참고 용이며, 실제 동작을 위해서는 고객사의 PallyCon 계정에 해당되는 값들을 입력해야 합니다.

1단계 - 요청 데이터 JSON 생성

JSON 예제

{
    "domain": "cdn.service-site.com",
    "output_path": "output",
    "cid": "content1",
    "streaming_format": "dash",
    "forensic_mark": "testmark.1234567",
    "wmt_type": "aes"
}

2단계 - JSON 문자열의 AES256 암호화

2단계 결과물

N5CNHHCgEPVDFBpgtHzraqNUzBZoy4pzx3fSDnzHDMek5AMlmWSlII67tNQ2MJP1NL+dSjQZlEnXp7+ATXOopJEdH1KIZ0jNjY19bRLl9aG0gJSsbS6krhNxuuDzLayT/CgPwQUge1hQj1U2xtXSbDFUfiXSFZtJLSlA/QdTwTC5NpxfLjBmtRspPh1AOuKNwgiS9HuJxV9f6NDK22unYrzZyq6HG+qNEY6O3kp8GdRkdTU62U4t9J/byiAtEkLT

3단계 - 해시 생성

  • 액세스 키: A3DfypNw0bLgR3FAa5Q2TbS1iiUK4iIf (PallyCon 콘솔 사이트에서 확인한 엑세스 키 값을 입력)
  • 사이트 ID: EXPL (PallyCon 콘솔 사이트에서 확인한 사이트 ID 값을 입력)
  • api data: 2단계 결과물
  • 타임스탬프: 2021-09-07T02:15:00Z

해시 생성을 위해 조합된 문자열

A3DfypNw0bLgR3FAa5Q2TbS1iiUK4iIfEXPLN5CNHHCgEPVDFBpgtHzraqNUzBZoy4pzx3fSDnzHDMek5AMlmWSlII67tNQ2MJP1NL+dSjQZlEnXp7+ATXOopJEdH1KIZ0jNjY19bRLl9aG0gJSsbS6krhNxuuDzLayT/CgPwQUge1hQj1U2xtXSbDFUfiXSFZtJLSlA/QdTwTC5NpxfLjBmtRspPh1AOuKNwgiS9HuJxV9f6NDK22unYrzZyq6HG+qNEY6O3kp8GdRkdTU62U4t9J/byiAtEkLT2021-09-07T02:15:00Z

3단계 결과물

Z4f4gAJPeJUytea8f4DXg7jz+vAkmzNVQEiaU7QO3tA=

4단계 - 요청 데이터 JSON 생성 및 Base64 인코딩

  • ‘data’: 2단계 결과물
  • ‘timestamp’: 3단계의 타임스탬프와 동일한 값
  • ‘hash’: 3단계 결과물

JSON 문자열

{
    "data": "N5CNHHCgEPVDFBpgtHzraqNUzBZoy4pzx3fSDnzHDMek5AMlmWSlII67tNQ2MJP1NL+dSjQZlEnXp7+ATXOopJEdH1KIZ0jNjY19bRLl9aG0gJSsbS6krhNxuuDzLayT/CgPwQUge1hQj1U2xtXSbDFUfiXSFZtJLSlA/QdTwTC5NpxfLjBmtRspPh1AOuKNwgiS9HuJxV9f6NDK22unYrzZyq6HG+qNEY6O3kp8GdRkdTU62U4t9J/byiAtEkLT",
    "timestamp":"2021-09-07T02:15:00Z",
    "hash":"Z4f4gAJPeJUytea8f4DXg7jz+vAkmzNVQEiaU7QO3tA="
}

4단계 결과물 (base64 인코딩된 JSON)

ewogICAgImRhdGEiOiAiTjVDTkhIQ2dFUFZERkJwZ3RIenJhcU5VekJab3k0cHp4M2ZTRG56SERNZWs1QU1sbVdTbElJNjd0TlEyTUpQMU5MK2RTalFabEVuWHA3K0FUWE9vcEpFZEgxS0laMGpOalkxOWJSTGw5YUcwZ0pTc2JTNmtyaE54dXVEekxheVQvQ2dQd1FVZ2UxaFFqMVUyeHRYU2JERlVmaVhTRlp0SkxTbEEvUWRUd1RDNU5weGZMakJtdFJzcFBoMUFPdUtOd2dpUzlIdUp4VjlmNk5ESzIydW5ZcnpaeXE2SEcrcU5FWTZPM2twOEdkUmtkVFU2MlU0dDlKL2J5aUF0RWtMVCIsCiAgICAidGltZXN0YW1wIjoiMjAyMS0wOS0wN1QwMjoxNTowMFoiLAogICAgImhhc2giOiJaNGY0Z0FKUGVKVXl0ZWE4ZjREWGc3anordkFrbXpOVlFFaWFVN1FPM3RBPSIKfQ==

5단계 - 세션 매니저 API 호출

파라미터 추가된 API URL

https://watermark.pallycon.com/api/v2/session/watermarkUrl/EXPL?pallycon-apidata=ewogICAgImRhdGEiOiAiTjVDTkhIQ2dFUFZERkJwZ3RIenJhcU5VekJab3k0cHp4M2ZTRG56SERNZWs1QU1sbVdTbElJNjd0TlEyTUpQMU5MK2RTalFabEVuWHA3K0FUWE9vcEpFZEgxS0laMGpOalkxOWJSTGw5YUcwZ0pTc2JTNmtyaE54dXVEekxheVQvQ2dQd1FVZ2UxaFFqMVUyeHRYU2JERlVmaVhTRlp0SkxTbEEvUWRUd1RDNU5weGZMakJtdFJzcFBoMUFPdUtOd2dpUzlIdUp4VjlmNk5ESzIydW5ZcnpaeXE2SEcrcU5FWTZPM2twOEdkUmtkVFU2MlU0dDlKL2J5aUF0RWtMVCIsCiAgICAidGltZXN0YW1wIjoiMjAyMS0wOS0wN1QwMjoxNTowMFoiLAogICAgImhhc2giOiJaNGY0Z0FKUGVKVXl0ZWE4ZjREWGc3anordkFrbXpOVlFFaWFVN1FPM3RBPSIKfQ==

API 응답 (최종 결과)

{
    "error_message":"Success",
    "error_code":"0000",
    "url":"https://cdn.service-site.com/dldzkdpsxmdnjrtm/OHVPUw4N4tUoc-wlcA72aX6Hj5a_v-HuXcLAbFwYSpwDDsiVdSLNbWnbjkVvTX20yiKw7U6nOmJzZaDep1_3YJYxfvHzof01IAVgAguBhGk=/output/ddb2b84b-c3ce-4f37-9182-c36f83fc3fce/dash/stream.mpd"
}
다음