Katalog Statement

Setiap elemen array statements adalah satu statement. Dokumen ini merangkum field, perilaku, dan hasil dari 17 jenis statement. Setiap posisi nilai mengikuti aturan Ekspresi nilai (referensi, literal, JsonLogic, locale map).

Ringkasan statement

Panggilan siklik dibatasi maksimal 3 kali. Pernyataan penulisan sumber daya di atas (ResourceCreate, ResourceUpdate, ResourcePublish, dll.) memicu peristiwa perubahan, dan peristiwa tersebut dapat menjalankan Script lagi melalui Webhook. Rantai seperti ini (Script → peristiwa → Webhook → Script → …) berlanjut paling banyak 3 kali. Setelah itu, platform menghentikannya secara otomatis untuk mencegah perulangan tak terhingga.

Field umum

{ "type": "<StatementType>", "name": "<opsional, unik dalam script>", /* ...field khusus per tipe... */ }

• type: diskriminator. Salah satu nilai dari tabel di atas (wajib).
• name: opsional. Jika disertakan, hasilnya diikat ke konteks pada /<name>, sehingga statement berikutnya dapat mereferensikannya sebagai { /<name>/... }. Hilangkan jika hasilnya tidak digunakan.
• Aturan nama binding: name (dan as pada Loop) merupakan key yang langsung diletakkan pada root konteks, sehingga divalidasi saat disimpan. Nama tidak boleh berupa string kosong dan tidak boleh mengandung / atau ~ (harus dapat dipakai sebagai key JSON Pointer), tidak boleh sama dengan root yang dicadangkan (payload, vars, error), dan harus unik dalam satu Script. Jika dilanggar, penyimpanan ditolak masing-masing dengan WGL400033 (format), WGL400032 (kata cadangan), dan WGL400034 (duplikat).

Bentuk referensi entitas

Referensi entitas seperti contentType dan target diseragamkan menjadi satu bentuk: { "sys": { "id": <ekspresi nilai> } }. Hanya sys.id yang diperlukan, dan tipe target disimpulkan dari resource (sys.type dan sys.targetType dihilangkan).

• contentType.sys.id biasanya berupa literal (mis. "ct_post").
• target.sys.id biasanya berupa ekspresi nilai { /ptr } (diselesaikan saat runtime; mis. { /payload/sys/id }).

resource

Statement keluarga resource menentukan jenis target dengan resource: "Content" | "Media".

Penulisan resource

Setiap statement penulisan memiliki propagateEvents (default false). Jika disetel true, penulisan tersebut memancarkan EntityEvent-nya sendiri (memicu pekerjaan lanjutan seperti pengindeksan pencarian dan Webhook). Default-nya tidak memancarkan (penulisan sistem yang senyap).

ResourceCreate

Membuat Content atau Media. Content dan Media berbagi model fields, dan nilainya berupa locale map.

• file dari Media: nilai fields.file.{locale} adalah instruksi ingest { "source": <ekspresi nilai>, "encoding": "url"|"base64" } (keduanya wajib). Penulisan Media yang menyertakan file bersifat khusus Async (di latar belakang, engine memprosesnya secara inline lalu mempublikasikannya; berlaku sama untuk url dan base64). Anda juga dapat membuat Media tanpa file (fileless). Jika publish:true tetapi tidak ada file atau pemrosesan belum selesai, tahap publikasi menghasilkan error; jika publish:false, statusnya tetap Draft.
• Hasil (binding name): resource yang dibuat. { /<name>/sys/id }, { /<name>/fields/<field>/<locale> }.

// Content
{ "type": "ResourceCreate", "resource": "Content", "contentType": { "sys": { "id": "ct_post" } },
  "fields": { "title": { "en-US": "{ /payload/fields/title }" } }, "publish": true, "name": "post" }
 
// Media. file adalah instruksi ingest (khusus Async)
{ "type": "ResourceCreate", "resource": "Media",
  "fields": {
    "title": { "en-US": "{ /payload/fields/prompt }" },
    "file":  { "en-US": { "source": "{ /gen/body/data/0/url }", "encoding": "url" } }
  }, "name": "img" }

ResourceUpdate

Mengganti sepenuhnya field dari Content atau Media target (PUT). Apa pun yang Anda berikan di fields menjadi kumpulan field yang baru, dan field serta locale yang tidak ada di sini akan dihapus. Untuk mengubah sebagian saja, gunakan ResourcePatch.

