뒤로
Object Storage
다큐멘트 센터 Object Storage API Return Data Specification

Return Data Specification

최신 업데이트：2025-08-18 15:33:46

이 문서는 오브젝트 스토리지 서비스의 ​​데이터 응답 및 콜백 메커니즘​​에 대한 포괄적인 가이드로, 다음 세 가지 핵심 서브시스템을 다룹니다.

  • ​​클라이언트 응답 제어(ReturnBody)​​: 동적 변수($(bucket), $(x:customVar))를 사용하여 클라이언트에 반환되는 내용을 맞춤 설정할 수 있습니다. 일반 업로드는 키-값 쌍, 멀티파트 업로드는 JSON 형식이 지원됩니다.
  • ​​서버 콜백 프로토콜(CallbackBody)​​: HMAC-SHA1 서명이 적용된 콜백을 사용해 비동기 시스템 연동이 가능합니다.
  • ​​파일 네이밍 및 처리(SaveKey/PersistentOps)​​: 타임스탬프 또는 UUID 변수로 저장 경로를 생성하고, 동영상 트랜스코딩 등 자동화 워크플로우를 구성할 수 있습니다.

returnBody 반환 메커니즘

시나리오 1: returnBody와 returnUrl로 지정된 요청 URL 반환

예시:

    bucket:     image
    key:        205.jpg
    returnBody: bucket=$(bucket)&key=$(key)
    returnUrl:  http://www.abc.com

업로더에게 반환되는 내용:

    http://www.abc.com?bucket=image&key=205.jpg&hash=610d0284a0923298247d3a269ee28908cdcc7476

시나리오 2: returnBody 지정, returnUrl 미지정 시, returnBody로 지정한 내용을 반환

returnBody를 사용하면 클라이언트로 반환되는 정보를 자유롭게 커스터마이징할 수 있습니다. 현재 커스텀 치환 변수와 지정 치환 변수의 두 가지 파라미터 방식을 지원하며, 혼합 사용도 가능합니다.

참고:

  1. 일반 업로드 시 returnBody에는 기본적으로 파일의 해시값이 포함됩니다. 멀티파트 업로드 시에는 해시값과 key가 기본 반환됩니다.
  2. 설정 후 returnBody로 반환되는 내용은 URL-safe Base64로 인코딩됩니다. 아래 예시는 디코딩된 내용입니다.

커스텀 치환 변수

  • 형식: $(x:variable)
  • 예시:
    ReturnBody: position=$(x:position)&message=$(x:message)
    Request Parameter: position=abc&message=Success

일반 업로드에서 업로더로 반환되는 내용:

    position=abc&message=Success&hash=610d0284a0923298247d3a269ee28908cdcc7476

멀티파트 업로드에서 업로더로 반환되는 내용:

    {
        "position":"abc",
        "message":"Success",
        "key":"filename",
        "hash":"610d0284a0923298247d3a269ee28908cdcc7476"
    }

참고: 커스텀 변수는 반드시 UTF-8 형식이어야 하며, & 기호를 포함할 수 없습니다. 포함 시 인코딩 오류가 발생합니다.

특수 치환 변수

  • 형식: $(variable)
  • 예시:
    returnBody：url=$(url)&fsize=$(fsize)&bucket=$(bucket)
    url=http://abc.com/1.jpg
    fsize=1231341
    bucket=test

일반 업로드 시 업로더로 반환되는 내용:

    url=http://abc.com/1.jpg&fsize=1231341&bucket=test&hash=610d0284a0923298247d3a269ee28908cdcc7476

멀티파트 업로드 시 업로더로 반환되는 내용:

    {
        "url":"http://abc.com/1.jpg",
        "fsize":"1231341",
        "bucket":"test",
        "key":"1.jpg",
        "hash":"610d0284a0923298247d3a269ee28908cdcc7476"
    }

참고: 파라미터의 나열 순서는 반환 값의 결과 순서와 동일합니다.

  • 변수 설명:
