Kebijakan JavaScript

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Lihat dokumentasi Apigee Edge.

Apa

Kebijakan ini memungkinkan Anda menambahkan kode JavaScript kustom yang dieksekusi dalam konteks alur proxy API. Dalam kode JavaScript kustom, Anda dapat menggunakan objek, metode, dan properti 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 adalah Kebijakan yang dapat diperluas dan penggunaan kebijakan ini mungkin memiliki implikasi biaya atau penggunaan, bergantung pada lisensi Apigee Anda. Untuk informasi tentang jenis kebijakan dan implikasi penggunaan, lihat Jenis kebijakan.

Tentang

Ada banyak kasus penggunaan untuk kebijakan JavaScript. Misalnya, Anda dapat mendapatkan dan menetapkan variabel alur, menjalankan logika kustom dan melakukan penanganan error, 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 yang diterapkan oleh kebijakan lain, seperti AssignMessage 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 untuk dieksekusi atau Anda dapat menyertakan kode JavaScript langsung dalam konfigurasi kebijakan dengan elemen <Source>. Apa pun itu, kode JavaScript akan dieksekusi saat langkah yang dilampirkan kebijakan dieksekusi. 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 tingkat 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 di mesin JavaScript Rhino 1.7.13.

Video

Catatan: Video berikut menampilkan Editor Proxy klasik di UI Apigee. Apigee memperkenalkan versi baru Editor Proxy, yang memiliki desain berbeda dari versi klasik yang ditampilkan dalam video.

Tonton video singkat untuk mempelajari cara membuat ekstensi kebijakan kustom menggunakan kebijakan JavaScript.

Sampel

Menulis ulang URL target

Berikut adalah kasus penggunaan umum: mengekstrak data dari isi permintaan, menyimpannya dalam variabel flow, dan menggunakan variabel flow tersebut di tempat lain dalam flow proxy. Misalnya, Anda memiliki aplikasi tempat pengguna memasukkan namanya 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 Anda akan melakukannya dalam kebijakan JavaScript?

Catatan: Jika Anda ingin mencoba contoh ini, kami mengasumsikan bahwa Anda telah membuat proxy baru di editor proxy. Saat membuatnya, cukup berikan URL layanan backend: http://www.example.com. Untuk contoh ini, kita akan menulis ulang URL backend secara dinamis. Jika Anda tidak tahu cara membuat proxy baru, lihat tutorial memulai.

1. Di UI Apigee, buka proxy yang Anda buat di editor proxy.
2. Pilih tab Mengembangkan.
3. Dari menu Baru, pilih Skrip Baru.
4. Dalam dialog, pilih JavaScript dan beri nama skrip, seperti js-example.
5. Tempelkan kode berikut di editor kode dan simpan proxy. Hal penting yang perlu diperhatikan adalah objek context. Objek ini tersedia untuk kode JavaScript di mana saja dalam alur proxy. Class ini digunakan untuk mendapatkan konstanta khusus alur, untuk memanggil metode get/set yang berguna, dan untuk operasi lainnya. Bagian objek ini adalah bagian dari model objek JavaScript Apigee. Perhatikan juga bahwa variabel alur target.url adalah variabel baca/tulis bawaan yang dapat diakses dalam alur Permintaan Target. 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, yang merupakan URL 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);
   }
6. Dari menu Kebijakan Baru, pilih JavaScript.
7. Beri nama kebijakan, seperti target-rewrite. Setujui setelan default, lalu simpan kebijakan.
8. Jika memilih Pra-Alur Endpoint Proxy di Navigator, Anda akan melihat bahwa kebijakan tersebut telah ditambahkan ke alur tersebut.
9. Di Navigator, pilih ikon Target Endpoint PreFlow.
10. Dari Navigator, tarik kebijakan JavaScript ke sisi Permintaan di Endpoint Target di editor alur.
11. Simpan.
12. Panggil API seperti ini, dengan mengganti nama organisasi dan nama proxy 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 elemen <ResourceURL> digunakan untuk menentukan file sumber JavaScript yang akan dieksekusi. Pola yang sama ini digunakan untuk file sumber JavaScript apa pun: jsc://filename.js. Jika kode JavaScript Anda memerlukan penyertaan, Anda dapat menggunakan satu atau beberapa elemen <IncludeURL> untuk melakukannya, seperti yang 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 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 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 error yang dapat Anda gunakan dalam info JavaScript, lihat Cara yang benar untuk menampilkan error dari kebijakan JavaScript. Saran yang ditawarkan di Komunitas Apigee hanya ditujukan sebagai informasi dan tidak selalu mewakili praktik terbaik yang direkomendasikan oleh Google.