Jika Anda menggunakan Update hanya untuk mengubah metadata Media, file tidak disertakan sehingga semua file terhapus (karena ini penggantian penuh). Untuk perubahan sebagian, selalu gunakan ResourcePatch. Update yang menyertakan file bersifat khusus Async.

{ "type": "ResourceUpdate", "resource": "Content", "target": { "sys": { "id": "{ /payload/sys/id }" } },
  "fields": { "title": { "en-US": "Hello", "ko-KR": "안녕" }, "status": { "en-US": "published" } } }

ResourcePatch

Menggabungkan sebagian field dari Content atau Media target (PATCH). Hanya menimpa field (dan locale di dalamnya) yang Anda berikan di fields, dan membiarkan field serta locale yang tidak disebutkan tetap apa adanya. Bentuk nilai, locale, version, dan publish sama seperti ResourceUpdate.

• Menghapus locale atau file tertentu: berikan null literal sebagai nilai. Misalnya: "title": { "fr-FR": null } (menghapus judul fr-FR), "file": { "en-US": null } (menghapus file en-US). Ekspresi nilai yang dievaluasi menjadi null saat runtime bukanlah penghapusan, melainkan error (hanya null literal yang menghapus).
• Jika Anda memberikan instruksi ingest pada file Media, file untuk locale tersebut akan diganti (khusus Async). Jika file tidak diberikan, file tetap dipertahankan.

// +1 hanya pada viewCount(en-US). title, locale lain, dan sisanya tetap dipertahankan
{ "type": "ResourcePatch", "resource": "Content", "target": { "sys": { "id": "{ /payload/sys/id }" } },
  "fields": { "viewCount": { "en-US": { "+": [ "{ /payload/fields/viewCount }", 1 ] } } } }

ResourceDelete

Menghapus target. Hanya status Draft dan Archived yang dapat dihapus. Jika Published atau Changed, penghapusan ditolak, sehingga Anda harus ResourceUnpublish terlebih dahulu (untuk Media, juga ditolak selama file sedang diproses (busy)). Ini tidak melakukan auto-unpublish (sama seperti CMA/ACMA).

{ "type": "ResourceDelete", "resource": "Content", "target": { "sys": { "id": "{ /payload/sys/id }" } } }

ResourcePublish, ResourceUnpublish, ResourceArchive, ResourceUnarchive

Mengontrol status publikasi dan pengarsipan target secara independen. Keempatnya memiliki field yang sama. Prasyarat status untuk setiap operasi sama seperti CMA/ACMA (publish tidak diperbolehkan dari Archived dan memerlukan pemrosesan file yang selesai; unpublish hanya dari Published/Changed; archive hanya dari Draft; unarchive hanya dari Archived).

{ "type": "ResourcePublish",   "resource": "Content", "target": { "sys": { "id": "{ /payload/sys/id }" } } }
{ "type": "ResourceUnpublish", "resource": "Content", "target": { "sys": { "id": "{ /payload/sys/id }" } } }
{ "type": "ResourceArchive",   "resource": "Media",   "target": { "sys": { "id": "{ /m/sys/id }" } } }

Pembacaan resource

Statement pembacaan tidak mengubah status (tidak ada propagateEvents).

Ketiga statement pembacaan menentukan salinan tersimpan mana yang dibaca melalui from (opsional, default Current). Current adalah draft terbaru yang dilihat oleh Content Studio (nilai yang dibaca CMA/ACMA), sedangkan Published adalah snapshot terpublikasi (nilai pada saat publikasi terakhir yang dikirimkan CDA/ACDA).

Selain itu, ResourceFind dan ResourcePageRead dapat mengaktifkan Pencarian Lanjutan (Advanced Search) melalui advanced (opsional, default false). Ini khusus Content, sehingga diabaikan untuk pembacaan Media. Saat aktif, where dapat menggunakan operator regex, near, dan within serta pencarian teks lengkap (pada field LongText yang pencarian teks lengkapnya aktif, eq juga menemukan item yang mengandung nilai tersebut, dengan pencocokan parsial atau serupa), dan order dapat mengurutkan berdasarkan fields.*. Saat tidak aktif, ketiga operator itu ditolak, eq pada teks menjadi pencocokan persis, dan prefix serta operator perbandingan dan daftar tetap berfungsi terlepas dari Pencarian Lanjutan. Item yang baru dibuat atau diubah memerlukan waktu sesaat (sekitar 1 detik) untuk tercermin di pencarian lanjutan, sehingga bisa terlewat oleh kueri pencarian lanjutan yang langsung menyusul. Untuk membaca item yang baru ditulis dengan segera, gunakan ResourceRead berdasarkan id (penyimpanan utama, tanpa jeda) atau lakukan kueri berdasarkan sys.id yang dikembalikan oleh penulisan.

