Kebijakan JavaScript

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Lihat dokumentasi Apigee Edge.

Kebijakan JavaScript memungkinkan Anda menambahkan kode JavaScript kustom yang dieksekusi dalam konteks alur proxy API. Kebijakan ini memungkinkan Anda menerapkan perilaku kustom yang tidak dicakup oleh kebijakan Apigee.

Dalam kode JavaScript kustom, Anda dapat menggunakan objek, metode, dan properti model objek JavaScript Apigee. Anda dapat mengambil, menetapkan, dan menghapus variabel dalam konteks alur proxy, mengeksekusi logika kustom, melakukan penanganan kesalahan, mengekstrak data dari permintaan atau respons, dan mengedit URL target backend secara dinamis. Anda juga dapat menggunakan fungsi kriptografi dasar yang tersedia dalam model objek.

Kebijakan JavaScript memungkinkan Anda menentukan file sumber JavaScript yang akan dieksekusi, atau Anda dapat menyertakan kode JavaScript langsung dalam konfigurasi kebijakan menggunakan elemen <Source>. Bagaimanapun juga, kode JavaScript dieksekusi saat langkah tempat kebijakan dilampirkan dieksekusi.

Untuk opsi file sumber, kode sumber selalu disimpan di lokasi standar dalam paket proxy: apiproxy/resources/jsc. Atau, Anda dapat menyimpan kode sumber dalam file resource di tingkat lingkungan atau organisasi. Untuk mendapatkan petunjuk, lihat File resource. Anda juga dapat mengupload JavaScript menggunakan editor proxy UI Apigee.

File sumber JavaScript harus memiliki ekstensi .js. Apigee mendukung JavaScript yang berjalan di mesin JavaScript Rhino 1.7.13.

Apigee tidak merekomendasikan penggunaan kebijakan JavaScript untuk hal berikut:

Logging. Kebijakan MessageLogging lebih cocok untuk logging dengan platform logging pihak ketiga seperti Splunk, Sumo, dan Loggly. Kebijakan ini juga meningkatkan performa proxy API dengan dieksekusi di PostClientFlow setelah respons dikembalikan ke klien.
Mengganti kebijakan Apigee. Kebijakan JavaScript tidak menggantikan kemampuan kebijakan Apigee. Jika kemampuan yang Anda butuhkan tersedia dalam kebijakan Apigee, gunakan kebijakan tersebut, bukan menerapkan solusi JavaScript kustom. Kode JavaScript kustom mungkin tidak sesuai dengan performa dan pengoptimalan kebijakan Apigee.
Untuk melakukan panggilan sistem. Model keamanan tidak mengizinkan panggilan sistem dari kebijakan JavaScript. Misalnya, pembacaan atau penulisan sistem file internal, informasi pengguna saat ini, daftar proses, atau penggunaan CPU/memori tidak diizinkan. Meskipun beberapa panggilan mungkin berfungsi, panggilan tersebut tidak didukung dan dapat dinonaktifkan kapan saja. Untuk kompatibilitas maju, hindari melakukan panggilan ini dalam kode Anda.

Kebijakan ini adalah Extensible policy dan penggunaan kebijakan ini mungkin memiliki implikasi biaya atau penggunaan, bergantung pada lisensi Apigee Anda. Untuk mengetahui informasi tentang jenis kebijakan dan implikasi penggunaannya, lihat Jenis kebijakan.

Sampel

Menulis ulang URL target

Kasus penggunaan umum melibatkan ekstraksi data dari isi permintaan, menyimpannya dalam variabel alur, lalu menggunakan variabel alur tersebut di tempat lain dalam alur proxy. Misalnya, pengguna memasukkan namanya dalam formulir HTML dan mengirimkannya. Untuk mengekstrak data formulir dan menambahkannya secara dinamis ke URL layanan backend, gunakan kebijakan JavaScript.

Catatan: Untuk mencoba contoh ini, buat proxy baru di editor proxy. Saat membuat proxy, berikan URL layanan backend, misalnya, http://www.example.com. Contoh ini menulis ulang URL backend secara dinamis. Jika Anda perlu membuat proxy baru, lihat tutorial memulai.

