Katalog Statement

Setiap elemen array statements adalah satu Statement. Dokumen ini merangkum field, perilaku, dan hasil dari 25 jenis Statement. Setiap posisi nilai mengikuti aturan Ekspresi nilai (referensi, literal, JsonLogic, locale map); pengecualiannya ada tiga, yaitu pattern pada Regex, key pada Cache, dan color pada PdfWatermark, lihat Regex, Cache, dan Transformasi file.

Ringkasan Statement

Statement yang menangani Content tanpa menunjuk targetnya dengan id wajib menuliskan Content Type. Pada ResourceFind, ResourceForEach, ResourceCount, contentType bersifat wajib bila resource bernilai "Content". Tidak ada kueri Content yang melintasi seluruh Space. ResourceCreate pun menuliskan Content Type yang akan dibuat. Media tidak memikul cakupan karena seluruh Space adalah satu set, sedangkan Statement yang menunjuk targetnya dengan id (ResourceRead, ResourceUpdate, ResourcePatch, ResourceDelete serta Statement publikasi dan pengarsipan) memiliki target sehingga tidak memerlukan cakupan.

Panggilan siklik dibatasi maksimal 3 kali. Jika Anda mengaktifkan propagateEvents (nilai bawaannya mati) pada Statement penulisan resource di atas (ResourceCreate, ResourceUpdate, ResourcePublish, dan sejenisnya), penulisan itu 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 merupakan key yang langsung diletakkan pada root konteks, sehingga divalidasi saat disimpan. Nama hanya boleh memakai huruf Latin, angka, _, dan - (harus dapat dipakai sebagai key JSON Pointer, sehingga karakter lain maupun nama kosong akan ditolak), tidak boleh sama dengan root yang dicadangkan (payload, rawPayload, headers, vars, error, now, secrets), dan harus unik dalam satu Script. Jika formatnya dilanggar, kata cadangan dipakai, atau ada duplikat, penyimpanan ditolak.

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" | "ContentType" | "Media" | "ServiceUser".

Content Type hanya diterima oleh ResourceCount. Jika Anda menuliskannya pada Statement lain, penyimpanan ditolak. Membuat atau mengubah formulirnya sendiri adalah urusan CMA, bukan Script.

Statement yang menerima ServiceUser (anggota yang mendaftar ke produk) adalah tiga Statement pembacaan (ResourceRead, ResourceFind, ResourceForEach) serta ResourceUpdate dan ResourcePatch. Field yang dapat ditulis oleh kedua Statement itu hanya dua, yaitu roleOverride dan enableLogin. Jika Anda menuliskannya pada Statement penulisan selain itu, penyimpanan ditolak (lihat Error). Aturannya dibahas di Menangani direktori anggota.

Penulisan resource

