Anda sedang melihat dokumentasi Apigee Edge.
Buka
Dokumentasi Apigee X. info
Apa
Kebijakan ini memungkinkan Anda menambahkan kode JavaScript kustom yang dijalankan dalam konteks API alur proxy. Di kode JavaScript khusus, Anda bisa menggunakan objek, metode, dan properti dari model objek JavaScript Apigee Edge. Model objek memungkinkan Anda mendapatkan, variabel dalam konteks alur proxy. Anda juga dapat menggunakan fungsi kriptografi dasar yang disediakan bersama model objek.
Tentang
Ada banyak kasus penggunaan untuk kebijakan JavaScript. Misalnya, Anda bisa mendapatkan dan mengatur alur variabel, mengeksekusi logika khusus dan melakukan penanganan kesalahan, mengekstrak data dari permintaan atau mengedit URL target backend secara dinamis, dan masih banyak lagi. Kebijakan ini memungkinkan Anda menerapkan perilaku khusus yang tidak tercakup oleh kebijakan Edge standar lainnya. Faktanya, Anda dapat menggunakan kebijakan JavaScript untuk mencapai banyak perilaku yang sama yang diterapkan oleh kebijakan lainnya, seperti MenetapkanMessage dan ExtractVariable.
Satu kasus penggunaan yang tidak kami rekomendasikan untuk kebijakan JavaScript adalah logging. Kebijakan Logging Pesan lebih cocok untuk logging ke platform {i>logging<i} pihak ketiga seperti Splunk, Sumo, dan Loggly, serta Anda meningkatkan kinerja proxy API dengan menjalankan kebijakan {i>Message Logging<i} di PostClientFlow, yang dijalankan setelah respons dikirim kembali ke klien.
Kebijakan JavaScript memungkinkan Anda menentukan file sumber JavaScript yang akan dieksekusi atau
Anda dapat menyertakan kode JavaScript langsung di konfigurasi kebijakan dengan <Source>
.
Apa pun pilihan Anda, kode JavaScript akan dijalankan saat langkah yang melampirkan kebijakan dijalankan.
Untuk opsi {i>source file<i}, kode sumber selalu disimpan dalam
lokasi standar dalam paket proxy: apiproxy/resources/jsc
. Atau, Anda juga bisa
menyimpan kode sumber dalam file sumber
daya di tingkat lingkungan atau organisasi. Sebagai
lihat petunjuk File resource. Anda dapat
upload JavaScript melalui editor proxy UI Apigee.
File sumber JavaScript harus selalu memiliki ekstensi .js
.
Lihat Software yang didukung dan versi yang didukung untuk versi JavaScript yang saat ini didukung.
Video
Tonton video singkat untuk mempelajari cara membuat ekstensi kebijakan kustom menggunakan JavaScript lebih lanjut.
Contoh
Menulis ulang URL target
Berikut ini kasus penggunaan umum: mengekstrak data dari isi permintaan, menyimpannya dalam flow variabel alur, dan menggunakan variabel alur tersebut di tempat lain dalam alur proxy. Katakanlah Anda memiliki aplikasi tempat pengguna memasukkan nama mereka di formulir HTML dan mengirimkannya. Anda ingin proxy API mengekstrak data formulir dan menambahkannya secara dinamis ke URL yang digunakan untuk memanggil layanan backend. Cara apakah Anda akan melakukannya di kebijakan JavsScript?
Catatan: Jika ingin mencoba contoh ini, kami asumsikan Anda telah membuat {i>proxy<i} di editor {i>proxy<i}. Saat Anda membuatnya, cukup berikan URL layanan backend: http://www.contoh.com. Untuk contoh ini, kita akan menulis ulang URL backend secara dinamis. Jika Anda tidak mengetahui cara membuat proxy baru, lihat tutorial memulai. .
- Di UI Edge, buka proxy yang Anda buat di editor proxy.
- Pilih tab Develop.
- Dari menu Baru, pilih Skrip Baru.
- Dalam dialog, pilih JavaScript dan beri nama skrip, seperti
js-example
. - Tempel kode berikut di editor kode dan simpan proxy. Hal yang
penting untuk
adalah objek
context
. Objek ini tersedia untuk kode JavaScript di mana saja dalam alur {i>proxy<i}. Ini digunakan untuk mendapatkan konstanta spesifik per alur, untuk memanggil metode get/set, dan untuk operasi lainnya. Bagian objek ini adalah milik Edge model objek JavaScript. Catatan: juga, variabel flowtarget.url
adalah variabel bawaan, baca/tulis yang dapat diakses dalam alur Permintaan Target. Ketika kita mengatur variabel itu dengan URL API, Edge melakukan panggilan backend ke URL tersebut. Pada dasarnya kita telah menulis ulang URL target, yaitu apa pun yang Anda tentukan saat membuat proxy (misalnya, http://www.contoh.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 New Policy, pilih JavaScript.
- Beri nama kebijakan tersebut, seperti
target-rewrite
. Setujui setelan default, lalu simpan kebijakan tersebut. - Jika memilih Preflow Endpoint Proxy di Navigator, Anda akan melihat bahwa kebijakan ditambahkan ke alur tersebut.
- Di Navigator, pilih ikon Target Endpoint PreFlow.
- Dari Navigator, seret kebijakan JavaScript ke sisi Permintaan Target Endpoint di editor alur.
- Simpan.
- Panggil API seperti ini, dengan mengganti nama organisasi dan nama proxy Anda yang benar dengan sesuai:
curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST -d 'user=Will' http://myorg-test.apigee.net/js-example
Terakhir, mari kita lihat definisi XML
untuk kebijakan JavaScript yang digunakan di
pada contoh ini. Hal penting yang perlu diperhatikan adalah <ResourceURL>
digunakan untuk menentukan file sumber JavaScript yang akan dieksekusi. Pola yang
sama ini digunakan
untuk setiap file sumber JavaScript: jsc://filename.js
. Jika Anda menggunakan kode JavaScript
memerlukan penyertaan, Anda dapat menggunakan satu atau lebih elemen <IncludeURL>
untuk
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 dengan JavaScript pada saat runtime.
Gunakan atribut name
elemen untuk menentukan nama yang akan digunakan untuk mengakses
dari kode JavaScript. Nilai elemen <Property>
(nilainya)
antara tag pembuka dan penutup) adalah nilai literal yang akan diterima oleh
pada JavaScript.
Di JavaScript, Anda mengambil nilai properti kebijakan dengan mengaksesnya sebagai properti
Properties
, seperti dalam contoh 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 diskusi tentang teknik penanganan kesalahan yang dapat Anda gunakan dalam Info JavaScript, lihat postingan ini di Komunitas Apigee. Saran yang ditawarkan di Komunitas Apigee adalah untuk informasi saja dan tidak selalu merepresentasikan praktik terbaik yang direkomendasikan oleh Apigee.
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>
<Javascript> Atribut
<Javascript name="Javascript-1" enabled="true" continueOnError="false" async="false" timeLimit="200">
Atribut berikut khusus untuk kebijakan ini.
Atribut | Deskripsi | Default | Ketersediaan |
---|---|---|---|
timeLimit |
Menentukan waktu maksimum (dalam milidetik) yang diizinkan untuk skrip
mengeksekusi. Misalnya, jika batas 200 md terlampaui, kebijakan akan menampilkan error ini:
Catatan: Untuk akun uji coba gratis, waktu eksekusi dibatasi hingga 200 md. |
T/A | Wajib |
Tabel berikut menjelaskan atribut yang umum untuk semua elemen induk kebijakan:
Atribut | Deskripsi | Default | Ketersediaan |
---|---|---|---|
name |
Nama internal kebijakan. Nilai atribut Secara opsional, gunakan elemen |
T/A | Wajib |
continueOnError |
Tetapkan ke Setel ke |
salah | Opsional |
enabled |
Setel ke Setel ke |
true | Opsional |
async |
Atribut ini tidak digunakan lagi. |
salah | Tidak digunakan lagi |
<DisplayName> elemen
Gunakan selain atribut name
untuk memberi label kebijakan di
editor proxy UI dengan nama natural language yang berbeda.
<DisplayName>Policy Display Name</DisplayName>
Default |
T/A Jika Anda menghapus elemen ini, nilai atribut |
---|---|
Ketersediaan | Opsional |
Jenis | String |
<IncludeURL> elemen
Menentukan file library JavaScript yang akan dimuat sebagai dependensi ke file JavaScript utama
ditentukan dengan elemen <ResourceURL>
atau <Source>
. Skrip akan dievaluasi dalam
dengan urutan yang tercantum dalam kebijakan. Kode Anda bisa menggunakan objek, metode, dan
properti model objek JavaScript.
Sertakan lebih dari satu resource dependensi JavaScript dengan
Elemen <IncludeURL>
.
<IncludeURL>jsc://my-javascript-dependency.js</IncludeURL>
Default: | Tidak ada |
Kehadiran: | Opsional |
Jenis: | String |
Contoh
Lihat Contoh Dasar di bagian Sampel.
<Property> elemen
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 | Ketersediaan |
---|---|---|---|
nama |
Menentukan nama properti. |
T/A | Wajib diisi. |
Contoh
Lihat contoh di bagian Contoh.
<ResourceURL> elemen
Menentukan file JavaScript utama yang akan dieksekusi dalam alur API. Anda dapat menyimpan file ini
pada cakupan proxy API (pada /apiproxy/resources/jsc
dalam paket proxy API atau di
bagian Skrip di panel Navigator editor proxy API), atau di organisasi,
cakupan lingkungan untuk digunakan kembali di beberapa proxy API, seperti yang dijelaskan dalam File resource. Kode Anda bisa menggunakan objek,
metode, dan properti model objek JavaScript.
<ResourceURL>jsc://my-javascript.js</ResourceURL>
Default: | Tidak ada |
Kehadiran: | <ResourceURL> atau <Source> wajib diisi. Jika
<ResourceURL> dan <Source> sama-sama ada <ResourceURL> akan diabaikan. |
Jenis: | String |
Contoh
Lihat Contoh Dasar di bagian Sampel.
<Source> elemen
Memungkinkan Anda menyisipkan JavaScript langsung ke konfigurasi XML kebijakan. Elemen yang disisipkan Kode JavaScript dijalankan saat kebijakan dieksekusi dalam alur API.
Default: | Tidak ada |
Kehadiran: | <ResourceURL> atau <Source> wajib diisi. Jika
<ResourceURL> dan <Source> sama-sama 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>
<SSLInfo> elemen
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 adalah proses yang sama dengan yang Anda gunakan untuk mengkonfigurasi TLS untuk TargetEndpoint/TargetServer. Lihat Mengonfigurasi TLS dari Edge ke backend untuk informasi selengkapnya.
Catatan penggunaan
Kebijakan JavaScript tidak berisi kode aktual. Sebagai gantinya, kebijakan JavaScript mereferensikan
'Resource' JavaScript dan menentukan Langkah dalam alur API tempat JavaScript dieksekusi. Anda dapat
upload skrip Anda melalui editor proxy UI Pengelolaan, atau Anda dapat menyertakannya dalam
Direktori /resources/jsc
di proxy API yang Anda kembangkan secara lokal.
Proses debug kode kebijakan JavaScript
Gunakan fungsi print() untuk menampilkan informasi debug pada transaksi panel output di Trace Tool. Untuk mengetahui detail dan contohnya, lihat Debug dengan JavaScript print().
Untuk melihat pernyataan cetak di Trace:
- Buka Alat Pelacakan dan mulai sesi pelacakan untuk proxy yang berisi JavaScript Anda lebih lanjut.
- Panggil proxy.
- Di Alat Rekaman Aktivitas, klik Output dari semua Transaksi untuk membuka output .
- Pernyataan cetak Anda akan muncul di panel ini.
Anda dapat menggunakan fungsi print() untuk menampilkan informasi debug ke alat Trace. Fungsi ini tersedia secara langsung melalui model objek JavaScript. Untuk mengetahui detailnya, lihat "Men-debug JavaScript dengan print() ".
Variabel Alur
Kebijakan ini tidak mengisi variabel apa pun secara default; Namun, Anda dapat mengatur (dan mendapatkan) alur variabel dalam kode JavaScript Anda dengan memanggil metode pada objek konteks. Pola umum akan terlihat seperti ini:
context.setVariable("response.header.X-Apigee-Target", context.getVariable("target.name"))
Objek konteks adalah bagian dari model objek JavaScript Apigee Edge.
Referensi error
Bagian ini menjelaskan kode kesalahan dan pesan error yang ditampilkan serta variabel kesalahan yang disetel oleh Edge saat kebijakan ini memicu error. Informasi ini penting untuk diketahui jika Anda mengembangkan aturan kesalahan untuk menangani kesalahan. Untuk mempelajari lebih lanjut, lihat Yang perlu Anda ketahui tentang error kebijakan dan Penanganan kesalahan.
Error runtime
Error ini dapat terjadi saat kebijakan dijalankan.
Kode error | Status HTTP | Penyebab | Perbaiki |
---|---|---|---|
steps.javascript.ScriptExecutionFailed |
500 | Kebijakan JavaScript dapat menampilkan berbagai jenis error ScriptExecutionFailed. Umumnya jenis kesalahan yang terlihat antara lain RangeError, ReferenceError, SyntaxError, TypeError, dan URIError. | build |
steps.javascript.ScriptExecutionFailedLineNumber |
500 | Terjadi error pada kode JavaScript. Lihat string kesalahan untuk detailnya. | T/A |
steps.javascript.ScriptSecurityError |
500 | Terjadi error keamanan saat JavaScript dieksekusi. Lihat string kesalahan untuk spesifikasi pendukung. | T/A |
Error saat deployment
Error ini dapat terjadi saat Anda men-deploy proxy yang berisi kebijakan ini.
Nama error | Penyebab | Perbaiki |
---|---|---|
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, berarti deployment proxy API akan gagal.
File sumber yang direferensikan harus ada di tingkat organisasi, lingkungan, atau proxy API. |
build |
WrongResourceType |
Error ini terjadi selama deployment jika <ResourceURL> atau <IncludeURL>
elemen kebijakan JavaScript merujuk ke jenis resource apa pun selain jsc (file JavaScript). |
build |
NoResourceURLOrSource |
Deployment kebijakan JavaScript dapat gagal dengan error ini jika <ResourceURL>
tidak dideklarasikan atau jika URL sumber daya tidak didefinisikan dalam elemen ini.
Elemen <ResourceURL> adalah elemen wajib. Atau, elemen <IncludeURL> dideklarasikan
namun URL resource tidak didefinisikan 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 Apa yang yang perlu diketahui tentang error kebijakan.
Variabel | Di 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
). Sebagai referensi, skema kebijakan
tersedia di GitHub.
Topik terkait
- Model objek JavaScript
- Untuk petunjuk, contoh kebijakan, dan contoh JavaScript, lihat Pemrograman API menggunakan proxy dengan JavaScript.
Artikel Komunitas Apigee
Anda dapat menemukan artikel terkait ini di Apigee Komunitas: