Script
Bayangkan Anda mengelola sebuah toko pakaian online. Setiap kali mengunggah produk, menuliskan satu per satu deskripsi yang menarik itu merepotkan. Karena itu, Anda ingin agar dengan memasukkan nama produk dan kata kunci saja, AI yang menuliskan deskripsinya untuk Anda. Namun, untuk memanggil layanan penulisan AI itu, Anda memerlukan sebuah kunci rahasia (access token, kunci yang dipakai layanan luar untuk memastikan "apakah ini benar-benar pengguna yang sudah membayar"). Jika Anda menaruh kunci ini di situs web yang dilihat pelanggan (browser), siapa pun bisa mengambilnya sehingga kunci itu bocor. Dengan kunci yang bocor, orang lain bisa memakai layanan ini sesuka hati dan membebankan biayanya kepada Anda.
Karena itu, dibutuhkan sesuatu yang menyembunyikan kunci di tempat yang tak terjangkau mata pelanggan, lalu memanggil AI menggantikan situs web dan mengisikan hasilnya ke produk. Script adalah hal itu. Script adalah catatan urut-urutan pekerjaan, seperti "panggil AI dengan kunci ini, lalu isikan kalimat yang diterima ke deskripsi produk ini". Ia dituliskan bukan dengan kode, melainkan dengan format baku (JSON, cara penulisan data yang menuliskan item dan nilai di dalam kurung kurawal). Yang dilakukan situs web adalah memanggil Script ini melalui internet, dan kuncinya tersembunyi di dalam Script sehingga tidak terlihat oleh pelanggan.
Ini bisa diibaratkan seperti menempelkan resep yang sudah ditulis sebelumnya di dapur. Ketika pelanggan memesan menu itu (ketika situs web memanggil Script), dapur (WEEGLOO) memasak sesuai urutan yang tertulis di resep lalu menyajikan masakan yang sudah jadi. Sang pemilik hanya menuliskan dan menempelkan resepnya saja, dan tidak memasak sendiri setiap kali ada pesanan masuk. Di halaman ini, Anda akan lebih dulu melihat apa itu Script, seperti apa bentuknya, dan apa yang dikembalikannya saat dipanggil, lalu memeriksa bentuknya melalui contoh Script "pengisian deskripsi produk" pada toko pakaian. Di bagian akhir, Anda juga akan melihat cara menyambungkan Script ini agar berjalan sendiri saat produk didaftarkan.
Pekerjaan yang diambil alih Script
Bahkan untuk satu pekerjaan mengisi satu deskripsi produk pun, ada bermacam-macam hal yang harus dikerjakan di baliknya. Memeriksa apakah pihak yang memanggil punya izin, memeriksa apakah nilai yang dikirim sudah benar, memanggil layanan AI luar dengan kunci yang disembunyikan, memasukkan hasil yang diterima ke tempat yang diinginkan (deskripsi produk), lalu mengembalikan respons. Dahulu, program perantara yang mengerjakan hal-hal ini harus Anda buat sendiri, unggah ke server, dan kelola. Tujuan Script adalah menggantikan semua pekerjaan ini dengan menuliskannya di satu tempat tanpa kode.
- Satu Script adalah satu loket panggilan. Satu loket yang bisa dipanggil situs web melalui internet, itulah satu Script. Cara yang dipakai saat memanggil (
method) menentukan Script mana yang dijalankan. - Pekerjaan disusun dari atas ke bawah. Di dalam Script, Anda menuliskan tindakan yang akan dijalankan secara berurutan. Tindakan dijalankan satu per satu dari atas, dan hasil tindakan sebelumnya diteruskan ke tindakan berikutnya.
- Anda memilih dan merangkai tindakan yang sudah ditetapkan. Anda tidak memasukkan kode sembarangan, melainkan memilih dan menyusun tindakan yang sudah disediakan (membuat, membaca, mengubah, dan menghapus sumber daya; memanggil layanan luar; menyimpan nilai; memeriksa kondisi; mengulang; dan sebagainya).
Definisi yang menuliskan apa yang harus dilakukan
Satu Script terdiri dari sebuah "definisi" yang menetapkan tiga hal.
- Cara pemanggilan(
method): cara yang dipakai saat memanggil Script ini. Salah satu dariGet,Post,Put,Patch,Delete, dan saat memanggil, nilai inilah yang menentukan Script yang mana. - Tugas(
statements): daftar tindakan yang dijalankan dari atas ke bawah. Setidaknya harus ada satu. - Pemeriksaan input(
payloadSchema, opsional): format untuk memeriksa input yang dikirim bersama saat pemanggilan, sebelum dijalankan. Jika ditetapkan, input yang tidak sesuai format tidak dijalankan, melainkan dikembalikan.
Berikut adalah contoh Script "pengisian deskripsi produk" pada toko pakaian. Yang ditangani Script ini adalah satu produk yang memuat nama produk dan kata kunci. Input yang diberikan dari situs web (pada eksekusi otomatis yang akan kita lihat nanti, produk yang didaftarkan diteruskan apa adanya) berbentuk seperti ini.
{
"sys": { "id": "3trmXRMKq7bd0Prbef1... (nomor produk)" },
"fields": {
"productName": { "id-ID": "Tumbler Stainless 500ml" },
"keywords": { "id-ID": "tahan panas, ringan, camping" }
}
}Berikut definisi Script yang menerima produk ini, membuat deskripsi dengan AI luar, lalu mengisi deskripsi produk (body) tersebut.
{
"method": "Post",
"statements": [
{ "type": "Http", "method": "POST",
"url": "https://api.ai-writer.example.com/v1/generate",
"headers": [
{ "key": "Authorization", "value": "Bearer <access token rahasia>", "secret": true }
],
"body": {
"product": "{ /payload/fields/productName/id-ID }",
"keywords": "{ /payload/fields/keywords/id-ID }"
},
"name": "gen" },
{ "type": "ResourcePatch", "resource": "Content",
"target": { "sys": { "id": "{ /payload/sys/id }" } },
"fields": { "body": { "id-ID": "{ /gen/body/text }" } },
"publish": true },
{ "type": "Return", "value": { "id": "{ /payload/sys/id }" }, "statusCode": 200 }
]
}- Tindakan pertama (
Http) memanggil layanan AI luar dengan kunci yang disembunyikan. Jika Anda menambahkansecret: truepada header yang memuat kunci, nilai itu tidak terlihat oleh pelanggan dan baru dibuka tepat sebelum pemanggilan. Hasil yang diterima disimpan dengan namagen. - Tindakan kedua (
ResourcePatch) mengisi hanya deskripsi produk (body) tersebut dengan kalimat yang diterima sebelumnya ({ /gen/body/text }). Nilai produk lainnya tidak disentuh. - Digunakan penanda tempat
{ /… }yang mengalirkan nilai ke tahap berikutnya.{ /payload/fields/productName/id-ID }menunjuk nama produk yang diteruskan,{ /payload/sys/id }menunjuk nomor produk itu, dan{ /gen/body/text }menunjuk kalimat yang dikembalikan AI. - Tindakan terakhir (
Return) mengembalikan nomor produk yang deskripsinya telah diisi. - Alasan menuliskan nilai Content per bahasa seperti
{ "id-ID": … }, seluruh jenis tindakan yang bisa dimasukkan kestatements, serta sintaksis penanda tempat dan kondisi/perhitungan dibahas di Ekspresi nilai dan Katalog Statement.
Apa yang dikembalikan saat dipanggil
Di bagian akhir, Script mengembalikan nilai dari tindakan Return ke pihak yang memanggil. Respons yang dikembalikan memuat hal-hal berikut.
requestId: nomor identifikasi yang menunjuk eksekusi kali ini.durationMs: waktu yang diperlukan untuk eksekusi (milidetik).statusCode: kode status dariReturnyang tercapai (200 jika tidak ditentukan secara terpisah).returnatauerror: nilai yang dikembalikanReturn. Biasanya dimuat direturn, dan jika nilai itu ditandai sebagai error, ia dimuat dierror. Keduanya tidak muncul bersamaan.
"Pengisian deskripsi produk" pun berjalan di tempat ia dipanggil, dan respons di atas langsung kembali. Namun, karena di dalamnya ada tindakan yang memanggil AI luar, respons itu bisa memerlukan beberapa detik sampai tiba. Waktu yang tersedia untuk satu kali eksekusi dibahas di bawah pada Waktu yang diberikan untuk eksekusi. Respons yang kembali berbentuk seperti ini.
{
"requestId": "3trmXRMZ8kqLb2Prdf1eYc0axWnKv",
"durationMs": 1840,
"statusCode": 200,
"return": { "id": "3trmXRMKq7bd0Prbef1... (nomor produk)" }
}Dengan id dari return ini, situs web dapat menandai produk yang deskripsinya baru saja diisi, lalu menampilkan deskripsi baru itu kepada pelanggan.
Jika Script berakhir tanpa mencapai Return, yang dikembalikan hanyalah statusCode 200 tanpa return maupun error. Aturan rinci tentang menentukan body respons dan kode status melalui Return dibahas di Return pada Katalog Statement.
Waktu yang diberikan untuk eksekusi
Script dijalankan di tempat ia dipanggil. Pihak yang memanggil menerima hasil eksekusi itu langsung sebagai respons. Tidak ada alur yang menanyakan lalu mengambil hasilnya kemudian.
Waktu yang tersedia untuk satu kali eksekusi memiliki anggaran. Bawaannya adalah 30 detik. Jika di dalamnya ada tindakan yang memanggil layanan luar, anggarannya bertambah sebanyak waktu tunggu yang sudah ditetapkan untuk tindakan itu. Meskipun bertambah seperti ini, batas paling banyaknya adalah 180 detik.
Tindakan yang mengulang sesuatu memakan anggaran dalam jumlah besar. Sebabnya, anggaran yang dihitung adalah waktu tunggu yang ditetapkan pada tindakan di dalam perulangan dikalikan jumlah perulangan. Jika Anda menetapkan jumlah perulangan yang besar, anggarannya pun dihitung sebesar itu.
Jika waktu yang ditetapkan terlampaui, eksekusi itu terhenti di titik tersebut. "Pengisian deskripsi produk" memanggil AI luar satu kali, jadi anggaran Script ini adalah 30 detik bawaan ditambah waktu tunggu untuk satu panggilan itu.
Berapa besar anggaran yang dihitung untuk setiap tindakan, serta batasan lain yang berlaku pada eksekusi, dibahas di Semantik eksekusi, batasan, dan keamanan.
Siapa yang membuat Script
Alih-alih menuliskan tindakan yang rumit satu per satu dengan tangan, Script dirancang untuk dibuat oleh agen AI atau program. Jika Anda meminta secara lisan kepada agen AI, "buatkan loket yang mengisi deskripsi produk", agen akan membuatkan definisi seperti yang Anda lihat di atas. Dengan satu kalimat saja, terciptalah satu loket yang akan bekerja di balik situs web.
Alur rinci untuk membuat Script dengan agen AI dibahas di Membuat backend hanya dengan berbicara.
Script yang sudah dibuat dilihat dan dikelola orang melalui layar pengelolaan (studio konten). Anda memeriksa nama dan definisinya, lalu menyunting atau menghapusnya bila perlu. Pihak yang benar-benar memanggil Script adalah situs web atau aplikasi yang dilihat pelanggan (frontend). Dengan identitas anggota yang mendaftar ke produk (ServiceUser), Script hanya bisa dijalankan, tetapi tidak bisa dibuat atau disunting.
Apa bedanya dengan Webhook
Script dan Webhook sama-sama alat yang menghubungkan dengan dunia luar, tetapi arah pemanggilannya berlawanan.
- Webhook bereaksi dengan sendirinya ketika perubahan yang ditentukan terjadi (seperti saat produk didaftarkan). Tanpa dipanggil orang pun, ia bergerak sendiri begitu peristiwa terjadi. Namun, ia tidak mengembalikan hasil kepada pihak yang memanggil.
- Script adalah loket yang dipanggil langsung oleh situs web saat dibutuhkan. Ia baru berjalan setelah dipanggil, dan hasil eksekusi itu langsung diterima kembali.
"Ketika pemilik menekan 'isi deskripsi', AI dipanggil untuk menerima lalu mengisi deskripsi" adalah pekerjaan di mana pihak pemanggil menunggu hasil, sehingga cocok memakai Script; sedangkan "ketika produk didaftarkan, sesuatu terjadi secara otomatis" adalah pekerjaan yang bereaksi terhadap peristiwa, sehingga cocok memakai Webhook. Dan keduanya bisa dipakai bersamaan. Kita akan melihatnya tepat setelah ini.
Agar deskripsi terisi otomatis saat produk didaftarkan
Sampai di sini, pemilik memanggil Script secara langsung dengan menekan tombol "isi deskripsi". Melangkah lebih jauh, tanpa menekan tombol pun Anda bisa membuat Script berjalan dengan sendirinya begitu produk didaftarkan. Sebab, Webhook menangkap peristiwa itu lalu memanggilkan Script kita.
Alurnya seperti ini.
- Pemilik mendaftarkan produk. Saat ini, ia hanya mengisi nama produk dan kata kunci, sedangkan deskripsi dibiarkan kosong.
- Webhook mengetahui peristiwa didaftarkannya produk baru.
- Webhook meneruskan produk yang baru saja didaftarkan apa adanya ke Script "pengisian deskripsi produk" kita, lalu menjalankannya.
- Script membuat deskripsi dengan AI luar lalu mengisi deskripsi produk (
body) itu. - Sesaat kemudian, deskripsi produk sudah terisi dengan sendirinya.
Di sini Script yang dipakai sama persis dengan sebelumnya. Yang berubah hanyalah pemicu pemanggilannya. Alih-alih tombol, yang memanggilnya adalah peristiwa "produk telah didaftarkan". Karena produk yang didaftarkan langsung menjadi input Script, Script memungut produk itu dengan { /payload/sys/id } lalu mengisi deskripsinya.
Yang perlu ditetapkan di sisi Webhook ada tiga hal. Peristiwa apa yang direspons (saat produk baru didaftarkan), hanya produk yang mana yang direspons (dibatasi menurut jenis produk), dan apa yang dilakukan (memanggil Script kita alih-alih memberi tahu ke alamat luar).
Anda mungkin khawatir deskripsi yang diisi Script akan kembali memicu peristiwa "produk telah berubah" sehingga berulang tanpa henti. Tidak demikian. Penulisan oleh Script tidak memicu peristiwa baru selama tidak diaktifkan secara terpisah, dan platform pun mencegah perulangan tanpa henti.
Beberapa Script bisa Anda atur agar hanya dapat dijalankan melalui Webhook seperti ini, sementara pemanggilan langsung dari luar ke alamatnya diblokir. Dengan begitu, Script itu hanya bereaksi terhadap peristiwa yang telah ditentukan, dan jika dipanggil langsung, ia ditolak. Cara pengaturannya dibahas di Resource Script dan endpoint.
Pengaturan rinci untuk menyambungkannya seperti ini dibahas di Webhook.
Ketika Script sangat berguna
Jika pekerjaannya sebatas memberi tahu dunia luar bahwa "hal seperti ini terjadi", satu Webhook saja sudah cukup. Namun, jika setelah memanggil layanan luar Anda harus melihat hasilnya lalu menilai dan memprosesnya lebih lanjut, Anda memerlukan Script yang menyatukan seluruh alur itu di satu tempat.
Sebagai contoh, perhatikan sebuah fitur berbayar yang membuatkan gambar AI. Ketika pelanggan meminta pembuatan gambar, pekerjaan berikut harus terjadi secara berurutan.
- Memeriksa apakah kredit pelanggan mencukupi. Jika kurang, berhenti di sini lalu memberi tahu bahwa "kredit tidak mencukupi".
- Jika mencukupi, mengurangi kredit terlebih dahulu sebesar biayanya.
- Memanggil layanan AI luar untuk membuat gambar.
- Menyimpan gambar yang telah dibuat sebagai Content.
- Jika terjadi masalah pada langkah 3 atau 4, mengembalikan kredit yang baru saja dikurangi.
Webhook memang bisa memberi tahu dunia luar bahwa "ada permintaan yang masuk", tetapi ia tidak bisa melihat hasilnya lalu mengurangi kredit atau membatalkan perubahan saat gagal seperti ini. Menyambungkan beberapa langkah sesuai kondisi, lalu membatalkan langkah sebelumnya bila terjadi kegagalan, adalah pekerjaan yang ditangani Script. Berikut adalah kasus-kasus di mana Script benar-benar menunjukkan perannya.
- Ketika harus memproses lebih lanjut setelah melihat hasil: berdasarkan respons yang dikembalikan layanan luar, Script memutuskan di tempat itu juga apakah akan menyimpan, mengurangi, atau mengembalikan.
- Ketika permintaan bersamaan tidak boleh saling berbenturan: meskipun pelanggan yang sama mengirim permintaan dua kali dalam waktu singkat, kredit tidak boleh dikurangi dua kali. Setelah membaca nilainya, tepat sebelum menyimpan, Script memeriksa melalui versi "apakah nilai ini tidak diubah oleh permintaan lain sementara itu", lalu berhenti bila terjadi ketidaksesuaian.
- Ketika diperlukan izin yang tidak dimiliki pihak pemanggil: pelanggan tidak memiliki izin untuk mengubah sendiri saldo kreditnya secara langsung. Meskipun demikian, pengurangan tetap bisa terjadi dengan aman karena Script dijalankan dengan pelimpahan izin dari pembuatnya. Pihak pemanggil hanya diberi izin untuk menjalankan Script. Pelimpahan ini dibahas secara rinci di bawah pada Izin untuk menjalankan dan mengelola.
Cara menuliskan contoh ini menjadi definisi Script yang sesungguhnya dibahas di Cookbook, pada contoh yang memeriksa, mengurangi, dan mengembalikan kredit.
Izin untuk menjalankan dan mengelola
Untuk menjalankan atau mengelola Script, peran (SpaceRole) harus memiliki izin yang sesuai.
- Menjalankan: untuk memanggil Script, peran harus memiliki izin menjalankan Script (Execute). Tanpa itu, eksekusi akan terhalang.
- Mengelola: untuk membuat, menyunting, dan menghapus Script, masing-masing memerlukan izin membuat, menyunting, dan menghapus.
Saat Script dijalankan, yang diperiksa hanya satu hal: apakah pihak yang memanggil punya izin menjalankan (Execute). Tindakan-tindakan individual yang disusun di dalam Script tidak diperiksa izinnya secara terpisah pada saat dijalankan. Ini seperti ketika Anda memanggil program yang sudah diizinkan untuk dijalankan: yang dilihat adalah izin untuk menjalankan program itu, dan setiap pekerjaan di dalamnya tidak perlu meminta izin satu per satu setiap kali.
Sebagai gantinya, izin untuk tindakan individual diperiksa lebih dulu bukan saat dijalankan, melainkan saat Script disimpan. Script baru bisa disimpan jika pembuatnya benar-benar memiliki izin untuk pekerjaan Content dan Media yang ditangani tindakan di dalam Script itu. Misalnya, Script "pengisian deskripsi produk" menyunting deskripsi pada Content produk, jadi jika pembuatnya tidak memiliki izin untuk menyunting produk, penyimpanan akan ditolak. Artinya, Script yang memuat tindakan tanpa izin memang tidak akan tersimpan sejak awal.
Dilihat begini, menjalankan Script sama seperti melaksanakan pekerjaan itu dengan pelimpahan izin dari pembuatnya. Meskipun suatu pekerjaan tidak dimiliki oleh pihak yang memanggil, selama pekerjaan itu bisa dilakukan pembuatnya, pekerjaan itu tetap terjadi melalui Script. Karena itu, saat membuat Script, Anda harus menentukan dengan cermat tindakan apa yang dimuat di dalamnya. Izin pembuat itulah yang menjadi batas cakupan apa yang bisa dilakukan Script tersebut.
Cara memuat izin ke dalam peran dibahas di Peran dan Izin.
Hal yang perlu diketahui
- Tidak ada penerbitan. Script bukan jenis sumber daya yang diterbitkan lalu disampaikan ke pengunjung, melainkan loket yang dibuat di layar pengelolaan lalu dipanggil dan dipakai oleh situs web. Karena itu, berbeda dengan Content dan Media, ia tidak memiliki status penerbitan maupun pembatalan penerbitan, dan langsung bisa dipakai begitu dibuat. Setiap kali disunting, versinya hanya bertambah satu, dan saat dihapus pun ia langsung terhapus tanpa langkah pendahuluan seperti pembatalan penerbitan.
- Ada batas jumlahnya. Karena Script termasuk objek yang dikenai biaya, jumlah yang bisa dimiliki satu Organization ditetapkan menurut paket harga (Free 10, Basic 30, Pro 100, Enterprise tak terbatas). Begitu batasnya tercapai, Anda tidak bisa membuat Script baru, dan jika Anda menghapus Script yang tidak dipakai, satu tempat akan kembali kosong.
Mengelola di studio konten
Script yang sudah dibuat dilihat dan dikelola di layar Script pada studio konten. Ketika Anda menekan Scripts di menu kiri, Script yang telah Anda buat sejauh ini muncul sebagai daftar. Setiap baris pada daftar menampilkan nama, Endpoint (cara pemanggilan ditampilkan bersama alamatnya), apakah panggilan anonim diizinkan (Anonim), waktu terakhir diubah, dan siapa yang mengubahnya.