Di where dan order, field dari Content ditulis sebagai fields.<field> (nama field saja tidak dikenali). Pada fields.<field>, mesin secara otomatis menerapkan locale default Space, sehingga Anda tidak menambahkan locale secara langsung. fields.status dan fields.slug pada contoh di bawah sudah merupakan kueri locale default. Hanya ketika ingin menargetkan locale tertentu (bukan default), tentukan secara eksplisit sebagai fields.<field>.<locale> (mis. fields.title.ko-KR). sys.* (mis. sys.createdAt) dan createdBy (:self) ditulis apa adanya tanpa fields.. Aturan selengkapnya ada di locale where·order pada Ekspresi nilai.

ResourceRead

Membaca satu item berdasarkan id (get-by-id). Hasilnya mengikat seluruh resource ke nama.

• Hasil: mereferensikan { /<name>/sys/id } dan { /<name>/fields/<field>/<locale> } secara langsung (items/0 tidak diperlukan).
• Jika target tidak ada, akan terjadi error. Anda dapat menanganinya dengan membungkusnya dalam Try.

{ "type": "ResourceRead", "resource": "Content",
  "target": { "sys": { "id": "{ /payload/fields/orderId }" } }, "name": "order" }

ResourceFind

Membaca satu item pertama yang cocok dengan filter. Jika tidak ada, hasilnya null. Gunakan untuk menemukan satu record berdasarkan kunci bisnis unik (slug, email, sku).

• Hasil: mengikat resource yang pertama cocok ke nama. Referensikan secara langsung dengan { /<name>/fields/<field>/<locale> }. Karena bernilai null saat tidak ada, bercabanglah berdasarkan keberadaannya dengan { "==": [ "{ /<name> }", null ] } (pola find-then-upsert yang umum).

{ "type": "ResourceFind", "resource": "Content", "contentType": { "sys": { "id": "ct_article" } },
  "where": { "fields.slug": { "eq": "{ /payload/fields/slug }" } }, "name": "found" }

ResourcePageRead

Pembacaan dengan filter, urutan, dan halaman.

• Hasil: { items, next }. { /<name>/items/0/... }, dan halaman berikutnya adalah { /<name>/next }.
• Untuk menelusuri semuanya, gunakan Loop while "{ /vars/hasMore }" bersama cursor dan akumulasi SetVar (lihat Cookbook).

{ "type": "ResourcePageRead", "resource": "Content", "contentType": { "sys": { "id": "ct_post" } },
  "where": { "fields.status": { "eq": "draft" } }, "order": "-sys.createdAt", "limit": 100, "name": "page" }

Eksternal

Http

Memanggil HTTP eksternal. Jika ada Http, executionMode harus Async (ExternalIo).

• Hasil: { status, body }. { /<name>/status }, { /<name>/body/... }.
• Batas ukuran respons: Body respons berukuran maksimum 10MiB. Jika melebihi itu, panggilan ini gagal dengan pengecualian dan dapat ditangani seperti kegagalan runtime lainnya dengan Try/catch (ini adalah kegagalan berbasis ukuran, jadi tidak diabaikan oleh ignoreStatusCode).

{ "type": "Http", "method": "POST", "url": "https://api.llm.com/v1/gen",
  "headers": [ { "key": "Authorization", "value": "Bearer sk-...", "secret": true } ],
  "body": { "prompt": "{ /payload/fields/prompt }" }, "timeoutMs": 15000, "retry": 1, "name": "resp" }

Variabel

SetVar

Mendeklarasikan atau memperbarui variabel mutable berlingkup script. Referensikan dengan { /vars/<var> } (JsonLogic tidak memiliki deklarasi variabel, jadi ini disediakan sebagai statement).

{ "type": "SetVar", "var": "total", "value": 0 }
{ "type": "SetVar", "var": "total", "value": { "+": [ "{ /vars/total }", "{ /row/qty }" ] } }   // akumulasi
{ "type": "SetVar", "var": "ids",   "value": { "merge": [ "{ /vars/ids }", [ "{ /row/sys/id }" ] ] } }  // kumpulkan ke array