Dalam kebijakan JavaScript, mengakses request.content.asJSON dalam kapasitas hanya baca menyebabkan bilangan bulat besar dikonversi menjadi notasi eksponensial dalam isi pesan. Akibatnya, pesan akan ditimpa dengan nilai yang dikonversi.

---

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 dieksekusi oleh skrip. Misalnya, jika batas 200 md terlampaui, kebijakan akan menampilkan error ini: Javascript.policy_name failed with error: Javascript runtime exceeded limit of 200ms. 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	Kehadiran
name	Nama internal kebijakan. Nilai atribut name dapat berisi huruf, angka, spasi, tanda hubung, garis bawah, dan titik. Nilai ini tidak boleh melebihi 255 karakter. Secara opsional, gunakan elemen <DisplayName> untuk memberi label pada kebijakan di editor proxy UI pengelolaan dengan nama bahasa alami yang berbeda.	T/A	Wajib
continueOnError	Tetapkan ke false untuk menampilkan error saat kebijakan gagal. Perilaku ini wajar terjadi untuk sebagian besar kebijakan. Tetapkan ke true agar eksekusi alur berlanjut meskipun setelah kebijakan gagal. Lihat juga: Aturan error HANYA dipicu dalam status error (tentang continueOnError) Menangani error dalam alur saat ini	false	Opsional
enabled	Tetapkan ke true untuk menerapkan kebijakan. Tetapkan ke false untuk menonaktifkan kebijakan. Kebijakan tidak akan diterapkan meskipun tetap terlampir ke alur.	benar	Opsional
async	Atribut ini tidak digunakan lagi.	false	Tidak digunakan lagi

Elemen <DisplayName>

Gunakan selain atribut name untuk melabeli kebijakan di editor proxy UI pengelolaan dengan nama bahasa alami yang berbeda.

<DisplayName>Policy Display Name</DisplayName>

Default	T/A Jika Anda menghapus elemen ini, nilai atribut name kebijakan akan digunakan.
Kehadiran	Opsional
Jenis	String

Elemen <IncludeURL>

Menentukan file library JavaScript yang akan dimuat sebagai dependensi ke 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 model objek JavaScript.

Sertakan lebih dari satu resource dependensi JavaScript dengan elemen <IncludeURL> tambahan.

Peringatan: Jika file JavaScript Anda disimpan di tingkat organisasi atau lingkungan, pastikan file tersebut diupload dengan benar menggunakan cURL menggunakan opsi -F atau sebagai lampiran file melalui klien REST. Content-Type adalah multipart/form-data. Untuk mengetahui informasi selengkapnya, lihat Mengelola resource.

<IncludeURL>jsc://my-javascript-dependency.js</IncludeURL>

Default:	Tidak ada
Kehadiran:	Opsional
Jenis:	String

Contoh

Lihat Contoh Dasar di bagian Contoh.

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
nama	Menentukan nama properti.	T/A	Wajib.

Contoh

Lihat contoh di bagian Contoh.

Elemen <ResourceURL>