Definisi biasanya dibuatkan untuk Anda oleh agen AI, tetapi Anda juga bisa membuatnya sendiri langsung di layar ini. Script baru dibuat dengan tombol Buat di kanan atas daftar.
- Tekan tombol Buat di kanan atas daftar.
- Masukkan
pengisian deskripsi produkke kolom Nama. - Pada Metode HTTP, pilih cara yang dipakai untuk memanggil Script ini (di sini,
POST). - Masukkan definisi yang menuliskan apa yang harus dilakukan ke kolom Statement. Anda bisa memasukkan definisi dari contoh "pengisian deskripsi produk" di atas apa adanya.
Selain itu, pada layar pembuatan ada kolom Izinkan panggilan langsung (jika dimatikan, ia tidak dapat dipanggil melalui URL panggilan dan hanya dijalankan melalui Webhook atau Scheduler. Bawaannya menyala), Izinkan panggilan anonim (jika dinyalakan, ikut terbentuk alamat panggilan anonim yang bisa dipanggil pihak ketiga tanpa login Weegloo. Bawaannya mati), dan URL panggilan (dua baris, yaitu Standar dan Anonim, yang baru ditetapkan setelah disimpan sehingga sekarang masih kosong).

Jika Anda ingin memeriksa input yang dikirim bersama pemanggilan sebelum dijalankan, nyalakan Validasi Payload pada Payload Schema lalu tuliskan format yang akan diperiksa. Setelah semuanya terisi, tekan tombol Buat di kanan atas.
Ketika Anda menekan salah satu Script di daftar, layar detailnya terbuka. Layar detail terbagi menjadi dua tab, Log eksekusi dan Pengaturan, dan saat pertama dibuka yang tampil adalah Log eksekusi. Pada tab Pengaturan Anda memeriksa nama dan definisinya, dan di sisi kanan Anda melihat nomor (ID) Script ini bersama Versi dan Perubahan (waktu dibuat, pembuatnya, waktu terakhir diubah, dan pengubahnya). Setelah menyunting definisi lalu menekan Simpan, versinya bertambah satu. Script yang tidak lagi dipakai dihapus dengan Hapus.