지정 변수 설명 업로드 인터페이스
$(persistentID) 업로드 전처리 또는 영구 처리 트리거의 프로세스 ID 일반 업로드(멀티파트 업로드 시 제한적 사용)
$(bucket) 대상 버킷명 추출 일반 업로드/멀티파트 업로드
$(key) 버킷에 저장되는 파일 이름 일반 업로드/멀티파트 업로드
$(fname) 원본 파일 이름 일반 업로드/멀티파트 업로드
$(hash) 리소스의 Etag 일반 업로드/멀티파트 업로드
$(fsize) 리소스 크기(바이트 단위) 일반 업로드/멀티파트 업로드
$(url) 리소스 접근 경로 일반 업로드/멀티파트 업로드
$(ip) 요청의 소스 IP 일반 업로드/멀티파트 업로드
$(imageInfo) 업로드 이미지 기본 정보 일반 업로드/멀티파트 업로드
$(exif) 업로드 이미지의 Exif 정보 일반 업로드/멀티파트 업로드
$(avinfo) JSON 형식의 동영상 메타데이터, URL-safe Base64 인코딩됨 일반 업로드/멀티파트 업로드
$(mimeType) 리소스 타입(예: JPG 이미지의 경우 image/jpg) 일반 업로드/멀티파트 업로드

callbackBody 콜백 메커니즘

callbackBody는 callbackUrl이 활성화된 경우, 클라이언트에 반환되는 정보를 포맷커스터마이징할 때 사용되며, 서버에 콜백을 호출합니다.

참고: 콜백 내용은 URLEncode로 인코딩되어 전달되며, 콜백 서버에서 수신 후 디코딩 처리가 가능합니다.

callbackBody는 정수, 커스텀 치환 변수, 지정 치환 변수를 모두 지원하며, 조합하여 사용할 수 있습니다.

콜백 데이터 설명

정수

  • 형식: key1=value1&key2=value2
  • 설명: 오브젝트 스토리지 플랫폼은 이 상수 파라미터를 받은 후 별도의 처리 없이 callbackUrl로 연동합니다.
  • 예시:
username=john&age=21

커스텀 치환 변수

  • 형식: $(x:variable)
  • 예시:
    callbackBody: position=$(x:position)&message=$(x:message)

$(x:position)=abc, $(x:message)=Success 이면 콜백 서버에 전달되는 값은 다음과 같습니다.

    position%3dabc%26message%3dSuccess%0a%0a

참고: 커스텀 변수는 UTF-8 형식이어야 하고 & 불허(포함 시 인코딩 오류).

특수 치환 변수

  • 형식: $(variable)
  • 예시:
    callbackBody: url=$(url)&fsize=$(fsize)&bucket=$(bucket)
    url=http://abc.com/1.jpg
    fsize=1231341
    bucket=test

콜백 서버로 반환되는 값(URLEncode 인코딩):

    url%3daHR0cDovL2FiYy5jb20vMS5qcGc%3d%26fisize%3d1231341%26bucket%3dtest%0a
  • 변수 설명:
지정 변수 설명 업로드 인터페이스
$(persistentID) 업로드 전처리/영구 트리거의 프로세스 ID 일반 업로드(멀티파트 업로드 시 제한적)
$(bucket) 업로드 대상 버킷명 일반 업로드/멀티파트 업로드
$(key) 공간에 저장되는 파일 이름 일반 업로드/멀티파트 업로드
$(fname) 원본 파일명 일반 업로드/멀티파트 업로드
$(hash) 리소스의 Etag 일반 업로드/멀티파트 업로드
$(fsize) 리소스 크기(바이트) 일반 업로드/멀티파트 업로드
$(mimeType) 리소스 타입(예: image/jpg) 일반 업로드/멀티파트 업로드
$(url) 실제 리소스 접근 경로, URL-safe Base64 인코딩됨 일반 업로드/멀티파트 업로드
$(ip) 요청의 소스 IP 일반 업로드/멀티파트 업로드
$ (costTime) 서버가 요청을 받고 콜백 시작까지 시간(밀리초) 일반 업로드/멀티파트 업로드
$(avinfo) 비디오 메타데이터, JSON, URL-safe Base64 인코딩 일반 업로드/멀티파트 업로드
$(imageInfo) 업로드 이미지의 기본정보, URL-safe Base64 인코딩 일반 업로드/멀티파트 업로드
$(exif) 업로드 이미지의 Exif, URL-safe Base64 인코딩 일반 업로드/멀티파트 업로드
$(mimeType) 리소스 타입(예: image/jpg) 일반 업로드/멀티파트 업로드

콜백 응답 설명

콜백 서버의 응답 코드와 JSON 형식의 응답 내용을 받은 후, 오브젝트 스토리지 플랫폼은 해당 응답을 기반으로 클라이언트에 결과를 전달합니다.

  1. 콜백 서버가 200 응답과 함께 JSON 문자열을 반환하면, 오브젝트 스토리지는 200 상태코드와 함께 다음과 같이 반환합니다.
    {
      "hash": "<hash string>",
      "response": "<response string>"
    }
  1. 콜백 서버의 응답이 비정상적일 경우, 오브젝트 스토리지는 579 상태코드와 함께 아래와 같이 반환합니다.
    {
      "hash": "<hash string>",
      "error": {
        "callbackUrl": "<callbackUrl string>",
        "callback_bodyType": "<callback_bodyType string>",
        "callback_body": "<callback_body string>",
        "token": "<token string>",
        "err_code": "<err_code string>",
        "error": "<unexpected response>"
      }
    }

