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 cukup memasukkan nama produk dan kata kunci, lalu 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). Situs web cukup 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 empat hal.

• Cara pemanggilan(method): cara yang dipakai saat memanggil Script ini. Salah satu dari Get, Post, Put, Patch, Delete, dan saat memanggil, nilai inilah yang menentukan Script yang mana.
• Tempat eksekusi(executionMode): apakah dijalankan langsung di tempat ia dipanggil (Sync), atau dijalankan di latar belakang (Async). Dibahas di bawah pada Eksekusi langsung dan eksekusi latar belakang.
• 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.

Mari kita lihat 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",
  "executionMode": "Async",
  "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 menambahkan secret: true pada header yang memuat kunci, nilai itu tidak terlihat oleh pelanggan dan baru dibuka tepat sebelum pemanggilan. Hasil yang diterima disimpan dengan nama gen.
• 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 ke statements, 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 dari Return yang tercapai (200 jika tidak ditentukan secara terpisah).
• return atau error: nilai yang dikembalikan Return. Biasanya dimuat di return, dan jika nilai itu ditandai sebagai error, ia dimuat di error. Keduanya tidak muncul bersamaan.

Namun, karena "pengisian deskripsi produk" memanggil AI luar, ia dijalankan di latar belakang (lihat Eksekusi langsung dan eksekusi latar belakang di bawah). Karena itu, saat dipanggil, yang lebih dulu langsung kembali hanyalah 202 dan requestId sebagai tanda "sudah diterima", sedangkan respons di atas diterima sesaat kemudian dengan menanyakannya kembali (polling) memakai requestId itu. Respons yang sudah selesai 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.

Eksekusi langsung dan eksekusi latar belakang

Script dapat dijalankan dengan dua cara, dan ditentukan melalui executionMode pada definisi.

• Eksekusi langsung(Sync): dijalankan seketika di tempat ia dipanggil, lalu langsung mengembalikan respons yang sudah jadi. Cocok untuk pekerjaan yang cepat selesai tanpa panggilan ke luar.
• Eksekusi latar belakang(Async): dijalankan di latar belakang. Saat dipanggil, ia lebih dulu langsung mengembalikan 202 dan requestId saja sebagai tanda "sudah diterima", sedangkan hasil sesungguhnya diambil kemudian dengan menanyakannya kembali (polling) memakai requestId itu.

Ada satu aturan. Jika ada satu saja tindakan yang memanggil layanan luar atau tindakan yang menerima berkas dan memasukkannya sebagai Media, maka Script itu harus dijalankan sebagai eksekusi latar belakang. "Pengisian deskripsi produk" pun memanggil AI luar, sehingga ia berjalan di latar belakang. Jika Anda mencoba menyimpannya sebagai eksekusi langsung, penyimpanan akan ditolak. Ini agar pihak yang memanggil tidak tertahan meskipun respons dari luar terlambat.

Waktu yang tersedia untuk eksekusi pun ada anggarannya. Eksekusi langsung secara default 10 detik, dan eksekusi latar belakang secara default 60 detik. Aturan rinci seperti cara melakukan polling dan tindakan apa saja yang mengharuskan eksekusi latar belakang 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 diterima kembali seketika, atau melalui polling jika berupa eksekusi latar belakang.

"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.

1. Pemilik mendaftarkan produk. Saat ini, ia hanya mengisi nama produk dan kata kunci, sedangkan deskripsi dibiarkan kosong.
2. Webhook mengetahui peristiwa didaftarkannya produk baru.
3. Webhook meneruskan produk yang baru saja didaftarkan apa adanya ke Script "pengisian deskripsi produk" kita, lalu menjalankannya.
4. Script membuat deskripsi dengan AI luar lalu mengisi deskripsi produk (body) itu.
5. 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.

Pengaturan rinci untuk menyambungkannya seperti ini dibahas di Webhook.

Ketika Script sangat berguna

Jika pekerjaannya hanya perlu 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.

Mari kita ambil contoh sebuah fitur berbayar yang membuatkan gambar AI. Ketika pelanggan meminta pembuatan gambar, pekerjaan berikut harus terjadi secara berurutan.

1. Memeriksa apakah kredit pelanggan mencukupi. Jika kurang, berhenti di sini lalu memberi tahu bahwa "kredit tidak mencukupi".
2. Jika mencukupi, mengurangi kredit terlebih dahulu sebesar biayanya.
3. Memanggil layanan AI luar untuk membuat gambar.
4. Menyimpan gambar yang telah dibuat sebagai Content.
5. 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 cukup diberi izin untuk menjalankan Script saja. 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: cukup dilihat 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 3, Basic 10, Pro 50, 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 Script di menu kiri, Script yang telah Anda buat sejauh ini muncul sebagai daftar. Setiap baris menampilkan nama, cara pemanggilan (Metode HTTP), Script ID yang menunjuk Script tersebut, tempat eksekusinya (Mode eksekusi), dan tanggal terakhir kali disunting.

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.

1. Tekan tombol Buat di kanan atas daftar.
2. Masukkan pengisian deskripsi produk ke kolom Nama.
3. Pada Metode HTTP, pilih cara yang dipakai untuk memanggil Script ini (di sini, POST).
4. Pada Mode eksekusi, pilih Async (eksekusi latar belakang). Karena Script ini memanggil AI luar, ia harus dijalankan sebagai eksekusi latar belakang.
5. Masukkan definisi yang menuliskan apa yang harus dilakukan ke kolom Statement. Anda bisa memasukkan definisi dari contoh "pengisian deskripsi produk" di atas apa adanya.

Jika Anda ingin memeriksa input yang dikirim bersama pemanggilan sebelum dijalankan, aktifkan Validasi Payload pada Payload Schema lalu tuliskan format yang akan diperiksa. Setelah semuanya terisi, tekan tombol Simpan di kanan atas.

Ketika Anda menekan salah satu Script di daftar, layar detailnya terbuka. Di sini Anda memeriksa nama dan definisinya, dan bisa juga melihat alamat untuk memanggil Script ini (Execute URL). Setelah menyunting definisi lalu menekan Simpan, versinya bertambah satu, dan Script yang tidak lagi dipakai dihapus dengan Hapus.

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.