Media

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> 结构，没有标签时为空数组 []。

与 Content 不同，Media 没有 contentType。它没有用于规定字段构成的模板，所有 Media 都具有相同的 title、description、file 结构。

文件结构 (file)

fields 由 title、description、file 三者构成，每一项都是按 Locale 划分的映射。title 和 description 将 Locale 键映射到字符串值，file 将 Locale 键映射到文件对象。如上例所示，演示 Media 仅在一个 ko-KR 键下持有值。

发布完成的 Media 的 file 对象具有以下键。

mimeGroups 是将文件按逻辑分类归并的值。具有下列值中的一个或多个。

Attachment, Plaintext, Image, Audio, Video, RichText, Presentation, Spreadsheet, PdfDocument, Archive, Code, Markup.

处理中的 file 对象结构

上传的文件在创建 Media 后不会立即传递。在系统处理文件期间，file 对象会额外附加两个键。

• upload：指向待处理 Upload 的 Refer<Upload>。
• state：处理状态。为下列值之一。

处理结束后，upload 和 state 被移除，转而填入 url 和 detail。也就是说，当没有 state 键且存在 url 时，该文件即处于可传递状态。

系统属性 (sys)

所有 Media 都将公共系统属性存放在 sys 对象中。space、createdBy、updatedBy 以 Refer 结构（{ "sys": { "id", "type": "Refer", "targetType" } }）填入。

与 Content 不同，Media 没有 contentType 属性。这是因为它不遵循模板。

status 为下列 4 种之一。

publish 对象是指向发布状态的指针。处于发布状态时，包含以下全部键。

取消发布后，publish 中会移除 version、at、by，仅保留 firstAt、counter。如果从未发布过，publish 为 { "counter": 0 }。

archive 对象仅在归档时存在。归档时它包含 version（归档时的 sys.version）、at（归档时间）、by（执行归档的用户），不处于归档状态时则没有 archive 键本身。

下方示例中的 sys.version 和所有时间值均为实际调用时刻的值，每次调用都会不同。

上传与发布生命周期

Media 先上传文件，再引用其产物来创建。

1. 通过 Upload API 上传文件，得到一个 Upload。
2. 用 POST /medias 引用该 Upload 来创建 Media。创建后 status 为 Draft，file 的 state 为 PENDING。
3. 系统完成文件处理后，会自动将 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 上的分类标签。