콜백 보안 메커니즘

CDNetwork 오브젝트 스토리지는 콜백 요청 헤더에 Authorization 필드를 추가합니다.

형식:

    <Accesskey>:<Urlsafe_Base64_Encode(hmac_sha1(callBackUrlWithQuery+"\n"+urlsafe_base64_encode(callbackBody),SecretKey))>

예시:

    d0e56f9f4a75267eba123348f839fbedcd9464c6:OTQzNzU5YWVjOTZlNTRlMWIwYmQzZTA2ZDhjMTFhOWEyNGM1ZjIzZg==

콜백 재시도 메커니즘

업로드 콜백 실패 시 기본적으로 3회 연속 재시도를 진행하며, 이후 1분마다 5회(총8회) 재시도를 합니다.

  1. 재시도 후 콜백이 성공하면 정상 콜백 응답(상태코드 200)이 반환됩니다.
  2. 재시도 이후에도 콜백 서버의 정상 응답이 없으면 비정상 콜백 응답(상태코드 579)이 반환됩니다.

saveKey 사용자 지정 네이밍

saveKey는 리소스 명칭 커스터마이징에 사용하며, 업로드 범위에서 key가 지정되지 않은 경우에만 동작합니다. 단일 파일의 일반 업로드에서만 지원됩니다.

saveKey는 정수, 커스텀 치환 변수, 지정 치환 변수를 지원하며, 조합해서 사용할 수 있습니다.

리소스 이름 설명

정수

  • 형식: value
  • 설명: 상수 파라미터를 지정하면, 오브젝트 스토리지는 별도 처리 없이 그대로 이름에 사용합니다.
  • 예시:
    saveKey: constant

폴더

형식: dirname/key

  • 설명: 오브젝트 스토리지는 멀티 레벨 디렉토리 개념이 없으나, 파일명을 활용해 가상 경로 구현이 가능합니다.
  • 예시:
    saveKey: dir/key

커스텀 치환 변수

형식: $(x:variable)
예시:

    saveKey: $(x:position)

$(x:position)= test일 때, 저장 파일명은 test가 됩니다.

참고: 커스텀 변수는 UTF-8이어야 하며 &를 포함할 수 없습니다.

특수 치환 변수

  • 형식: $(variable)
  • 예시:
    saveKey: $(year)/$(month)/$(hash)

예를 들어, 현재 시각이 2016년 4월이면, 업로드한 파일은 2016/04/해시로 저장됩니다.

  • 변수 설명:
지정 변수 설명
$(fname) 업로드 원본 파일명
$(hash) 리소스의 Etag
$(mimeType) 리소스 타입(예: image/jpg)
$(suffix) 리소스 확장자(없으면 unknown)
$(fprefix) 확장자를 제외한 파일명
$(uuid) 난수
$(year) 업로드 연도(예: 2015)
$(month) 업로드 달(예: 01)
$(day) 업로드 일(예: 01)
$(hour) 업로드 시(예: 01)
$ (min) 업로드 분(예: 01)
$(sec) 업로드 초(예: 01)

트랜스코딩 명령어 설명

동영상 트랜스코딩 및 스크린샷 관련 명령어는 Ops 파라미터 포맷을 참고하세요.

예시:

동영상 트랜스코딩:

    persistentOps=avthumb/mp4/vb/64k|saveas/YnVja2V0OmZpbGVrZXk=;avthumb/flv/vb/64k|saveas/YnVja2V0OmZpbGVrZXk=

동영상 스크린샷:

    persistentOps=vframe/jpg/offset/10|saveas/YnVja2V0OmZpbGVrZXk=;vframe/jpg/offset/15|saveas/YnVja2V0OmZpbGVrZXk=

참고: 여러 명령어는 ;로 이어서 사용할 수 있습니다.

이 문서의 내용이 도움이 되었습니까?
예
아니오
정상적으로 제출되었습니다.피드백을 주셔서 감사합니다.앞으로도 개선을 위해 노력하겠습니다.

CDNetworks Inc., © 2025. 1840 Enterprise Way, Monrovia, CA 91016 – All rights reserved.