Halaman ini berlaku untuk Apigee dan Apigee Hybrid.
Baca dokumentasi Apigee Edge.
Apa
Kebijakan ini memungkinkan Anda menambahkan kode JavaScript kustom yang dijalankan dalam konteks alur proxy API. Dalam kode JavaScript kustom, Anda dapat menggunakan objek, metode, dan properti dari model objek JavaScript Apigee. Model objek memungkinkan Anda mendapatkan, menetapkan, dan menghapus variabel dalam konteks alur proxy. Anda juga dapat menggunakan fungsi kriptografi dasar yang disediakan dengan model objek.
Kebijakan ini merupakan Kebijakan yang dapat diperluas, dan penggunaan kebijakan ini mungkin memiliki implikasi biaya atau pemanfaatan, bergantung pada lisensi Apigee Anda. Untuk mengetahui informasi tentang jenis kebijakan dan implikasi penggunaan, lihat Jenis kebijakan.
Tentang
Ada banyak kasus penggunaan kebijakan JavaScript. Misalnya, Anda dapat memperoleh dan menetapkan variabel alur, menjalankan logika kustom dan melakukan penanganan fault, mengekstrak data dari permintaan atau respons, mengedit URL target backend secara dinamis, dan banyak lagi. Kebijakan ini memungkinkan Anda menerapkan perilaku kustom yang tidak tercakup dalam kebijakan Apigee standar lainnya. Bahkan, Anda dapat menggunakan kebijakan JavaScript untuk mencapai banyak perilaku yang sama dengan yang diterapkan oleh kebijakan lain, sepertiAssignMessage dan ExtractVariable.
Satu kasus penggunaan yang tidak kami rekomendasikan untuk kebijakan JavaScript adalah logging. Kebijakan MessageLogging jauh lebih cocok untuk logging ke platform logging pihak ketiga seperti Splunk, Sumo, dan Loggly, dan Anda dapat meningkatkan performa proxy API dengan menjalankan kebijakan MessageLogging di PostClientFlow, yang dijalankan setelah respons dikirim kembali ke klien.
Kebijakan JavaScript memungkinkan Anda menentukan file sumber JavaScript yang akan dijalankan atau
Anda dapat menyertakan kode JavaScript secara langsung dalam konfigurasi kebijakan dengan elemen
<Source>
.
Apa pun pilihannya, kode JavaScript akan dieksekusi saat langkah tempat kebijakan terkait dijalankan.
Untuk opsi file sumber, kode sumber selalu disimpan di lokasi standar dalam paket proxy: apiproxy/resources/jsc
. Atau, Anda juga dapat menyimpan kode sumber dalam file resource di level lingkungan atau organisasi. Untuk
mengetahui petunjuknya, lihat File resource. Anda juga dapat mengupload JavaScript melalui editor proxy UI Apigee.
File sumber JavaScript harus selalu memiliki ekstensi .js
.
Apigee mendukung JavaScript yang berjalan pada mesin Rhino JavaScript 1.7.13.
Video
Tonton video singkat untuk mempelajari cara membuat ekstensi kebijakan kustom menggunakan kebijakan JavaScript.
Sampel
Menulis ulang URL target
Berikut ini kasus penggunaan yang umum: mengekstrak data dari isi permintaan, menyimpannya dalam variabel alur, dan menggunakan variabel alur tersebut di tempat lain dalam alur proxy. Misalnya, Anda memiliki aplikasi yang memungkinkan pengguna memasukkan nama dalam formulir HTML dan mengirimkannya. Anda ingin proxy API mengekstrak data formulir dan menambahkannya secara dinamis ke URL yang digunakan untuk memanggil layanan backend. Bagaimana cara melakukannya dalam kebijakan JavsScript?
- Di UI Apigee, buka proxy yang Anda buat di editor proxy.
- Pilih tab Develop.
- Dari menu New, pilih New Script.
- Dalam dialog, pilih JavaScript dan beri nama skrip, seperti
js-example
. - Tempel kode berikut di editor kode dan simpan proxy. Hal penting yang perlu
diperhatikan adalah objek
context
. Objek ini tersedia untuk kode JavaScript di mana pun dalam alur proxy. Metode ini digunakan untuk mendapatkan konstanta khusus alur, untuk memanggil metode get/set yang berguna, dan untuk operasi lainnya. Bagian objek ini adalah model objek JavaScript Apigee. Perlu diketahui juga bahwa variabel alurtarget.url
adalah variabel baca/tulis bawaan yang dapat diakses dalam alur Target Request. Saat kita menetapkan variabel tersebut dengan URL API, Apigee akan melakukan panggilan backend ke URL tersebut. Pada dasarnya kami telah menulis ulang URL target asli, yaitu URL apa pun yang Anda tentukan saat membuat proxy (misalnya, http://www.example.com).
if (context.flow=="PROXY_REQ_FLOW") { var username = context.getVariable("request.formparam.user"); context.setVariable("info.username", username); } if (context.flow=="TARGET_REQ_FLOW") { context.setVariable("request.verb", "GET"); var name = context.getVariable("info.username"); var url = "http://mocktarget.apigee.net/" context.setVariable("target.url", url + "?user=" + name); }
- Dari menu Kebijakan Baru, pilih JavaScript.
- Beri nama kebijakan, seperti
target-rewrite
. Setujui nilai default dan simpan kebijakan. - Jika memilih Proxy Endpoint Preflow di Navigator, Anda akan melihat bahwa kebijakan telah ditambahkan ke alur tersebut.
- Di Navigator, pilih ikon Target Endpoint PreFlow.
- Dari Navigator, tarik kebijakan JavaScript ke sisi Permintaan pada Endpoint Target di editor alur.
- Simpan.
- Panggil API seperti ini, dengan mengganti nama organisasi dan nama proxy Anda yang benar sesuai kebutuhan:
curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST -d 'user=Will' http://myorg-test.apigee.net/js-example
Satu hal terakhir, mari kita lihat definisi XML untuk kebijakan JavaScript yang digunakan dalam contoh ini. Hal penting yang perlu diperhatikan adalah bahwa elemen <ResourceURL>
digunakan untuk menentukan file sumber JavaScript yang akan dieksekusi. Pola yang sama ini digunakan untuk semua file sumber JavaScript: jsc://filename.js
. Jika kode JavaScript
mengharuskan penyertaan, Anda dapat menggunakan satu atau beberapa elemen <IncludeURL>
untuk
melakukannya, seperti yang akan dijelaskan nanti dalam referensi ini.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <Javascript async="false" continueOnError="false" enabled="true" timeLimit="200" name="target-rewrite"> <DisplayName>target-rewrite</DisplayName> <Properties/> <ResourceURL>jsc://js-example.js</ResourceURL> </Javascript>
Mengambil nilai properti dari JavaScript
Anda dapat menambahkan elemen <Property>
dalam konfigurasi, lalu mengambil nilai elemen tersebut dengan JavaScript saat runtime.
Gunakan atribut name
elemen untuk menentukan nama yang akan digunakan untuk mengakses properti dari kode JavaScript. Nilai elemen <Property>
(nilai
antara tag pembuka dan penutup) adalah nilai literal yang akan diterima oleh
JavaScript.
Di JavaScript, Anda mengambil nilai properti kebijakan dengan mengaksesnya sebagai properti objek
Properties
, seperti berikut:
- Konfigurasikan properti. Di sini, nilai properti adalah nama variabel
response.status.code
.<Javascript async="false" continueOnError="false" enabled="true" timeLimit="200" name="JavascriptURLRewrite"> <DisplayName>JavascriptURLRewrite</DisplayName> <Properties> <Property name="source">response.status.code</Property> </Properties> <ResourceURL>jsc://JavascriptURLRewrite.js</ResourceURL> </Javascript>
- Ambil properti dengan JavaScript. Di sini, nilai yang diambil -- nama variabel --
kemudian digunakan oleh fungsi
getVariable
untuk mengambil nilai variabel.var responseCode = properties.source; // Returns "response.status.code" var value = context.getVariable(responseCode); // Get the value of response.status.code context.setVariable("response.header.x-target-response-code", value);
Menangani error
Untuk contoh dan pembahasan tentang teknik penanganan error yang dapat Anda gunakan dalam pemanggilan JavaScript, lihat Cara benar untuk menampilkan error dari kebijakan JavaScript. Saran yang ditawarkan di Komunitas Apigee hanya untuk informasi dan tidak merepresentasikan praktik terbaik yang direkomendasikan oleh Google.
Referensi elemen
Referensi elemen menjelaskan elemen dan atribut kebijakan JavaScript.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <Javascript async="false" continueOnError="false" enabled="true" timeLimit="200" name="JavaScript-1"> <DisplayName>JavaScript 1</DisplayName> <Properties> <Property name="propName">propertyValue</Property> </Properties> <SSLInfo> <Enabled>trueFalse</Enabled> <ClientAuthEnabled>trueFalse</ClientAuthEnabled> <KeyStore>ref://keystoreRef</KeyStore> <KeyAlias>keyAlias</KeyAlias> <TrustStore>ref://truststoreRef</TrustStore> </SSLInfo> <IncludeURL>jsc://a-javascript-library-file</IncludeURL> <ResourceURL>jsc://my-javascript-source-file</ResourceURL> <Source>insert_js_code_here</Source> </Javascript>
Atribut <Javascript>
<Javascript name="Javascript-1" enabled="true" continueOnError="false" async="false" timeLimit="200">
Atribut berikut khusus untuk kebijakan ini.
Atribut | Deskripsi | Default | Kehadiran |
---|---|---|---|
timeLimit |
Menentukan waktu maksimum (dalam milidetik) yang diizinkan untuk
mengeksekusi skrip. Misalnya, jika batas 200 milidetik terlampaui, kebijakan akan menampilkan error ini:
|
T/A | Diperlukan |
Tabel berikut menjelaskan atribut yang sama untuk semua elemen induk kebijakan:
Atribut | Deskripsi | Default | Kehadiran |
---|---|---|---|
name |
Nama internal kebijakan. Nilai atribut Atau, gunakan elemen |
T/A | Diperlukan |
continueOnError |
Setel ke Setel ke |
false | Opsional |
enabled |
Setel ke Setel ke |
true | Opsional |
async |
Atribut ini sudah tidak digunakan lagi. |
false | Tidak digunakan lagi |
Elemen <DisplayName>
Gunakan selain atribut name
untuk memberi label kebijakan di
editor proxy UI pengelolaan dengan nama natural-language yang berbeda.
<DisplayName>Policy Display Name</DisplayName>
Default |
T/A Jika Anda menghapus elemen ini, nilai atribut |
---|---|
Kehadiran | Opsional |
Jenis | String |
Elemen <IncludeURL>
Menentukan file library JavaScript yang akan dimuat sebagai dependensi pada file JavaScript utama
yang ditentukan dengan elemen <ResourceURL>
atau <Source>
. Skrip akan dievaluasi sesuai urutan yang tercantum dalam kebijakan. Kode Anda dapat menggunakan objek, metode, dan
properti dari model objek JavaScript.
Sertakan lebih dari satu resource dependensi JavaScript dengan elemen
<IncludeURL>
tambahan.
<IncludeURL>jsc://my-javascript-dependency.js</IncludeURL>
Default: | Tidak ada |
Kehadiran: | Opsional |
Jenis: | String |
Contoh
Lihat Contoh Dasar di bagian Sample.
Elemen <Property>
Menentukan properti yang dapat Anda akses dari kode JavaScript saat runtime.
<Properties> <Property name="propName">propertyValue</Property> </Properties>
Default: | Tidak ada |
Kehadiran: | Opsional |
Jenis: | String |
Atribut
Atribut | Deskripsi | Default | Kehadiran |
---|---|---|---|
name |
Menentukan nama properti. |
T/A | Wajib. |
Contoh
Lihat contohnya di bagian Sample.
Elemen <ResourceURL>
Menentukan file JavaScript utama yang akan dijalankan di alur API. Anda dapat menyimpan file ini
di cakupan proxy API (di bagian /apiproxy/resources/jsc
di paket proxy API atau di
bagian Skrip pada panel Navigator editor proxy API), atau di cakupan organisasi atau
lingkungan untuk digunakan kembali di beberapa proxy API, seperti dijelaskan dalam Mengelola resource. Kode Anda dapat menggunakan objek,
metode, dan properti model objek JavaScript.
<ResourceURL>jsc://my-javascript.js</ResourceURL>
Default: | Tidak ada |
Kehadiran: | <ResourceURL> atau <Source> harus ada. Jika
<ResourceURL> dan <Source> ada, <ResourceURL> akan diabaikan. |
Jenis: | String |
Contoh
Lihat Contoh Dasar di bagian Sample.
Elemen <Source>
Memungkinkan Anda menyisipkan JavaScript secara langsung ke dalam konfigurasi XML kebijakan. Kode JavaScript yang dimasukkan akan dieksekusi saat kebijakan dieksekusi dalam alur API.
Default: | Tidak ada |
Kehadiran: | <ResourceURL> atau <Source> harus ada. Jika
<ResourceURL> dan <Source> ada, <ResourceURL> akan diabaikan. |
Jenis: | String |
Contoh
<Javascript name='JS-ParseJsonHeaderFullString' timeLimit='200' > <Properties> <Property name='inboundHeaderName'>specialheader</Property> <Property name='outboundVariableName'>json_stringified</Property> </Properties> <Source> var varname = 'request.header.' + properties.inboundHeaderName + '.values.string'; var h = context.getVariable(varname); if (h) { h = JSON.parse(h); h.augmented = (new Date()).valueOf(); var v = JSON.stringify(h, null, 2) + '\n'; // further indent var r = new RegExp('^(\S*)','mg'); v= v.replace(r,' $1'); context.setVariable(properties.outboundVariableName, v); } </Source> </Javascript>
Elemen <SSLInfo>
Menentukan properti yang digunakan untuk mengonfigurasi TLS untuk semua instance klien HTTP yang dibuat oleh kebijakan JavaScript.
<SSLInfo> <Enabled>trueFalse</Enabled> <ClientAuthEnabled>trueFalse</ClientAuthEnabled> <KeyStore>ref://keystoreRef</KeyStore> <KeyAlias>keyAlias</KeyAlias> <TrustStore>ref://truststoreRef</TrustStore> </SSLInfo>
Default: | Tidak ada |
Kehadiran: | Opsional |
Jenis: | String |
Proses konfigurasi TLS untuk klien HTTP sama dengan proses yang Anda gunakan untuk mengonfigurasi TLS untuk TargetEndpoint/TargetServer. Lihat Opsi untuk mengonfigurasi TLS untuk mengetahui informasi selengkapnya.
Catatan penggunaan
Proses debug kode kebijakan JavaScript
Gunakan fungsi print()
untuk menghasilkan informasi debug ke panel
output transaksi di Alat debug. Untuk mengetahui detail dan contohnya, lihat Debug dengan pernyataan
print()
JavaScript.
Untuk melihat pernyataan cetak di Debug:
- Buka alat Debug dan mulai sesi pelacakan untuk proxy yang berisi kebijakan JavaScript Anda.
- Memanggil proxy.
- Di Alat Debug, klik Output dari semua Transaksi untuk membuka panel output.
- Pernyataan cetak Anda akan muncul di panel ini.
Anda dapat menggunakan fungsi print()
untuk menghasilkan output informasi debug ke alat Debug. Fungsi ini tersedia langsung
melalui model objek JavaScript. Untuk mengetahui detailnya, lihat
Men-debug JavaScript dengan parameter print().
Variabel Alur
Kebijakan ini tidak mengisi variabel apa pun secara default. Namun, Anda dapat menetapkan (dan mendapatkan) variabel alur dalam kode JavaScript dengan memanggil metode pada objek konteks. Pola umumnya terlihat seperti ini:
context.setVariable("response.header.X-Apigee-Target", context.getVariable("target.name"))
Objek konteks adalah bagian dari model objek JavaScript Apigee.
Referensi error
Bagian ini menjelaskan kode kesalahan dan pesan error yang ditampilkan dan variabel kesalahan yang disetel oleh Apigee saat kebijakan ini memicu error. Informasi ini penting untuk diketahui apakah Anda mengembangkan aturan fault untuk menangani kesalahan. Untuk mempelajari lebih lanjut, lihat Yang perlu Anda ketahui tentang error kebijakan dan Menangani kesalahan.
Error runtime
Error ini dapat terjadi saat kebijakan dieksekusi.
Kode kesalahan | Status HTTP | Penyebab | Perbaikan |
---|---|---|---|
steps.javascript.ScriptExecutionFailed |
500 |
Kebijakan JavaScript dapat menampilkan berbagai jenis error ScriptExecutionFailed . Jenis error yang umum ditemui mencakup
RangeError,
ReferenceError,
SyntaxError,
TypeError, dan
URIError. |
build |
steps.javascript.ScriptExecutionFailedLineNumber |
500 |
Terjadi error di kode JavaScript . Lihat string fault untuk mengetahui detailnya. |
T/A |
steps.javascript.ScriptSecurityError |
500 |
Terjadi error keamanan saat JavaScript dieksekusi. Lihat string fault untuk mengetahui detailnya. |
T/A |
Error saat deployment
Error ini dapat terjadi saat Anda men-deploy proxy yang berisi kebijakan ini.
Nama error | Penyebab | Perbaikan |
---|---|---|
InvalidResourceUrlFormat |
Jika format URL resource yang ditentukan dalam elemen <ResourceURL> atau <IncludeURL> kebijakan JavaScript tidak valid, deployment proxy API akan gagal. |
build |
InvalidResourceUrlReference |
Jika elemen <ResourceURL> atau <IncludeURL>
merujuk ke file JavaScript yang tidak ada, deployment proxy API akan gagal.
File sumber yang direferensikan harus ada proxy API, lingkungan, atau tingkat organisasi. |
build |
WrongResourceType |
Error ini terjadi selama deployment jika elemen <ResourceURL> atau <IncludeURL> dari kebijakan JavaScript merujuk ke jenis resource apa pun selain jsc (file JavaScript ). |
build |
NoResourceURLOrSource |
Deployment kebijakan JavaScript dapat gagal dengan error ini jika elemen <ResourceURL> tidak dideklarasikan atau jika URL resource tidak ditentukan dalam elemen ini.
Elemen <ResourceURL> adalah elemen wajib. Atau, elemen <IncludeURL> dideklarasikan, tetapi URL resource tidak ditentukan dalam elemen ini. Elemen <IncludeURL> bersifat opsional,
tetapi jika dideklarasikan, URL resource harus ditentukan dalam elemen <IncludeURL> . |
build |
Variabel kesalahan
Variabel ini ditetapkan saat kebijakan ini memicu error saat runtime. Untuk informasi selengkapnya, lihat Yang perlu Anda ketahui tentang error kebijakan.
Variabel | Dari mana | Contoh |
---|---|---|
fault.name="fault_name" |
fault_name adalah nama kesalahan, seperti yang tercantum dalam tabel Error runtime di atas. Nama kesalahan adalah bagian terakhir dari kode kesalahan. | fault.name Matches "ScriptExecutionFailed" |
javascript.policy_name.failed |
policy_name adalah nama kebijakan yang ditentukan pengguna yang menampilkan kesalahan. | javascript.JavaScript-1.failed = true |
Contoh respons error
{ "fault": { "faultstring": "Execution of SetResponse failed with error: Javascript runtime error: "ReferenceError: "status" is not defined. (setresponse.js:6)\"", "detail": { "errorcode": "steps.javascript.ScriptExecutionFailed" } } }
Contoh aturan kesalahan
<FaultRule name="JavaScript Policy Faults"> <Step> <Name>AM-CustomErrorResponse</Name> <Condition>(fault.name Matches "ScriptExecutionFailed") </Condition> </Step> <Condition>(javascript.JavaScript-1.failed = true) </Condition> </FaultRule>
Skema
Setiap jenis kebijakan ditentukan oleh skema XML (.xsd
). Untuk referensi,
skema kebijakan
tersedia di GitHub.
Topik terkait
Artikel Komunitas Apigee
Anda dapat menemukan artikel terkait berikut di Komunitas Apigee: