Media

Media adalah resource yang menampung file yang diunggah. Setiap file seperti gambar atau dokumen dikelola sebagai satu Media. Mengambil contoh toko pakaian online, foto produk "potongan samping Tumbler Stainless 500ml" adalah satu Media.

Media dikelola terpisah dari Content. Content menunjuk ke Media melalui field bertipe Refer (misalnya "foto utama" dari produk) untuk memakai file tersebut. Di CMA, Media adalah sub-resource dari Space, dan path-nya mengacu pada /spaces/{spaceId}/medias. Operasi pengelolaan dilakukan di CMA, dan Media yang sudah dipublikasikan diekspos ke luar melalui URL delivery.

Struktur resource

Berikut adalah respons single fetch dari Media yang sudah dipublikasikan, "potongan samping Tumbler Stainless 500ml". Selain sys (properti sistem), ia memiliki fields (nilai field) dan metadata (informasi tambahan seperti tag).

{
  "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": [] }
}

Key utama:

• sys.id: Identifier unik dari Media. Mengisi {mediaId} pada path single fetch, update, delete, dan publish.
• fields: Nilai field dari Media. Terdiri dari tiga bagian, yaitu title, description, dan file; bentuk detailnya dijelaskan di bawah pada Struktur file (file).
• metadata.tags: Daftar Tag yang dilekatkan pada Media ini. Setiap item berbentuk Refer<Tag>, dan bila tidak ada tag, isinya adalah array kosong [].

Berbeda dengan Content, Media tidak memiliki contentType. Tanpa kerangka yang menentukan susunan field, semua Media memiliki struktur title, description, dan file yang sama.

Struktur file (file)

fields terdiri dari tiga bagian, yaitu title, description, dan file, yang masing-masing merupakan map per locale. title dan description memetakan key Locale ke nilai string, sedangkan file memetakan key Locale ke objek file. Seperti contoh di atas, Media demo memiliki nilai pada satu key ko-KR.

Objek file dari Media yang sudah selesai dipublikasikan memiliki key berikut.

mimeGroups adalah nilai yang mengelompokkan file ke dalam klasifikasi logis. Ia memiliki satu atau lebih dari nilai berikut.

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

Bentuk objek file saat sedang diproses

File yang diunggah tidak langsung dapat dideliver tepat setelah Media dibuat. Selama sistem memproses file, dua key tambahan ikut menempel pada objek file.

• upload: Refer<Upload> yang menunjuk ke Upload yang menjadi objek pemrosesan.
• state: Status pemrosesan. Salah satu dari nilai berikut.

Setelah pemrosesan selesai, upload dan state dilepas, dan sebagai gantinya url dan detail diisi. Artinya, bila key state tidak ada dan url tersedia, file tersebut berada dalam keadaan siap dideliver.

Properti sistem (sys)

Setiap Media menyimpan properti sistem yang sama pada objek sys. space, createdBy, dan updatedBy masuk dalam bentuk Refer ({ "sys": { "id", "type": "Refer", "targetType" } }).

Berbeda dengan Content, Media tidak memiliki properti contentType. Karena ia tidak mengikuti suatu kerangka.

status adalah salah satu dari 4 nilai berikut.

Objek publish adalah pointer yang menunjuk status publikasi. Saat sedang dipublikasikan, ia memiliki semua key berikut.

Saat publikasi dibatalkan, version, at, dan by dilepas dari publish, dan hanya firstAt dan counter yang tersisa. Bila belum pernah dipublikasikan sama sekali, publish adalah { "counter": 0 }.

Objek archive hanya ada saat sedang diarsipkan. Saat diarsipkan, ia memiliki version (sys.version pada saat pengarsipan), at (waktu pengarsipan), dan by (pengguna yang mengarsipkan); bila tidak dalam keadaan diarsipkan, key archive itu sendiri tidak ada.

Nilai sys.version dan semua nilai waktu pada contoh di bawah adalah nilai pada saat pemanggilan aktual, dan berbeda-beda setiap kali dipanggil.

Siklus hidup unggah dan publikasi

Media dibuat dengan mengunggah file terlebih dahulu, lalu mereferensikan hasilnya.

1. Unggah file melalui Upload API untuk memperoleh satu Upload.
2. Buat Media dengan POST /medias yang mereferensikan Upload tersebut. Tepat setelah pembuatan, status adalah Draft dan state dari file adalah PENDING.
3. Saat sistem selesai memproses file, ia secara otomatis mengubah Media menjadi Published. Pada saat ini file menjadi siap dideliver.

Bila pada request POST diberikan header X-Weegloo-Ignore-Publish: true, publikasi otomatis dilewati dan Media dibiarkan dalam Draft. Update dan partial update juga secara default dipublikasikan ulang secara otomatis setelah pemrosesan selesai, dan bisa dimatikan dengan header yang sama.

Request update, partial update, publish, unpublish, archive, dan unarchive harus menyertakan sys.version saat ini pada header x-weegloo-version. Bila nilai ini hilang atau berbeda dengan versi saat ini, hal itu dianggap sebagai konflik perubahan bersamaan dan request ditolak. Request create dan delete tidak memiliki header ini. Transisi status seperti publish, unpublish, archive, dan unarchive tidak memiliki request body tersendiri.

Archive dan delete tidak bisa langsung dilakukan dari keadaan dipublikasikan. Anda harus membatalkan publikasi terlebih dahulu. Bila mencoba mengarsipkan Media yang dalam keadaan dipublikasikan, ia ditolak dengan WGL422007, dan bila mencoba menghapusnya, ia ditolak dengan WGL422009.

API

Base URL untuk semua endpoint di bawah adalah https://cma.weegloo.com/v1, dan diperlukan Bearer token yang mengautentikasi CMA pada header Authorization. Update, partial update, publish, unpublish, archive, dan unarchive harus mengirimkan header X-Weegloo-Version (yaitu sys.version dari resource saat ini) untuk kontrol konkurensi optimistis.

Dokumen terkait

• Upload API: Request untuk mengunggah file dan memperoleh Upload yang dipakai dalam pembuatan Media.
• Content: Data isi yang menunjuk ke Media lewat field Refer untuk memakainya.
• Tag: Label klasifikasi yang dilekatkan pada metadata.tags.