Setiap Statement penulisan memiliki propagateEvents (default false) (ResourceUpdate dan ResourcePatch yang menulis ServiceUser tidak menerima field ini). Jika disetel true, penulisan tersebut memicu peristiwa perubahan sehingga tindakan lanjutan seperti Webhook dijalankan. Default-nya tidak memicu apa pun (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", "transformations": [ … ] }. source dan encoding wajib, sedangkan transformations hanya ditulis jika file yang diterima akan diubah sebelum disimpan (Transformasi file). Pada penulisan yang menyertakan file, engine melakukan penyerapan itu (jika url, ia mengunduh; jika base64, ia mendekode lalu mengunggah dan memprosesnya). Penyerapan ini tidak mendeklarasikan waktu sehingga diambil dari anggaran dasar 30 detik (Anggaran waktu), dan tidak dihitung ke batas panggilan eksternal. 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
{ "type": "ResourceCreate", "resource": "Media",
  "fields": {
    "title": { "en-US": "{ /payload/fields/prompt }" },
    "file":  { "en-US": { "source": "{ /gen/body/data/0/url }", "encoding": "url" } }
  }, "name": "img" }

Transformasi file (transformations)

Saat menjual e-book, ada kalanya Anda ingin menyerahkan salinan yang setiap halaman PDF-nya dibubuhi email pembeli. Jika Anda menulis transformations pada instruksi ingest, file yang diterima dapat diubah sebelum disimpan. Transformasi yang didukung hanya satu, yaitu PdfWatermark.

• Diterapkan sesuai urutan array. Hasil transformasi sebelumnya menjadi input transformasi berikutnya, dan hasil terakhir menjadi file Media.
• Dapat ditulis pada instruksi ingest mana pun di ResourceCreate, ResourceUpdate, ResourcePatch.
• File asli yang ditunjuk source tidak berubah. Untuk membubuhkan teks pada file yang sudah ada di Space, baca Media itu dengan ResourceRead, lalu masukkan { /<name>/fields/file/<locale>/url } ke source untuk membuat Media baru.
• Transformasi juga merupakan bagian dari ingest. Waktu yang dibutuhkan diambil dari anggaran dasar 30 detik (Anggaran waktu).

PdfWatermark: membubuhkan teks pada setiap halaman PDF

• Field yang tidak ada di tabel diabaikan. Ukuran huruf, posisi, dan transparansi tidak dapat ditentukan.
• Dibubuhkan pada setiap halaman. Satu baris teks diletakkan di sepanjang diagonal yang melewati tengah halaman (dari kiri bawah ke kanan atas).
• Dibubuhkan di atas isi halaman dengan opasitas 30%. Isi asli di bawah teks tetap terbaca.
• Ukuran huruf ditentukan otomatis untuk setiap halaman. Teks dibubuhkan dengan ukuran yang menempati 80% panjang diagonal, tetapi tidak melebihi 15% sisi pendek halaman. Teks pendek dibubuhkan besar, teks panjang dibubuhkan kecil, dan teks tidak keluar dari halaman.
• Fontnya adalah Helvetica, font standar PDF.
• Apakah file berupa PDF ditentukan dari isinya, bukan dari nama file atau ekstensinya.

// bagian dari array statements. Media baru dari PDF e-book yang dibeli, dibubuhi email pembeli dan nomor pesanan
{ "type": "ResourceRead", "resource": "Media",
  "target": { "sys": { "id": "{ /payload/fields/ebookMediaId }" } }, "name": "ebook" },
{ "type": "ResourceCreate", "resource": "Media", "locale": "en-US", "publish": false,
  "fields": {
    "title": "{ /ebook/fields/title/en-US }",
    "file": {
      "source": "{ /ebook/fields/file/en-US/url }", "encoding": "url",
      "transformations": [
        { "type": "PdfWatermark", "text": "{ /payload/fields/email } · { /payload/fields/orderId }", "color": "#B22222" }
      ]
    }
  }, "name": "stamped" }

Salinan ini ditujukan untuk satu pembeli, sehingga publish diatur ke false agar tidak dikirimkan melalui CDA/ACDA. Jika dihilangkan, salinan dipublikasikan sesuai nilai default true.

Batasan teks PdfWatermark

text hanya dapat memuat karakter yang dapat digambar oleh font standar PDF (set karakter WinAnsi).

Karakter selain itu tidak dapat dipakai. Yang termasuk di sini adalah karakter Latin Extended yang tidak ada di tabel (seperti ł, ő, ș), karakter non-Latin, emoji, serta baris baru dan tab.

Saat Script disimpan, text diperiksa sebagaimana ditulis. Nilai hasil resolve dari text yang memuat { /pointer } baru diketahui saat eksekusi, sehingga nilai hasil resolve itu diperiksa lagi saat eksekusi. Kode error yang terjadi saat penyimpanan ada di Error.

• Hitung panjang teks tetap saat menulis. Pada "Purchased by { /payload/fields/email } · Order { /payload/fields/orderId }", teks tetap di luar template berjumlah 22 karakter, sehingga panjang yang tersisa untuk email dan nomor pesanan adalah 42 karakter secara gabungan. Jika nilai sebenarnya yang masuk lebih panjang dari itu, Script tetap tersimpan tetapi eksekusi tersebut gagal.
• Bubuhkan pengenal, bukan nama. Nama pembeli yang memuat karakter yang tidak ada di tabel akan gagal saat eksekusi. Email atau nomor pesanan yang berupa ASCII dapat dibubuhkan.

Kasus ketika transformasi file gagal

Dalam kasus berikut, Statement tersebut gagal. Seperti kegagalan runtime lainnya, kegagalan ini dapat ditangani dengan Try/catch. Transformasi terjadi sebelum Media ditulis, sehingga jika gagal, Media baru tidak dibuat dan target ResourceUpdate, ResourcePatch juga tidak berubah.

ResourceUpdate

Mengganti sepenuhnya field dari Content, Media, atau ServiceUser 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.

{ "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, Media, atau ServiceUser 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. 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, penghapusan ditolak selama file Media tersebut sedang diproses. 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. ResourcePublish tidak dapat dilakukan dari Archived dan menuntut pemrosesan file sudah selesai. ResourceUnpublish hanya dapat dilakukan dari Published dan Changed, ResourceArchive hanya dari Draft, dan ResourceUnarchive 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

ResourceRead dan ResourceFind membaca resource lalu mengikatnya sebagai nilai, sedangkan ResourceCount hanya menghitung jumlahnya. Ketiganya tidak mengubah status (tidak ada propagateEvents). Pembacaan pada ResourceForEach sendiri juga bersifat baca, tetapi jika onEach memuat Statement penulisan resource, penulisan itu dijalankan untuk tiap item sehingga statusnya berubah.

Keempat Statement (ResourceRead, ResourceFind, ResourceForEach, ResourceCount) menentukan salinan tersimpan mana yang dibaca melalui from (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). (ServiceUser tidak dipublikasikan sehingga hanya menerima Current. Lihat Menangani direktori anggota.)

Selain itu, ResourceFind, ResourceForEach, ResourceCount mengaktifkan dan menonaktifkan Pencarian Lanjutan (Advanced Search) melalui advanced (default true). Jika tidak dituliskan, ia aktif. Ini khusus Content, sehingga diabaikan untuk pembacaan Media dan ServiceUser. 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 pengurutan fields.* dapat dipakai. 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. Karena bawaannya aktif, jeda ini berlaku untuk semua kueri kecuali Anda menyetel advanced menjadi false. Untuk membaca item yang baru ditulis dengan segera, gunakan ResourceRead berdasarkan id (salinan tersimpan default, tanpa jeda) atau lakukan kueri berdasarkan sys.id yang dikembalikan oleh penulisan.

createdBy: ":self" pada where berarti "hanya yang dibuat oleh pemanggil saat ini". Namun ini tidak dapat dipakai pada Script yang mengizinkan panggilan anonim (anonymousCallEnabled). Pada kasus itu :self di-resolve menjadi penulis, bukan pemanggil, sehingga resource milik penulis terbuka secara senyap; karena itu definisi semacam itu ditolak saat disimpan (lihat Panggilan anonim).

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 melakukan kueri pada 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.

Menangani direktori anggota (ServiceUser)

ResourceRead, ResourceFind, ResourceForEach menerima "ServiceUser" pada resource untuk membaca direktori anggota Space tersebut (ResourceCount tidak menerimanya, lihat ResourceCount di bawah). Gunakan untuk memastikan siapa pemilik sebuah pesanan, atau untuk alur yang mencari anggota berdasarkan email lalu meneruskan sys.id-nya ke Statement berikutnya. Aturan berikut berlaku untuk kelima Statement yang menangani direktori anggota.

• Field yang dapat diubah hanya dua. ResourceUpdate dan ResourcePatch menerima "ServiceUser" lalu mengubah roleOverride dan enableLogin. Jika pada ResourcePatch Anda memberi null untuk roleOverride, peran yang sudah ditetapkan akan dilepas. ResourceCreate, ResourceDelete serta Statement publikasi dan pengarsipan tidak menerima "ServiceUser", dan definisi semacam itu ditolak saat disimpan. Ini bukan sesuatu yang bisa dibuka dengan menambah izin, melainkan karena Script tidak dapat membuat atau menghapus anggota, sehingga penolakannya bukan error izin melainkan Statement yang salah tulis.
• Anggota tidak memiliki version maupun propagateEvents. Jika Anda menuliskan salah satunya, eksekusinya gagal. Karena ResourceUpdate mengganti seluruh field yang dapat ditulis, enableLogin bersifat wajib, dan jika roleOverride tidak dituliskan, peran yang sudah ditetapkan akan dilepas. Untuk mengubah salah satunya saja, gunakan ResourcePatch, dan pada kasus itu setidaknya satu dari kedua field tersebut harus dituliskan.
• Penyimpanan hanya berhasil jika penulis memiliki izin direktori anggota. Pemeriksaannya tidak lewat map izin seperti Content dan Media, melainkan melihat apakah settings pada SpaceRole penulis memuat SETTING_SERVICE_LOGIN (atau SETTING_ALL). Alasannya, direktori anggota adalah resource yang dikelola pengaturan Space di semua jalur lainnya juga. Jika tidak ada, penyimpanan ditolak (lihat Model keamanan).
• from hanya menerima Current. Anggota bukan resource yang dipublikasikan, sehingga memberi Published membuat eksekusi gagal.
• contentType dan advanced diabaikan. Direktori anggota tidak terbagi per Content Type (satu set untuk seluruh Space), dan Pencarian Lanjutan pun khusus Content.
• sys.email pada where hanya menerima operator keluarga kecocokan persis (eq, ne, in, nin). Alamat anggota disimpan terenkripsi, sehingga perbandingan urutan atau prefix tidak bermakna. Jika Anda memberi operator lain, alih-alih mengembalikan 0 hasil secara senyap, eksekusinya gagal.
• Hasilnya adalah resource ServiceUser itu sendiri. Rujuk seperti { /<name>/sys/id } dan { /<name>/nickname }. Strukturnya dibahas di referensi ServiceUser. Ketika mengirim email kepada anggota yang ditemukan, jangan mengeluarkan alamatnya, melainkan berikan sys.id-nya pada toServiceUser milik EmailSend (engine me-resolve alamat tepat sebelum pengiriman sehingga alamat anggota tidak masuk ke ruang variabel Script).

// Mencari satu anggota berdasarkan email. null jika tidak ada
{ "type": "ResourceFind", "resource": "ServiceUser",
  "where": { "sys.email": { "eq": "{ /payload/fields/email }" } }, "name": "member" }

ResourceRead

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

• Hasil: yang diikat adalah resource itu sendiri. Jika Statement ini diberi name, rujuk langsung dengan { /<name>/sys/id } dan { /<name>/fields/<field>/<locale> } (dengan "name": "order" pada contoh di bawah, berarti { /order/sys/id }). Ini bukan list, jadi tidak melewati indeks array.
• 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 name Statement ini. 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" }

ResourceForEach

Menelusuri resource yang cocok dengan filter secara internal dan menjalankan onEach untuk tiap item. Ini adalah Statement untuk melakukan pekerjaan pada tiap item, bukan untuk membentuk koleksi yang akan dipakai sebagai nilai. Gunakan untuk pekerjaan berulang seperti mempublikasikan draft secara massal, mengubah Content yang memenuhi kondisi secara massal, atau mengirim/menyinkronkan tiap item ke luar. Untuk membaca satu item saja, gunakan ResourceRead (id) atau ResourceFind (filter).

• Tidak mengikat koleksi (foreach, bukan map). Tidak ada { items, next } maupun cursor. Alih-alih mengembalikan hasil penelusuran sebagai nilai, ia menjalankan onEach untuk tiap item. Jika Anda memerlukan daftarnya, kumpulkan sendiri dengan SetVar. Jika yang Anda perlukan hanya jumlahnya, gunakan ResourceCount.
• Tanpa limit pun bukan berarti penelusuran tak terhingga. Jika tidak ada, ia menelusuri hingga batas atas platform (10.000 item), dan gagal jika mencapai batas itu sementara masih ada kecocokan tersisa (agar tidak melaporkan keberhasilan padahal ada item yang belum tersentuh). Sebaliknya, mencapai limit yang Anda deklarasikan adalah penghentian yang disengaja sehingga berakhir normal. limit yang melebihi batas atas ditolak saat disimpan.
• Tidak ada cursor. Jika menyelesaikan seluruhnya, berarti berhasil; jika terputus di tengah (batas wall-clock atau kuota terlampaui, kegagalan onEach yang tidak tertangani), berarti gagal, dan error menunjuk pada item mana serta mengapa gagal. Pelanjutan diekspresikan penulis dengan datanya sendiri (jadikan where bermakna "belum diproses" dan tandai penyelesaian di akhir onEach, sehingga eksekusi ulang melanjutkan dari sisa yang ada).
• Pada anggaran waktu ia dihitung sebagai perkalian. Waktu yang dideklarasikan Statement ini adalah waktu yang dideklarasikan onEach dikalikan jumlah item yang diproses (limit, atau 10.000 jika tidak ada) (Anggaran waktu). Karena ini Statement komposit yang memiliki anak, Statement itu sendiri tidak dihitung ke anggaran leaf panggilan eksternal; Statement panggilan eksternal di dalam onEach-lah yang dihitung ke anggaran.
• onEach dapat memuat panggilan eksternal (Http, EmailSend) atau penyerapan file Media seperti Statement lainnya (sama seperti body pada Loop). Memproses hasil kueri resource satu kali per item adalah alasan keberadaan Statement ini.

// Temukan semua postingan berstatus draft lalu publikasikan tiap item
{ "type": "ResourceForEach", "resource": "Content", "contentType": { "sys": { "id": "ct_post" } },
  "where": { "fields.status": { "eq": "draft" } }, "order": "sys.createdAt,sys.id",
  "from": "Current", "advanced": false, "name": "post",
  "onEach": [
    { "type": "ResourcePublish", "resource": "Content", "target": { "sys": { "id": "{ /post/sys/id }" } } }
  ] }

ResourceCount

Hanya menghitung jumlah yang cocok dengan filter. Karena ia tidak membaca itemnya, gunakan Statement ini saat yang Anda perlukan adalah jumlahnya, bukan daftarnya. Ini tempatnya untuk memeriksa sisa stok, menentukan apakah nilai yang sama sudah ada, atau memeriksa apakah suatu batas sudah terlampaui.

• Hasil: mengikat jumlah yang cocok ke name. Rujuk dengan { /<name> } lalu gunakan untuk perbandingan dan percabangan.
• Ia tidak mengembalikan itemnya. Jika Anda memerlukan itemnya, gunakan ResourceFind (satu item pertama yang cocok) atau ResourceForEach (dijalankan untuk tiap item).
• Jangan menghitung dengan menelusuri ResourceForEach hanya demi memperoleh jumlahnya. Penelusuran mengambil anggaran waktu sebanyak perkalian dengan jumlah item (Anggaran waktu), dan gagal jika mencapai batas atas platform sementara masih ada kecocokan tersisa. Jika yang Anda butuhkan hanya hitungannya, Statement ini menyelesaikannya sekali jalan.
• Tidak ada order dan limit. Menghitung tidak memerlukan urutan, dan semua yang cocok memang dihitung.

// Menghitung berapa banyak komentar yang tertaut pada postingan ini
{ "type": "ResourceCount", "resource": "Content", "contentType": { "sys": { "id": "ct_comment" } },
  "where": { "fields.postId": { "eq": "{ /payload/sys/id }" } }, "name": "commentCount" }

Eksternal

Http

Memanggil HTTP eksternal. Karena ini panggilan eksternal, ia dihitung ke batas panggilan eksternal per paket. Pada Anggaran waktu, timeoutMs ditambahkan, dan jika Anda mengirim file, waktu unduh untuk setiap file juga ditambahkan. Jika retry ditentukan, jumlah itu dikalikan dengan jumlah percobaan (1 + retry).

• Gunakan hanya salah satu dari body, urlBody, dan multipartBody. Jika dua atau lebih dituliskan, penyimpanan ditolak. Jika ketiganya tidak ada, permintaan dikirim tanpa body.
• Hasil: { status, body }. Jika Statement ini diberi name, { /<name>/status }, { /<name>/body/... }. Bentuk body ditentukan oleh responseType.
• responseType hanya berlaku untuk respons yang berhasil. Isi respons dengan status 400 atau lebih diikat untuk keperluan diagnosis, apa pun nilai yang dideklarasikan (nilai hasil parsing jika JSON, string jika bukan).
• Jika "Json" tetapi isinya bukan JSON, panggilan ini gagal (menjadi target Try/catch). Untuk API yang tidak mengembalikan JSON, terima responsnya sebagai "Text", lalu parsing dengan ParseJson bila perlu diperlakukan sebagai nilai.
• "Text" didekode dengan charset dari Content-Type respons, dan dianggap UTF-8 bila tidak ada charset. Bila isinya kosong, body bernilai null pada kedua kasus.
• 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 { /secrets/LLM_API_KEY }" } ],
  "body": { "prompt": "{ /payload/fields/prompt }" }, "timeoutMs": 15000, "retry": 1,
  "responseType": "Json", "name": "resp" }

Dalam format apa body dikirim

Content-Type yang diletakkan pada headers menentukan format serialisasi body. Perbandingannya mengabaikan besar-kecil huruf dan parameter seperti ;charset=…, lalu hanya melihat bagian depannya. Jika headernya tidak ada atau nilainya kosong, permintaan dikirim sebagai application/json. Header ini hanya dilekatkan ketika ada body, jadi bila tidak ada body, header yang dituliskan dikirim apa adanya. Jika key yang sama diletakkan beberapa kali, hanya nilai pertama yang dipakai dan semuanya digabung menjadi satu.

body yang tidak dapat dimuat dalam format yang dideklarasikan akan dikoreksi ke format yang dapat memuatnya sebelum dikirim. Header tidak pernah menyatakan hal yang berbeda dari body yang sebenarnya.

Berikut kombinasi yang dikirim sesuai nilai yang dideklarasikan.

Berikut kombinasi yang dikoreksi karena tidak dapat dimuat dalam format yang dideklarasikan.

Dua baris ini menjelaskan bagaimana permintaan dikirim ketika pasangannya tidak cocok, dan bukan cara untuk memperoleh format yang Anda maksudkan. Jika body disusun dengan ekspresi nilai, ia dapat menjadi skalar tergantung pada payload saat eksekusi, dan koreksi ini terjadi tanpa kesalahan. Jika pihak penerima mempermasalahkan formatnya, perbaiki salah satu di antara bentuk body dan Content-Type sesuai maksud Anda.

form-urlencoded membentangkan objek menjadi key berkurung siku dan array menjadi indeks.

Key dan nilai dikirim dengan persen-encoding UTF-8. Tabel di atas adalah bentuk hasil dekode untuk memperlihatkan struktur key-nya. Meskipun nilainya mengandung & atau +, keduanya tidak disalahartikan sebagai pemisah pasangan atau spasi dan diteruskan apa adanya.

Notasi yang membentangkan struktur bersarang menjadi key berkurung siku adalah konvensi yang dipakai luas, bukan spesifikasi dari format itu sendiri. Periksa apakah pihak penerima memulihkan order[id] menjadi objek bersarang, dan jika tidak dipulihkan, susun body dengan key yang datar.

{ "type": "Http", "method": "POST", "url": "https://api.example.com/oauth/token",
  "headers": [ { "key": "Content-Type", "value": "application/x-www-form-urlencoded" } ],
  "body": { "grant_type": "client_credentials", "client_id": "{ /vars/clientId }" },
  "name": "token" }

Mengirim file sebagai body

Ada kalanya file yang telah diunggah ke Media perlu diteruskan ke API eksternal. Byte file tidak dapat dimuat dalam ekspresi nilai. Sebagai gantinya, jika Anda menentukan URL tempat file berada, platform mengambil file dari URL itu lalu mengirimkannya sebagai body permintaan. Untuk mengirim satu file sebagai seluruh body, gunakan urlBody; untuk mengirim file bersama field teks sebagai formulir, gunakan multipartBody.

urlBody: mengirim satu file sebagai seluruh body

File yang diambil dari URL yang ditentukan dikirim apa adanya sebagai body permintaan tanpa diubah. Cara ini cocok untuk API yang menerima unggahan file dengan PUT ke URL unggahan. Berikut contoh membaca PDF kontrak (Media) lalu mengirimkannya ke URL unggahan layanan tanda tangan elektronik.

// bagian dari array statements
{ "type": "ResourceRead", "resource": "Media",
  "target": { "sys": { "id": "{ /payload/fields/contractMediaId }" } }, "name": "contract" },
{ "type": "Http", "method": "PUT",
  "url": "https://api.esign.example/v1/envelopes/{ /payload/fields/envelopeId }/document",
  "headers": [ { "key": "Authorization", "value": "Bearer { /secrets/ESIGN_API_KEY }" },
               { "key": "Content-Type", "value": "application/pdf" } ],
  "urlBody": "{ /contract/fields/file/en-US/url }", "name": "upload" }

Content-Type permintaan ditentukan dengan urutan berikut.

1. Jika Content-Type ditentukan pada headers, nilai itu dipakai apa adanya. Koreksi pada serialisasi body tidak diterapkan.
2. Jika tidak ditentukan atau nilainya kosong, Content-Type yang dikembalikan URL file dipakai.
3. Jika itu pun tidak ada, application/octet-stream dipakai.

multipartBody: mengirim file dan teks sebagai formulir

Permintaan dikirim sebagai multipart/form-data. Satu elemen array menjadi satu part, dan part dikirim sesuai urutan array. Array harus berisi 1 elemen atau lebih, dan array kosong membuat penyimpanan ditolak. Content-Type selalu multipart/form-data (string pembatas dibuat otomatis), dan Content-Type yang ditulis pada headers diabaikan.

• Tuliskan tepat salah satu dari value dan url. Jika keduanya ditulis atau keduanya tidak ada, penyimpanan ditolak. Menulis fileName pada part value juga membuat penyimpanan ditolak.
• Jika fileName dihilangkan, potongan path terakhir dari url didekode lalu dipakai (query string tidak termasuk). Jika potongan itu kosong atau memuat karakter kontrol, nama yang dikirim adalah file.
• Jika contentType dihilangkan, part value dikirim tanpa Content-Type, dan part url memakai Content-Type yang dikembalikan URL file (jika tidak ada, application/octet-stream). Jika Anda menentukan nilai yang bukan format media type, Http itu gagal dengan status 400 saat dijalankan.
• Jika hasil ekspresi nilai fileName dan contentType memuat karakter baris baru, Http itu gagal dengan status 400 sebelum permintaan dikirim.

Berikut contoh mengirim foto produk (Media) bersama opsi analisis ke layanan analisis gambar. Part image tidak menuliskan fileName, sehingga potongan terakhir URL file Media (mis. tumbler.png) dikirim sebagai nama file.

// bagian dari array statements
{ "type": "ResourceRead", "resource": "Media",
  "target": { "sys": { "id": "{ /payload/fields/photoMediaId }" } }, "name": "photo" },
{ "type": "Http", "method": "POST", "url": "https://api.vision.example/v2/analyze",
  "headers": [ { "key": "x-api-key", "value": "{ /secrets/VISION_API_KEY }" } ],
  "multipartBody": [
    { "name": "image", "url": "{ /photo/fields/file/en-US/url }" },
    { "name": "language", "value": "ko" },
    { "name": "features", "value": "labels" },
    { "name": "features", "value": "text" }
  ], "timeoutMs": 20000, "name": "analysis" }

Kegagalan yang terjadi pada Http yang mengirim file juga terbagi menjadi dua jenis. Batas waktu yang terlampaui diperlakukan sebagai respons status 504, sehingga retry dan ignoreStatusCode berlaku. Pada kegagalan terkait file dalam tabel di bawah, keduanya tidak berlaku. Klasifikasi seluruh kegagalan Http dirangkum di Dua cara Http gagal.

Jika ignoreStatusCode: true, { "status": 504, "body": "timed out after …ms" } diikat sebagai hasil ketika batas waktu terlampaui.

Satu permintaan harus selesai dalam timeoutMs, dan waktu menunggu respons URL file juga termasuk di dalamnya. Saat mengirim file, batas waktu diperpanjang sebanyak waktu yang dibutuhkan untuk mengirim file itu pada kecepatan 10.000.000 byte per detik. Waktu tambahan itu tidak melebihi waktu unduh paket dikalikan jumlah file. Namun jika URL file tidak memberi tahu ukuran file, perpanjangannya hanya sebanyak data yang benar-benar terkirim, sehingga jika transfer lambat atau berhenti di tengah, batas waktu dapat terlampaui lebih awal.

Dalam kasus berikut, Http itu langsung gagal. Kegagalan ini tidak dicoba ulang dengan retry, dan tetap diperlakukan sebagai kegagalan meskipun ignoreStatusCode: true ditentukan. Seperti kegagalan runtime lainnya, kegagalan ini dapat ditangani dengan Try/catch.

• Batas unduhan berlaku per URL file. Jika multipartBody memuat beberapa part file, batasnya berlaku terpisah untuk setiap file.
• Byte yang dikirim, termasuk file, dijumlahkan ke "Panggilan eksternal" pada transfer data di Paket Harga.

EmailSend

Mengirim 1 email melalui EmailAccount terdaftar. Field yang diterima hanya yang dipetakan langsung ke SMTP/MIME. Tidak ada id template, penjadwalan pengiriman, atau ekstensi khusus penyedia (jika membutuhkan fitur semacam itu, panggil langsung API layanan email tersebut dengan Http). Pengirim (alamat pengirim) tidak ditentukan di sini melainkan berasal dari EmailAccount yang ditunjuk account.

• Body ditulis dengan salah satu dari body atau templateBody. Jika keduanya ditulis bersamaan atau keduanya dikosongkan, penyimpanan ditolak.
• Nilai yang dikirim pemanggil secara bawaan dirender sebagai huruf. Jika autoEscape aktif, markup seperti <a> di dalam nilai terlihat sebagai huruf, bukan sebagai tag. Ini mekanisme agar nilai yang dikirimkan orang lain tidak dapat menanam tautan atau tag ke dalam email orang lain. Setel false hanya ketika markup memang harus dipertahankan, seperti pada body newsletter yang ditulis sendiri oleh pengelola.
• Field header tidak boleh memuat nilai yang mengandung baris baru. Ini berlaku untuk subject, replyTo dan semua alamat. Jika baris baru masuk, eksekusi gagal. Pada body, baris baru adalah isi yang wajar sehingga tidak diperiksa.
• Total penerima maksimum 50 orang. Dihitung dengan menjumlahkan to (1 orang), cc, dan bcc (envelope SMTP tidak membedakan cc/bcc dan semuanya keluar sebagai penerima, jadi dihitung sebagai total). Jika melebihi, ditolak saat disimpan dan dijalankan. Untuk mengirim ke banyak orang, kirim 1 email per item dengan ResourceForEach + EmailSend.
• Tidak mengikat hasil. Keberhasilan hanya berarti "penyedia menerima email", sehingga tidak ada nilai yang dikembalikan dan name tidak diterima. Juga tidak melakukan percobaan ulang (email tidak idempoten, sehingga percobaan ulang setelah kegagalan yang ambigu akan menyebabkan pengiriman ganda. Karena itu ia tidak mengikuti retry milik Http). Kegagalan di-throw dan ditangani oleh catch pada Try.
• Ini panggilan eksternal. Ia dihitung ke batas panggilan eksternal per paket, dan pada Anggaran waktu ia dihitung sebagai timeoutMs (atau 10 detik jika tidak ada) satu kali (karena tidak melakukan percobaan ulang, hitungannya tidak dikalikan seperti pada Http). Dapat dipakai di dalam onEach milik ResourceForEach (bentuk standar untuk pengiriman banyak email).

{ "type": "EmailSend", "account": { "sys": { "id": "eml_orders" } },
  "to": "{ /order/fields/email/en-US }",
  "subject": "Pesanan berhasil diterima (nomor pesanan { /order/sys/id })",
  "body": "<p>Pesanan Anda telah diterima. Kami akan memberi tahu lagi ketika pengiriman dimulai.</p>",
  "replyTo": "support@my-shop.example" }

Membuat body dari template (templateBody)

Jika body email ditulis langsung di dalam definisi Script, setiap kali kalimatnya diperbaiki Script harus ikut diubah. templateBody menempatkan template body di dalam Content dan hanya mengisi bagian kosongnya, sehingga kalimat diperbaiki di Content Studio dan Script tetap apa adanya.

Bagian kosong di dalam template ditulis { /<kunci> }. Yang dibaca bagian kosong ini hanya data; template tidak dapat membaca /payload atau /secrets secara langsung. Bagian kosong yang menunjuk kunci yang tidak ada di data dirender sebagai huruf kosong. Kunci yang nilainya null pun sama. Ini kebalikan dari pointer pada body yang menunjuk null lalu tercetak sebagai huruf null, jadi perhatikan hal ini saat berpindah antara kedua cara tersebut.

Jika di dalam template ada tempat yang {-nya diikuti / (sekalipun ada spasi di antaranya, misalnya a{/*komentar*/} pada CSS), ia terbaca sebagai bagian kosong sehingga ditulis \{.

Ada tiga tempat yang lolos saat disimpan tetapi terputus saat dijalankan. Jika source ter-resolve menjadi objek (ketika lokal pada Field multibahasa terlewat), ia gagal. Jika source bernilai kosong, ia gagal (karena ResourceFind tidak menemukannya, atau karena Statement yang membaca template berada setelah EmailSend). Jika hasil pengisian seluruh bagian kosong hanya berupa spasi, ia juga gagal.

Template yang ditunjuk source sendiri tidak di-escape. Yang menjadi sasaran escape adalah nilai data. Karena itu, untuk memasukkan HTML kiriman pemanggil ke dalam email apa adanya, letakkan nilai tersebut di data dan setel autoEscape menjadi false.

{ "type": "ResourceRead", "resource": "Content", "name": "tpl",
  "target": { "sys": { "id": "cnt_mail_shipping" } } },
{ "type": "EmailSend", "account": { "sys": { "id": "eml_orders" } },
  "toServiceUser": { "sys": { "id": "{ /order/fields/buyer/en-US/sys/id }" } },
  "subject": "Pengiriman telah dimulai",
  "templateBody": {
    "source": "{ /tpl/fields/html/en-US }",
    "data": { "name": "{ /order/fields/buyerName/en-US }",
              "tracking": "{ /order/fields/trackingNo/en-US }" } } }

Templatenya (Field html pada cnt_mail_shipping) berbentuk seperti ini.

<p>Halo { /name }, pengiriman produk yang Anda pesan telah dimulai.</p>
<p>Nomor resi: { /tracking }</p>

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

Cache

Cache

Membaca dan menulis cache berumur pendek yang hanya dimiliki Script itu sendiri. Ini tempat untuk menahan selama beberapa detik nilai yang sayang diambil ulang setiap kali, seperti hasil panggilan eksternal, lalu memakainya kembali pada pemanggilan berikutnya. Karena ini bukan panggilan eksternal, ia tidak ikut dihitung dalam jumlah panggilan eksternal per definisi, dan tidak mendeklarasikan waktu apa pun pada anggaran waktu.

• Tulis hanya field yang sesuai dengan operasinya. Menulis ttl pada Get atau defaultValue pada Set membuat penyimpanan ditolak.
• Data yang tidak ada dan data yang sudah kedaluwarsa tidak dibedakan. Keduanya mengikat defaultValue. Begitu pula ketika yang tersimpan adalah null.
• Cakupan penyimpanannya hanya satu Script itu. Script lain di Space yang sama tidak dapat melihat data milik satu sama lain meskipun memakai kunci cache yang sama. Jika Script itu diubah atau dihapus, seluruh data milik Script itu ikut hilang.
• key bersifat literal. Jika data boleh dipilih dengan kunci cache yang datang dari permintaan, pemanggil yang menentukan apa yang dibaca, dan Script yang menyimpan satu nilai untuk tiap anggota akan menyerahkan nilai milik seorang anggota kepada anggota lain. Karena itu, jika key memuat { /pointer }, ia tidak diubah menjadi nilai dan tidak juga dipakai secara harfiah. Penyimpanannya sendirilah yang ditolak.
• Tidak boleh diletakkan di dalam perulangan. Jika ada Cache di dalam blok Loop atau ResourceForEach, penyimpanan ditolak. Sebab batas jumlah di bawah ini tidak lagi menjadi batasan apa pun ketika berada di dalam perulangan. Karena satu data ditulis pada tiap iterasi, jumlah Statement yang tertulis di definisi tidak lagi sesuai dengan jumlah kunci cache yang benar-benar dipakai.
• Satu definisi dapat memuat paling banyak 5 (termasuk yang bersarang, dijumlahkan tanpa memandang operasinya). Jika melebihi, penyimpanan ditolak.
• Nilai yang disimpan maksimal 10.240 byte (10KiB). Jika melebihi, Statement itu gagal (status 422). Sama seperti kegagalan runtime lainnya sehingga dapat ditangani secara lokal dengan Try/catch.

// Memakai ulang kurs selama 30 detik.
{ "type": "Cache", "action": "Get", "name": "cached", "key": "rates" }
 
// Jika ada nilai yang sedang disimpan, kembalikan apa adanya tanpa panggilan eksternal
{ "type": "If", "condition": { "!!": [ "{ /cached }" ] },
  "then": [ { "type": "Return", "value": "{ /cached }" } ] }
 
{ "type": "Http", "name": "fetched", "method": "GET", "url": "https://api.example.com/rates" }
{ "type": "Cache", "action": "Set", "key": "rates", "value": "{ /fetched/body }", "ttl": 30 }
{ "type": "Return", "value": "{ /fetched/body }" }
 
// Membuang nilai yang sedang disimpan sebelum kedaluwarsa
{ "type": "Cache", "action": "Delete", "key": "rates" }

Parsing nilai

ParseJson

Mem-parsing teks JSON menjadi nilai yang diwakilinya lalu mengikatnya ke sebuah nama. Dipakai untuk isi yang diterima dari Http dengan responseType: "Text", string JSON yang masuk lewat payload, atau JSON yang disimpan sebagai string di sebuah field. Karena ini bukan panggilan eksternal, ia tidak dihitung ke batas panggilan eksternal, dan tidak mendeklarasikan waktu apa pun pada anggaran waktu.

• Hasil: nilai hasil parsing itu sendiri. Objek tetap objek, array tetap array, dan nilai tunggal seperti 42 atau "a" juga di-parsing. Setelah itu tunjuk bagian dalamnya dengan { /<name>/... }.
• Nilai yang sudah di-parsing diikat apa adanya. Ketika value menghasilkan sesuatu yang bukan string, tidak ada teks untuk di-parsing, sehingga nilai itu diikat sebagaimana adanya.
• { /pointer } di dalam teks yang di-parsing tidak diuraikan lagi. Meski string yang diterima dari luar memuat ekspresi seperti { /payload/... }, itu tidak digantikan nilai dan tetap menjadi teks.
• null mencakup dua kasus berbeda. Jika teks yang di-parsing hanya satu kata null, itu normal dan hasilnya juga null. Sebaliknya, jika tempat yang ditunjuk value kosong sehingga tidak ada nilai sama sekali, tidak ada yang bisa di-parsing dan Statement gagal.
• Gagal: ketika value menghasilkan tanpa nilai atau hanya spasi, dan ketika teksnya bukan JSON. Tangani dengan Try/catch seperti kegagalan runtime lainnya; pesan kesalahan memuat teks yang coba di-parsing.
• Ia dihitung sebagai satu Statement pada jumlah Statement per definisi, tetapi tidak berkaitan dengan batas panggilan eksternal maupun batas SetVar.

// 1) API yang tidak mengembalikan JSON: terima sebagai Text lalu parsing
{ "type": "Http", "method": "GET", "url": "https://api.partner.example/v1/quote",
  "responseType": "Text", "name": "resp" },
{ "type": "ParseJson", "name": "quote", "value": "{ /resp/body }" },
 
// 2) Parsing string JSON yang masuk lewat payload
{ "type": "ParseJson", "name": "spec", "value": "{ /payload/fields/specJson }" }

Verifikasi tanda tangan dan pemrosesan teks

Ini adalah Statement untuk memeriksa tanda tangan yang dikirim penyedia pembayaran lewat webhook, dan untuk menguraikan string tempat tanda tangan itu dibungkus. Ketiganya bukan panggilan eksternal melainkan perhitungan, sehingga tidak dihitung ke batas panggilan eksternal dan tidak mendeklarasikan waktu apa pun pada anggaran waktu; karena tidak memiliki posisi data, ketiganya juga tidak berkaitan dengan aturan awalan $. Contoh lengkap yang mengombinasikan ketiganya ada di verifikasi tanda tangan webhook pada Cookbook.

Ketiga Statement memiliki batas atas panjang nilai hasil resolve. Yang dibatasi bukan panjang ekspresinya, melainkan panjang nilai yang ditunjuk ekspresi itu (enam belas karakter { /rawPayload } menunjuk ke puluhan KB), dan jika melebihi batas, eksekusinya gagal sehingga dapat ditangani dengan Try. Angkanya dikumpulkan di Batas atas panjang nilai.

Signature

Memeriksa apakah kode tanda tangan yang diterima sama dengan kode yang dibuat memakai secret, lalu mengikat jawabannya sebagai nilai Boolean. Tanda tangan yang dikirim penyedia pembayaran (PG, MoR) lewat webhook diverifikasi dengan Statement ini.

• Hasil: Boolean. Setelah itu pakai { /<name> } apa adanya sebagai kondisi If.
• value ditulis dengan /rawPayload, bukan /payload yang sudah di-parsing. Jika payload hasil parsing dijadikan string kembali, spasi, notasi angka, dan escape akan dinormalkan sehingga tidak kembali menjadi byte yang ditandatangani pihak lain (Root konteks).
• Tidak ada field yang menentukan notasi keluaran. Karena algorithm mengunci panjang byte kode dan panjang string hex maupun base64 untuk panjang byte yang sama tidak bertumpang tindih, engine dapat memulihkan byte-nya tanpa diberi tahu pihak lain mengirim dalam bentuk yang mana. Huruf besar-kecil pada hex, serta base64 dan base64url (termasuk ada atau tidaknya padding), juga tidak dibedakan karena alasan yang sama.
• Kegagalan dan false dibedakan oleh siapa yang memberi nilai itu.
  • Jika expected tidak ada atau kodenya tidak cocok, hasilnya hanya false, bukan kegagalan. Alasannya, memberi tahu ketiadaan header dan ketidakcocokan kode secara terpisah berarti mengajari pengirim bagian mana yang salah.
  • Jika value kosong, kode dihitung dengan pesan kosong. Body kosong pun adalah objek tanda tangan.
  • Jika secret tidak ada atau bukan notasi yang dideklarasikan secretEncoding, itu kegagalan. Di antara ketiganya, hanya inilah masukan penulis sendiri. secret dan value tidak disertakan dalam pesan kegagalan.
• Batas atas value adalah 65.536 karakter (berdasarkan nilai hasil resolve). Angka ini disesuaikan dengan ukuran body webhook yang benar-benar dikirim penyedia.
• Perbandingannya menilai kesamaan nilai secara constant-time. Jadi tidak ada kebocoran lewat waktu respons tentang berapa byte awal yang sudah cocok.
• Kunci tanda tangan tidak ditulis apa adanya di secret. Deklarasikan kunci itu di secrets pada definisi, lalu tulis sebagai "{ /secrets/<key> }". Nilai di secrets dienkripsi dan disimpan dengan aman oleh WEEGLOO. secretEncoding menyatakan notasi string kunci yang disimpan di secrets.

// Penyedia yang menandatangani seluruh body
{ "type": "Signature", "name": "verified", "algorithm": "SHA256",
  "secret": "{ /secrets/WEBHOOK_SIGNING_SECRET }", "value": "{ /rawPayload }",
  "expected": "{ /headers/x-webhook-signature }" }
 
// Penyedia yang menerbitkan kunci dalam base64 (string base64 disimpan apa adanya di secrets)
{ "type": "Signature", "name": "verified", "algorithm": "SHA256",
  "secret": "{ /secrets/WEBHOOK_SIGNING_KEY }", "secretEncoding": "Base64",
  "value": "{ /rawPayload }", "expected": "{ /headers/webhook-signature }" }

Hash

Men-digest value lalu mengikatnya sebagai string dalam notasi yang ditentukan encoding. Dipakai untuk mereproduksi skema tanda tangan yang bukan HMAC, melainkan "menyambung beberapa field dengan kunci rahasia lalu menghitung SHA256".

• Tidak ada field secret. Di dalam value, tulis { /secrets/<key> } pada posisi tempat skema itu meletakkan kunci. Setiap skema menempatkan kunci di depan, di belakang, atau di tengah, dan dengan cara ini posisi mana pun dapat dinyatakan. Kuncinya dideklarasikan lebih dulu di secrets.
• Hasil: string. Ketika membandingkannya dengan kode yang dikirim pihak lain, tulis { "==": [ "{ /<name> }", "{ /headers/... }" ] }. Perbandingan ini adalah perbandingan kesetaraan biasa, berbeda dengan perbandingan constant-time milik Signature.
• Jika value di-resolve tanpa nilai atau hanya berisi spasi, itu kegagalan (karena ini ekspresi penulis sendiri).
• Batas atas value adalah 128 karakter. Karena tempat ini memuat beberapa field yang disambung, batasnya jauh lebih sempit daripada Signature. Jika Anda harus menghitung atas seluruh body webhook, pakai Signature.

// SHA256(nomor pesanan + jumlah + MERCHANT_KEY) sebagai hex huruf besar
{ "type": "Hash", "name": "expectedSign", "algorithm": "SHA256", "encoding": "HexUpper",
  "value": "{ /payload/orderId }{ /payload/amount }{ /secrets/MERCHANT_KEY }" }

Regex

Menerapkan pattern pada value lalu mengikat apa yang diminta mode. Karena ekspresi nilai tidak memiliki sarana untuk memotong string (hanya ada cat untuk menyambung dan in untuk melihat keterkandungan), Statement ini dipakai untuk menguraikan beberapa nilai yang datang terbungkus dalam satu header, seperti t=…,v1=….

• Hasil: Match berupa Boolean, Capture berupa array atau null. Pada array, indeks 0 adalah keseluruhan kecocokan dan mulai dari 1 adalah grup tangkapan; grup yang tidak berpartisipasi bernilai null (bukan string kosong. String kosong berarti cocok). Jika pattern tidak muncul, Capture bernilai null, bukan array kosong.
• Kedua mode sama-sama menanyakan "apakah pattern muncul di suatu tempat". Jika seluruh teks harus sama dengan pattern, kunci dengan ^…$. Pertanyaannya dibuat sama agar dua Statement, yaitu memeriksa dengan Match lalu mengambil dengan Capture, tidak memberi jawaban yang berbeda.
• pattern adalah satu dari tiga field pada engine ini yang bukan ekspresi nilai (sisanya adalah key pada Cache dan color pada PdfWatermark). Jika pattern yang datang dari permintaan dijalankan apa adanya, pemanggil dapat memilih ekspresi yang akan dijalankan, dan backtracking ekspresi reguler menjadikan hal itu sarana penolakan layanan. Karena itu { /pointer } di dalam pattern pun tidak diubah menjadi nilai dan tetap menjadi bagian pattern secara harfiah.
• Pattern dikompilasi satu kali untuk seluruh definisi ketika eksekusi dimulai. Meski berada di dalam Loop atau ResourceForEach, ia tidak dikompilasi ulang setiap iterasi, dan pattern yang tidak dapat dipakai akan gagal sebelum Statement pertama melakukan apa pun (dapat ditangani dengan Try).

// Menguraikan "t=1492774577,v1=<hex 64 karakter>" menjadi { /sig/1 } = timestamp, { /sig/2 } = kode
{ "type": "Regex", "name": "sig", "mode": "Capture",
  "pattern": "^t=(\\d+),v1=([0-9a-f]{64})$", "value": "{ /headers/x-provider-signature }" }
 
// Hanya memeriksa format
{ "type": "Regex", "name": "isOrderId", "mode": "Match",
  "pattern": "^ORD-\\d{8}-\\d{4}$", "value": "{ /payload/orderId }" }

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 iterasi (untuk mencegah perulangan tak terbatas). Batas atas itu dideklarasikan dengan maxIterations, dan jika tidak dituliskan, batas atas platform yang berlaku. Di dalam body juga dapat dimuat panggilan eksternal (Http, EmailSend) dan penyerapan file Media, dan Statement panggilan eksternal benar-benar dipanggil pada tiap iterasi saat dijalankan. Batas jumlah panggilan eksternal maksimum per satu definisi tetap berlaku.

Pada anggaran waktu ia dihitung sebagai perkalian. Waktu yang dideklarasikan Statement ini adalah waktu yang dideklarasikan body dikalikan maxIterations (atau 10.000 jika tidak ada) (Anggaran waktu). Jika body tidak memuat panggilan eksternal, waktu deklarasinya 0 sehingga anggaran dasar 30 detik menjadi batas yang sesungguhnya.

// foreach
{ "type": "Loop", "over": "{ /payload/fields/items }", "name": "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 }, "name": "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. Jika Anda menempatkan Return pada then milik If, Statement itu mengembalikan nilai ketika kondisi dilanggar dan tidak menjalankan Statement setelahnya. Ini adalah salah satu dari beberapa kegunaan Return.

{ "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": "Generation failed" }, "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 ini.
• Ikhtisar Script: struktur tingkat atas dan waktu yang diberikan untuk satu eksekusi.