Pustaka media

Cara kerja media

Setiap file milik satu brand. Anda mengunggahnya sekali, lalu halaman, menu, setting, dan opsi tema merujuknya lewat id. API mengubah id itu menjadi URL, ukuran, dan teks alt saat menyusun jawaban, sehingga block tidak pernah menyimpan tautan ke file.

Semua panggilan media butuh sesi yang sudah masuk dan header X-Brand-Id. Peran:

Alur unggah

File tidak lewat API. Browser mengirimnya langsung ke penyimpanan dengan alamat bertanda tangan, lalu memberi tahu API bahwa unggahan selesai. Setelah itu API memverifikasi apa yang sampai.

Langkah 1: mulai unggahan

{
  "filename": "hero.png",
  "mime": "image/png",
  "size": 482113,
  "hash": "3f5a...sha256 hex of the file...",
  "folder_id": null
}

hash adalah SHA-256 file dalam heksadesimal (shasum -a 256 hero.png). size dibatasi per tipe, dan file yang lebih besar dijawab 422:

mime lain ditolak. Jika brand sudah punya file siap dengan hash yang sama, jawabannya mengembalikan aset itu dengan duplicate: true dan upload: null, dan Anda melewati langkah berikutnya. Jika tidak, jawabannya berisi aset yang tertunda dan objek upload: url, method (PUT), headers, dan expires_at.

Langkah 2: kirim byte

PUT file ke upload.url dan kirim persis upload.headers. Panjang dan checksum yang dinyatakan ditandatangani ke dalam alamat, sehingga penyimpanan menolak byte lain. Alamat itu menunjuk ke key staging yang hanya berlaku sekali. Pada penyedia local, alamatnya berupa route bertanda tangan di API.

curl -X PUT "$UPLOAD_URL" -H "Content-Length: 482113" \
  -H "x-amz-checksum-sha256: $CHECKSUM" --data-binary @hero.png

Pakai header yang dikembalikan API, bukan yang ada di contoh ini. Bucket Anda butuh CORS untuk origin dashboard ketika browser yang mengunggah.

Langkah 3: selesaikan

Kirim { "hash": "..." }, hash yang sama dengan langkah 1. API memeriksa ukuran dan checksum objek yang tersimpan, membaca width dan height yang sebenarnya, menulis thumbnail 480 px, dan menandai aset siap. Ukuran atau checksum yang salah dijawab 422 dan file dibuang. Panggilan kedua juga 422, dan alamat unggah lama tidak bisa lagi mengubah file yang tersimpan. File identik yang sudah ada di brand mengembalikan aset yang ada dengan deduplicated: true.

File SVG dibersihkan

SVG bisa membawa skrip, jadi tidak pernah disajikan apa adanya. Pada langkah 3, API membaca byte staging, membuang skrip, foreignObject, elemen animasi, atribut event handler, dan referensi apa pun yang bukan #fragment lokal, lalu hanya menyimpan file yang sudah bersih. File yang bukan XML valid, punya doctype atau entity, atau tidak berakar di <svg> dijawab 422 dan tidak ada yang disimpan.

Folder dan daftar

GET /v1/manage/media menerima folder_id (atau none untuk file tanpa folder), q (nama file), ids (sampai 40 id dipisah koma), sort (created_at, filename, size), direction, dan per_page (1 sampai 100, bawaan 40). Setiap baris membawa usage_count.

Folder adalah resource di /v1/manage/media-folders. Folder punya name (paling banyak 120 karakter) dan parent_id opsional. Menghapus folder yang masih berisi file atau folder dijawab 409 sampai Anda mengirim move_contents=1, yang memindahkan semua isinya naik satu tingkat.

Pindahkan file dengan PATCH /v1/manage/media/{asset} dan folder_id, atau sekaligus banyak:

{ "action": "move_to_folder", "folder_id": "01m...", "ids": ["01m...", "01n..."] }