Menentukan file JavaScript utama yang akan dieksekusi dalam alur API. Anda dapat menyimpan file ini di cakupan proxy API (di bagian /apiproxy/resources/jsc dalam 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 yang 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 Contoh.

Elemen <Source>

Memungkinkan Anda menyisipkan JavaScript langsung ke konfigurasi XML kebijakan. Kode JavaScript yang dimasukkan akan dijalankan saat kebijakan dijalankan 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 mengonfigurasi TLS untuk klien HTTP adalah proses yang sama dengan yang Anda gunakan untuk mengonfigurasi TLS untuk TargetEndpoint/TargetServer. Lihat Opsi untuk mengonfigurasi TLS untuk informasi selengkapnya.

Catatan penggunaan

Peringatan: Panggilan sistem tidak diizinkan oleh model keamanan. Misalnya: sistem file internal membaca atau menulis, atau mendapatkan info pengguna saat ini, daftar proses, atau penggunaan CPU/memori. Meskipun beberapa panggilan tersebut mungkin berfungsi, panggilan tersebut tidak didukung dan dapat dinonaktifkan secara aktif kapan saja. Untuk kompatibilitas ke depan, Anda harus menghindari panggilan tersebut dalam kode Anda.

Men-debug kode kebijakan JavaScript

Gunakan fungsi print() untuk menampilkan 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:

1. Buka Alat debug dan mulai sesi pelacakan untuk proxy yang berisi kebijakan JavaScript Anda.
2. Panggil proxy.
3. Di Alat Debug, klik Output dari semua Transaksi untuk membuka panel output.

   

4. Pernyataan cetak Anda akan muncul di panel ini.

Anda dapat menggunakan fungsi print() untuk menampilkan informasi debug ke Alat debug. Fungsi ini tersedia langsung melalui model objek JavaScript. Untuk mengetahui detailnya, lihat Men-debug JavaScript dengan pernyataan 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 standar 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 error dan pesan error yang ditampilkan serta variabel error yang ditetapkan oleh Apigee saat kebijakan ini memicu error. Informasi ini penting untuk diketahui jika Anda mengembangkan aturan error untuk menangani error. Untuk mempelajari lebih lanjut, lihat Yang perlu Anda ketahui tentang error kebijakan dan Menangani error.

Error runtime

Error ini dapat terjadi saat kebijakan dieksekusi.

Tips: Perlu bantuan untuk mengatasi error? Klik di kolom Perbaiki untuk mendapatkan informasi pemecahan masalah mendetail.

Kode kerusakan	Status HTTP	Penyebab	Perbaiki
steps.javascript.ScriptExecutionFailed	500	Kebijakan JavaScript dapat menampilkan berbagai jenis error ScriptExecutionFailed. Jenis error yang biasa dilihat meliputi RangeError, ReferenceError, SyntaxError, TypeError, dan URIError.
steps.javascript.ScriptExecutionFailedLineNumber	500	Terjadi error pada kode JavaScript. Lihat string error untuk mengetahui detailnya.	T/A
steps.javascript.ScriptSecurityError	500	Terjadi error keamanan saat JavaScript dieksekusi. Lihat string error untuk mengetahui detailnya.	T/A

Error saat deployment

Error ini dapat terjadi saat Anda men-deploy proxy yang berisi kebijakan ini.

Tips: Perlu bantuan untuk mengatasi error? Klik di samping deskripsi penyebab error untuk membuka halaman pemecahan masalah.

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.
InvalidResourceUrlReference	Jika elemen <ResourceURL> atau <IncludeURL> merujuk ke file JavaScript yang tidak ada, deployment proxy API akan gagal. File sumber yang dirujuk harus ada di tingkat proxy, lingkungan, atau organisasi API.
WrongResourceType	Error ini terjadi selama deployment jika elemen <ResourceURL> atau <IncludeURL> dari kebijakan JavaScript merujuk ke jenis resource selain jsc (file JavaScript).
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>.

Variabel error

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 error, seperti yang tercantum dalam tabel Runtime errors di atas. Nama error adalah bagian terakhir dari kode error.	fault.name Matches "ScriptExecutionFailed"
javascript.policy_name.failed	policy_name adalah nama kebijakan yang ditentukan pengguna yang menampilkan error.	javascript.JavaScript-1.failed = true

Contoh respons error

Catatan: Untuk penanganan error, praktik terbaiknya adalah menangkap bagian errorcode dari respons error. Jangan mengandalkan teks di faultstring, karena teks tersebut dapat berubah.

{
  "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 error

<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

Artikel Komunitas Apigee

Anda dapat menemukan artikel terkait ini di Komunitas Apigee:

• Bagaimana cara menangani header multi-nilai di JavaScript?