Di UI Apigee, 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 js-example.
Tempelkan kode berikut di editor kode dan simpan proxy. Objek context tersedia untuk kode JavaScript di mana saja dalam alur proxy. Class ini mendapatkan konstanta khusus alur, memanggil metode get/set yang berguna, dan melakukan operasi lainnya. Objek ini adalah bagian dari model objek JavaScript Apigee. Variabel alur target.url adalah variabel bawaan baca/tulis yang dapat diakses dalam alur Permintaan Target. Saat Anda menyetel variabel tersebut dengan URL API, Apigee akan memanggil URL backend tersebut. Tindakan ini akan menulis ulang URL target asli, yaitu 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);
}
```
Dari menu Kebijakan Baru, pilih JavaScript.
Beri nama kebijakan target-rewrite. Terima setelan default, lalu simpan kebijakan.
Setelah Anda memilih Proxy Endpoint Preflow di Navigator, kebijakan ditambahkan ke alur tersebut.
Di Navigator, pilih Target Endpoint PreFlow.
Di Navigator, tarik kebijakan JavaScript ke sisi Permintaan Target Endpoint di editor alur.
Simpan.
Ganti nama organisasi dan nama proxy saat Anda memanggil API:

curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST -d 'user=Will' http://myorg-test.apigee.net/js-example

Periksa definisi XML untuk kebijakan JavaScript yang digunakan dalam contoh ini. Elemen <ResourceURL> menentukan file sumber JavaScript yang akan dieksekusi. Pola ini berlaku untuk semua file sumber JavaScript: jsc://filename.js. Jika kode JavaScript Anda memerlukan penyertaan, gunakan satu atau beberapa elemen <IncludeURL>, seperti yang dijelaskan nanti dalam dokumen 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 nilainya dengan JavaScript saat runtime.

Gunakan atribut name elemen untuk menentukan nama guna mengakses properti dari kode JavaScript. Nilai elemen <Property> (nilai antara tag pembuka dan penutup) adalah nilai literal yang diterima JavaScript.

Di JavaScript, Anda mengambil nilai properti kebijakan dengan mengaksesnya sebagai properti objek Properties, sebagai berikut:

Konfigurasi properti. 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 menggunakan JavaScript. Fungsi getVariable kemudian menggunakan nama variabel yang diambil 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);

Dalam kebijakan JavaScript, mengakses request.content.asJSON dalam mode hanya baca akan mengonversi bilangan bulat besar menjadi notasi eksponensial dalam isi pesan. Hal ini akan menggantikan pesan 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>

< languageVersion="VERSION_1_3" Javascript name="Javascript-1" enabled="true" continueOnError="false" async="false" timeLimit="200">

Atribut	Deskripsi	Default	Kehadiran
languageVersion	Menentukan versi bahasa JavaScript yang digunakan untuk menulis kode. Nilai mencakup `VERSION_DEFAULT`, `VERSION_1_0`, `VERSION_1_1`, `VERSION_1_2`, `VERSION_1_3`, `VERSION_1_4`, `VERSION_1_5`, `VERSION_1_6`, `VERSION_1_7`, `VERSION_1_8`, dan `VERSION_ES6`.	VERSION_DEFAULT	Opsional
timeLimit	Menentukan waktu maksimum (dalam milidetik) yang dapat dieksekusi 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

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

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 untuk file JavaScript utama yang ditentukan dengan elemen <ResourceURL> atau <Source>. Kebijakan mengevaluasi skrip dalam urutan yang tercantum dalam kebijakan. Kode Anda dapat menggunakan objek, metode, dan properti model objek JavaScript.

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

Peringatan: Jika file JavaScript Anda disimpan di tingkat proxy atau lingkungan, pastikan Anda menguploadnya dengan benar menggunakan cURL dengan 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

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 dijalankan dalam alur API. Anda dapat menyimpan file ini di cakupan proxy API (di bagian /apiproxy/resources/jsc dalam paket proxy API atau di bagian Scripts pada panel Navigator editor proxy API). Atau, simpan 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, kebijakan akan mengabaikan `<ResourceURL>`.
Jenis:	String

Contoh

Lihat contoh di bagian Contoh.

Elemen <Source>

Anda dapat menyisipkan JavaScript langsung ke konfigurasi XML kebijakan. Kode JavaScript yang disisipkan dieksekusi saat kebijakan dieksekusi dalam alur API.

Default:	Tidak ada
Kehadiran:	`<ResourceURL>` atau `<Source>` harus ada. Jika `<ResourceURL>` dan `<Source>` ada, kebijakan akan mengabaikan `<ResourceURL>`.
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 digunakan untuk mengonfigurasi TLS untuk TargetEndpoint/TargetServer. Lihat Opsi untuk mengonfigurasi TLS untuk mengetahui informasi selengkapnya.

Menggunakan JavaScript untuk menangani error

Anda dapat menggunakan kebijakan JavaScript untuk menangani dan menampilkan error. Untuk pembahasan tentang topik ini, lihat Cara yang benar untuk menampilkan error dari kebijakan JavaScript di Komunitas Apigee. Perhatikan bahwa postingan dan komentar komunitas tidak selalu mewakili praktik terbaik yang direkomendasikan oleh Apigee.

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 Men-debug JavaScript dengan pernyataan print().

Untuk melihat pernyataan cetak di alat Debug:

Buka alat Debug dan mulai sesi rekaman aktivitas untuk proxy yang berisi kebijakan JavaScript Anda.
Panggil proxy.
Di Debug Tool, klik kebijakan JavaScript, lalu tab Properties untuk melihat properti "stepExecution-stdout" yang menampilkan output pernyataan cetak.
Pernyataan cetak Anda muncul di panel ini.

Variabel Alur

Kebijakan ini tidak mengisi variabel apa pun secara default. Namun, Anda dapat menyetel dan mendapatkan variabel alur dalam kode JavaScript dengan memanggil metode pada objek context. Contoh:

context.setVariable("response.header.X-Apigee-Target", context.getVariable("target.name"))

Objek context adalah bagian dari model objek JavaScript Apigee.

Referensi error

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code	HTTP status	Cause	Fix
`steps.javascript.ScriptExecutionFailed`	`500`	The `JavaScript` policy can throw many different types of `ScriptExecutionFailed` errors. Commonly seen types of errors include RangeError, ReferenceError, SyntaxError, TypeError, and URIError.
`steps.javascript.ScriptExecutionFailedLineNumber`	`500`	An error occurred in the `JavaScript` code. See the fault string for details.	N/A
`steps.javascript.ScriptSecurityError`	`500`	A security error occurred when the `JavaScript` executed. See the fault string for details.	N/A

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name	Cause	Fix
`InvalidResourceUrlFormat`	If the format of the resource URL specified within the `<ResourceURL>` or the `<IncludeURL>` element of the `JavaScript` policy is invalid, then the deployment of the API proxy fails.
`InvalidResourceUrlReference`	If the `<ResourceURL>` or the `<IncludeURL>` elements refer to a `JavaScript` file that does not exist, then the deployment of the API proxy fails. The referenced source file must exist either the API proxy, environment, or organization level.
`WrongResourceType`	This error occurs during deployment if the `<ResourceURL>` or the `<IncludeURL>` elements of the `JavaScript` policy refer to any resource type other than jsc (`JavaScript` file).
`NoResourceURLOrSource`	The deployment of the `JavaScript` policy can fail with this error if the `<ResourceURL>` element is not declared or if the resource URL is not defined within this element. `<ResourceURL>` element is a mandatory element. Or, The `<IncludeURL>` element is declared but the resource URL is not defined within this element. The `<IncludeURL>` element is optional but if declared, the resource URL must be specified within the `<IncludeURL>` element.

Fault variables

These variables are set when this policy triggers an error at runtime. For more information, see What you need to know about policy errors.

Variables	Where	Example
`fault.name="fault_name"`	`fault_name` is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code.	`fault.name Matches "ScriptExecutionFailed"`
`javascript.policy_name.failed`	`policy_name` is the user-specified name of the policy that threw the fault.	`javascript.JavaScript-1.failed = true`

Example error response

Note: For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

{
  "fault": {
    "faultstring": "Execution of SetResponse failed with error: Javascript runtime error: "ReferenceError: "status" is not defined. (setresponse.js:6)\"",
    "detail": {
      "errorcode": "steps.javascript.ScriptExecutionFailed"
    }
  }
}

Example fault rule

<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:

Cara menangani header multi-nilai di JavaScript

Kebijakan JavaScript Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Sampel

Menulis ulang URL target

Mengambil nilai properti dari JavaScript

Referensi elemen

Atribut <Javascript>

Elemen <DisplayName>

Elemen <IncludeURL>

Elemen <Property>

Atribut

Contoh

Elemen <ResourceURL>

Contoh

Elemen <Source>

Contoh

Elemen <SSLInfo>

Menggunakan JavaScript untuk menangani error

Men-debug kode kebijakan JavaScript

Variabel Alur

Referensi error

Runtime errors

Deployment errors

Fault variables

Example error response

Example fault rule

Skema

Topik terkait

Artikel Komunitas Apigee

Kebijakan JavaScript