Media
최종 수정: 2026년 6월 22일
Media는 올린 파일을 담는 리소스입니다. 이미지·문서 같은 파일 하나하나가 Media 한 건으로 관리됩니다. 옷가게 쇼핑몰을 예로 들면, 상품 사진 "스테인리스 텀블러 500ml 측면 컷"이 Media 한 건입니다.
Media는 Content와 별도로 관리됩니다. Content는 Refer 타입 필드(예: 상품의 "대표 사진")로 Media를 가리켜 그 파일을 씁니다. CMA에서 Media는 Space 하위 리소스이며, 경로는 /spaces/{spaceId}/medias를 기준으로 합니다. 관리 작업은 CMA에서 수행하고, 발행된 Media는 전달 URL로 외부에 공개됩니다.
리소스 구조
다음은 발행된 Media "스테인리스 텀블러 500ml 측면 컷"의 단일 조회 응답입니다. sys(시스템 속성)와 함께 fields(필드 값)와 metadata(태그 등 부가 정보)를 가집니다.
{
"sys": {
"id": "3trmXRM3RqbgSnifyg7PV9MlFUzv3r",
"type": "Media",
"space": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } },
"publish": {
"version": 1,
"at": "2026-06-18T10:11:46.712Z",
"firstAt": "2026-06-18T10:11:46.712Z",
"counter": 1,
"by": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } }
},
"createdBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
"createdAt": "2026-06-18T10:11:46.586Z",
"updatedBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
"updatedAt": "2026-06-18T10:11:46.712Z",
"version": 2,
"status": "Published"
},
"fields": {
"title": { "ko-KR": "스테인리스 텀블러 500ml 측면 컷" },
"description": { "ko-KR": "흰 배경에서 찍은 텀블러 측면 제품 사진입니다." },
"file": {
"ko-KR": {
"fileName": "tumbler.png",
"contentType": "image/png",
"mimeGroups": ["Image"],
"url": "https://weegloo-media.com/medias/HnQ32YiH/v3r/3trmXRM3RqbgSnifyg7PV9MlFUzv3r/ko-KR/1/tumbler.png",
"detail": { "size": 50847, "image": { "width": 900, "height": 900 } }
}
}
},
"metadata": { "tags": [] }
}주요 키:
sys.id: Media의 고유 식별자입니다. 단일 조회·수정·삭제·발행 경로의{mediaId}에 들어갑니다.fields: Media의 필드 값입니다.title·description·file세 가지로 이루어지며, 자세한 모양은 아래 파일 구조 (file)에서 설명합니다.metadata.tags: 이 Media에 단 Tag 목록입니다. 각 항목은Refer<Tag>모양이며, 태그가 없으면 빈 배열[]입니다.
Media에는 Content와 달리 contentType이 없습니다. 필드 구성을 정하는 틀 없이, 모든 Media가 같은 title·description·file 구조를 가집니다.
파일 구조 (file)
fields는 title·description·file 세 가지이며, 각각 로케일별 맵입니다. title과 description은 Locale 키를 문자열 값에 매핑하고, file은 Locale 키를 파일 객체에 매핑합니다. 위 예시처럼 데모 Media는 ko-KR 키 하나에 값을 가집니다.
발행이 끝난 Media의 file 객체는 다음 키를 가집니다.
| 키 | 타입 | 설명 |
|---|---|---|
fileName | string | 올린 파일의 이름. 예: tumbler.png. |
contentType | string | 파일의 MIME 타입. 예: image/png. |
mimeGroups | array | 파일의 논리 분류 배열. 예: ["Image"]. 아래 값 목록 참조. |
url | string | 발행된 파일의 전달 URL. |
detail | object | 파일 상세. size(바이트)와, 이미지면 image: { width, height }를 가집니다. |
mimeGroups는 파일을 논리 분류로 묶은 값입니다. 다음 중 하나 이상을 가집니다.
Attachment, Plaintext, Image, Audio, Video, RichText, Presentation, Spreadsheet, PdfDocument, Archive, Code, Markup.
처리 중 file 객체의 모양
올린 파일은 Media를 만든 직후 곧바로 전달되지 않습니다. 시스템이 파일을 처리하는 동안에는 file 객체에 두 키가 더 붙습니다.
upload: 처리 대상인 Upload를 가리키는Refer<Upload>입니다.state: 처리 상태입니다. 아래 값 중 하나입니다.
state | 의미 |
|---|---|
PENDING | 처리 대기 중. |
PROCESSING | 처리 중. |
FAILED | 처리 실패. |
| 키 없음 | 처리 완료. |
처리가 끝나면 upload와 state가 빠지고, 대신 url과 detail이 채워집니다. 즉 state 키가 없고 url이 있으면 그 파일은 전달 가능한 상태입니다.
시스템 속성 (sys)
모든 Media는 공통 시스템 속성을 sys 객체에 담습니다. space, createdBy, updatedBy는 Refer 모양({ "sys": { "id", "type": "Refer", "targetType" } })으로 들어갑니다.
| 속성 | 타입 | 설명 |
|---|---|---|
id | string | 리소스 고유 식별자. |
type | string | 리소스 종류. Media는 항상 "Media". |
space | Refer<Space> | 이 Media가 속한 Space. |
publish | object | 발행 상태 포인터. 아래 키 참조. |
archive | object | 보관 정보. 보관 중일 때만 존재하며, 아니면 키가 없습니다. 아래 키 참조. |
createdBy | Refer<User> | 생성한 사용자. |
createdAt | string (date-time) | 생성 시각. |
updatedBy | Refer<User> | 마지막으로 수정한 사용자. |
updatedAt | string (date-time) | 마지막 수정 시각. |
version | integer (≥1) | 리소스 버전. 생성·수정·발행·발행취소·보관 등 모든 변경마다 1씩 올라갑니다. |
status | string (enum) | 발행 상태. 아래 4가지 중 하나. |
Media에는 Content와 달리 contentType 속성이 없습니다. 틀을 따르지 않기 때문입니다.
status는 다음 4가지 중 하나입니다.
status | 의미 |
|---|---|
Draft | 작성 중이며 아직 발행되지 않은 상태. |
Changed | 발행된 적이 있으나 그 뒤 수정되어 아직 발행되지 않은 변경분이 있는 상태. |
Published | 발행되어 있고 미발행 변경분이 없는 상태. |
Archived | 보관된 상태. |
publish 객체는 발행 상태를 가리키는 포인터입니다. 발행 중일 때는 다음 키를 모두 가집니다.
| 키 | 타입 | 설명 |
|---|---|---|
version | integer | 발행된 시점의 sys.version. |
at | string (date-time) | 마지막 발행 시각. |
firstAt | string (date-time) | 최초 발행 시각. 발행취소해도 보존됩니다. |
counter | integer | 누적 발행 횟수. |
by | Refer<User> | 마지막으로 발행한 사용자. |
발행취소하면 publish에서 version·at·by가 빠지고 firstAt·counter만 남습니다. 한 번도 발행한 적이 없으면 publish는 { "counter": 0 }입니다.
archive 객체는 보관 중일 때만 존재합니다. 보관 중이면 version(보관 시점의 sys.version)·at(보관 시각)·by(보관한 사용자)를 가지며, 보관 상태가 아니면 archive 키 자체가 없습니다.
아래 예시의 sys.version과 모든 시각 값은 실제 호출 시점의 값이며, 호출마다 달라집니다.
업로드와 발행 라이프사이클
Media는 파일을 먼저 올린 뒤, 그 결과물을 참조해 만듭니다.
- Upload API로 파일을 올려 Upload 하나를 받습니다.
POST /medias로 그 Upload를 참조해 Media를 만듭니다. 생성 직후status는Draft이고,file의state는PENDING입니다.- 시스템이 파일 처리를 마치면 Media를 자동으로
Published로 바꿉니다. 이때 파일이 전달 가능해집니다.
POST 요청에 X-Weegloo-Ignore-Publish: true 헤더를 주면 자동 발행을 건너뛰고 Draft로 둡니다. 수정·부분 수정도 기본은 처리가 끝나면 자동으로 다시 발행되며, 같은 헤더로 끌 수 있습니다.
수정·부분 수정·발행·발행취소·보관·보관해제 요청에는 x-weegloo-version 헤더에 현재 sys.version을 실어야 합니다. 이 값이 빠지거나 현재 버전과 어긋나면 동시 수정 충돌로 간주되어 요청이 거부됩니다. 생성과 삭제 요청에는 이 헤더가 없습니다. 발행·발행취소·보관·보관해제 같은 상태 전환에는 별도 요청 본문이 없습니다.
보관과 삭제는 발행 상태에서 바로 할 수 없습니다. 먼저 발행취소해야 합니다. 발행 상태인 Media를 보관하려 하면 WGL422007로, 삭제하려 하면 WGL422009로 거부됩니다.
API
아래 모든 엔드포인트의 기준 URL은 https://cma.weegloo.com/v1이며, Authorization 헤더에 CMA를 인증하는 Bearer 토큰이 필요합니다. 수정·부분 수정·발행·발행취소·보관·보관해제는 낙관적 동시성 제어를 위해 X-Weegloo-Version 헤더(현재 리소스의 sys.version)를 함께 보내야 합니다.
관련 문서
- Upload API: 파일을 올려 Media 생성에 쓸 Upload를 받는 요청.
- Content: Refer 필드로 Media를 가리켜 쓰는 본문 데이터.
- Tag:
metadata.tags에 다는 분류 라벨.