action adalah move_to_folder (semua anggota) atau delete (publisher atau admin), dengan 1 sampai 100 id. Jawabannya selalu 200 dengan { action, done, failed, results[] }. Setiap hasil adalah moved, deleted, not_found, atau in_use. File yang sedang dipakai tidak pernah dihapus.

Teks alt dan titik fokus

{
  "alt": { "en": "A technician replacing a phone screen", "id": "Teknisi mengganti layar ponsel" },
  "focal_x": 0.4,
  "focal_y": 0.3
}

Teks alt disimpan per bahasa, paling banyak 500 karakter masing-masing, dan setiap key harus locale milik brand. focal_x dan focal_y bernilai 0 sampai 1. Anda juga bisa mengganti nama file dengan filename.

Prop media di sebuah block butuh teks alt, kecuali prop itu menyetel decorative: true. Peringatan saat terbitkan dan laporan kesehatan dashboard menandai gambar tanpa teks alt. Ketika perubahan alt atau titik fokus menyentuh file yang sedang dipakai, situs di-purge.

Ganti file

Publisher mengirim { "mime", "size", "hash" } dan menerima objek upload baru, lalu mengulang langkah 2 dan 3. File mempertahankan id, teks alt, dan semua referensinya. Jenisnya harus sama: gambar hanya bisa menggantikan gambar, PDF hanya PDF. API menghapus objek dan thumbnail lama serta mengantrekan webhook purge media.replaced, sehingga cache menyegarkan diri.

File yang dipakai tidak bisa dihapus

Jawabannya mendaftar tempat file dipakai: entries, fragments, menus, settings, templates, dan theme, dengan total. DELETE /v1/manage/media/{asset} (publisher) dijawab 422 selama file ada di revisi terbit atau revisi terbaru sebuah entri, sebuah part, menu, setting seperti logo atau gambar bagikan bawaan, atau tema. Jawabannya menyebut entri dan other_usages. Hapus referensinya dulu, baru hapus file.

Menerbitkan atau me-rollback revisi yang menunjuk ke file terhapus juga ditolak.

Tempat file disimpan

Secara bawaan file masuk ke penyimpanan bersama AtlasCMS. Admin bisa memberi brand bucket sendiri.

{
  "provider": "r2",
  "endpoint": "https://<account>.r2.cloudflarestorage.com",
  "region": "auto",
  "bucket": "acme-media",
  "public_url": "https://media.acme.example",
  "access_key_id": "...",
  "secret_access_key": "..."
}

provider adalah shared, s3, r2, b2, custom, atau local. Penyedia remote butuh bucket dan region, dan r2, b2, serta custom juga butuh endpoint. Endpoint dan public_url harus HTTPS di port 443 dan mengarah ke alamat publik. Kredensial bersifat hanya-tulis: API menyimpannya terenkripsi dan GET hanya melaporkan credentials_set. Mengubah penyedia, endpoint, atau bucket butuh kredensial baru. POST /v1/manage/media/storage/test memeriksa koneksi tanpa menyimpan. File yang sudah diunggah tetap bisa diakses setelah Anda berpindah.

Berpindah tidak memindahkan file

Unggahan baru masuk ke penyimpanan baru. File lama mempertahankan key-nya dan tetap di tempatnya.

Assets base URL

Setting media menentukan dari alamat mana file publik disajikan dan bagaimana unggahan baru dinamai. Admin menulisnya dengan PUT /v1/manage/settings:

{ "settings": { "media": { "assets_base_url": "https://cdn.acme.example/atlas", "upload_structure": "year_month", "keep_filename": false } } }

assets_base_url bernilai null (pakai alamat disk) atau alamat HTTPS di port 443 dengan nama host biasa. upload_structure adalah year_month, year, flat, atau pola folder kustom. keep_filename: true mempertahankan nama asli yang sudah dibersihkan alih-alih id acak. Database hanya menyimpan key, jadi mengubah base URL memindahkan semua tautan publik sekaligus. Tautan yang ditempel di teks kaya tidak ditulis ulang.

POST /v1/manage/media/assets-base-url/test (admin) menulis file uji kecil dan memeriksa bahwa alamat tersebut menyajikannya.