Alur kontrol

If

Percabangan kondisional. condition adalah JsonLogic, dan nilai benar/salah mengikuti aturan penilaian benar dan salah.

{ "type": "If",
  "condition": { "<": [ "{ /wallet/fields/balance/en-US }", "{ /payload/fields/cost }" ] },
  "then": [ { "type": "Return", "value": { "ok": false, "reason": "insufficient credit" } } ],
  "else": [ /* ... */ ] }

Loop

Perulangan. Pilih satu mode: over (foreach), while (kondisi), atau for (hitungan). Dalam mode apa pun, engine menerapkan batas atas dengan maxIterations (untuk mencegah perulangan tak terbatas). Panggilan eksternal di dalam body (Http, ingest file Media) dilarang.

// foreach
{ "type": "Loop", "over": "{ /payload/fields/items }", "as": "item", "maxIterations": 100,
  "body": [ { "type": "ResourceCreate", "resource": "Content", "contentType": { "sys": { "id": "ct_item" } },
             "fields": { "name": { "en-US": "{ /item/name }" } } } ] }
 
// while
{ "type": "Loop", "while": "{ /vars/hasMore }", "maxIterations": 1000, "body": [ /* ... */ ] }
 
// counted (1..10 step 2)
{ "type": "Loop", "for": { "from": 1, "to": 10, "step": 2 }, "as": "i", "maxIterations": 100, "body": [ /* ... */ ] }

Parallel

Menjalankan cabang-cabang secara bersamaan dan melanjutkan setelah join. Referensi antar-cabang tidak diperbolehkan (jika ada ketergantungan, tempatkan secara berurutan).

{ "type": "Parallel", "branches": [
  [ { "type": "Http", "method": "GET", "url": "https://api.a.com/x", "name": "a" } ],
  [ { "type": "Http", "method": "GET", "url": "https://api.b.com/y", "name": "b" } ]
] }

Return

Ini adalah return seperti dalam pemrograman pada umumnya. Mengembalikan hasil Script kepada pemanggil dan berhenti secara normal pada titik itu.

• Jika Return tidak pernah tercapai, tidak ada nilai yang dikembalikan. Untuk mengembalikan hasil, tentukan value secara eksplisit.
• Karena ini adalah penghentian normal, bukan pengecualian atau throw, ini bukan target catch (bahkan di dalam Try, ini menghentikan seluruh Script, tetapi finally tetap dijalankan).
• Guard juga diekspresikan dengan statement ini: If yang dikombinasikan dengan then:[Return] (kembalikan saat kondisi dilanggar, sehingga bagian setelahnya tidak dijalankan). Ini salah satu dari beberapa kegunaannya.

{ "type": "Return", "value": { "orderId": "{ /order/sys/id }", "status": "paid" }, "statusCode": 201 }
{ "type": "Return", "value": { "reason": "payment failed" }, "isError": true, "statusCode": 402 }

Try

Penanganan pengecualian.

• Jika catch menanganinya, Script tidak dibatalkan. Hanya kegagalan tanpa catch yang membatalkan Script (termasuk upaya kompensasi).
• Apa yang dianggap "kegagalan", dan batasan kompensasi (compensation), dibahas dalam Semantik eksekusi, batasan, dan keamanan.

{ "type": "Try",
  "body":    [ { "type": "Http", "method": "POST", "url": "https://primary.api/gen", "name": "resp" },
               { "type": "ResourceCreate", "resource": "Content", "contentType": { "sys": { "id": "ct_result" } },
                 "fields": { "text": { "en-US": "{ /resp/body/text }" } } } ],
  "catch":   [ { "type": "ResourceCreate", "resource": "Content", "contentType": { "sys": { "id": "ct_result" } },
                 "fields": { "text": { "en-US": "Pembuatan gagal" }, "error": { "en-US": "{ /error/message }" } } } ],
  "finally": [ /* selalu dijalankan */ ] }

Dokumen terkait

• Ekspresi nilai: aturan nilai yang diikuti oleh semua field di atas.
• Semantik eksekusi, batasan, dan keamanan: urutan eksekusi, error, batasan statis, dan keamanan.
• Cookbook: contoh lengkap yang mengombinasikan statement-statement ini.
• Ringkasan Script: struktur tingkat atas dan mode eksekusi.