Pada tab Log eksekusi, catatan eksekusi Script ini yang sesungguhnya bertumpuk satu baris demi satu baris. Pada tiap baris terlihat Dieksekusi pada, apa yang memulai eksekusi itu (Pemicu), Hasil, Durasi, dan ID permintaan yang menunjuk eksekusi tersebut. Dengan kolom Hasil di bagian atas, Anda dapat memilih untuk melihat hanya yang berhasil atau hanya yang gagal, dan jika Anda menekan Segarkan Log, catatan yang baru saja dieksekusi pun terbaca kembali.
Catatan tidak tersimpan lama. Eksekusi yang berhasil terhapus dengan sendirinya setelah 1 jam, dan eksekusi yang gagal setelah 3 hari. Karena yang berhasil hilang lebih dulu, ada saatnya di daftar hanya tampak kegagalan saja.

Hal yang dilakukan berikutnya
- Ikhtisar Script: Membahas struktur teratas dari definisi yang menyusun Script, aturan eksekusi, dan kumpulan dokumen sintaksis.
- Katalog Statement: Membahas jenis dan field tindakan yang bisa dimasukkan ke
statements(membuat, membaca, mengubah, dan menghapus sumber daya; memanggil layanan luar; kondisi; perulangan; dan sebagainya). - Webhook: Membahas cara membuat sesuatu bereaksi otomatis ketika perubahan yang ditentukan terjadi, seperti menyambungkan Script agar berjalan sendiri saat produk didaftarkan.
