Media
最終更新: 2026年6月22日
Media はアップロードしたファイルを格納するリソースです。画像やドキュメントといったファイル 1 つひとつが Media 1 件として管理されます。アパレルのショッピングモールを例にすると、商品写真「ステンレスタンブラー 500ml サイドカット」が Media 1 件にあたります。
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の 3 つで構成され、詳しい形は後述の ファイル構造 (file) で説明します。metadata.tags: この Media に付けた Tag の一覧です。各項目はRefer<Tag>の形で、タグがなければ空配列[]になります。
Media には Content と違い contentType がありません。フィールド構成を定める枠を持たず、すべての Media が同じ title・description・file の構造を持ちます。
ファイル構造 (file)
fields は title・description・file の 3 つで、それぞれロケール別マップです。title と description は Locale キーを文字列値にマッピングし、file は Locale キーをファイルオブジェクトにマッピングします。上の例のように、デモ用の Media は ko-KR キー 1 つに値を持ちます。
発行が完了した Media の file オブジェクトは次のキーを持ちます。
| キー | タイプ | 説明 |
|---|---|---|
fileName | string | アップロードしたファイルの名前。例: tumbler.png。 |
contentType | string | ファイルの MIME タイプ。例: image/png。 |
mimeGroups | array | ファイルの論理分類の配列。例: ["Image"]。下記の値一覧を参照してください。 |
url | string | 発行されたファイルの配信 URL。 |
detail | object | ファイルの詳細。size（バイト）と、画像なら image: { width, height } を持ちます。 |
mimeGroups はファイルを論理分類でまとめた値です。次のうち 1 つ以上を持ちます。
Attachment, Plaintext, Image, Audio, Video, RichText, Presentation, Spreadsheet, PdfDocument, Archive, Code, Markup。
処理中の file オブジェクトの形
アップロードしたファイルは、Media を作成した直後にすぐ配信されるわけではありません。システムがファイルを処理している間は、file オブジェクトにさらに 2 つのキーが付きます。
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 を 1 つ受け取ります。
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に付ける分類ラベル。