Kebijakan JavaScript

Kebijakan yang dapat diperluas

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 gangguan, mengekstrak data dari permintaan atau respons, dan mengedit URL target backend secara dinamis. Anda juga dapat menggunakan fungsi kriptografi dasar yang tersedia di 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 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 flow variable, lalu menggunakan flow variable 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.

  1. Di UI Apigee, buka proxy yang Anda buat di editor proxy.
  2. Pilih tab Develop.
  3. Dari menu Baru, pilih Skrip Baru.
  4. Dalam dialog, pilih JavaScript dan beri nama skrip js-example.
  5. 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);
}
  6. Dari menu Kebijakan Baru, pilih JavaScript.
  7. Beri nama kebijakan target-rewrite. Terima setelan default, lalu simpan kebijakan.
  8. Setelah Anda memilih Proxy Endpoint Preflow di Navigator, kebijakan ditambahkan ke alur tersebut.
  9. Di Navigator, pilih Target Endpoint PreFlow.
  10. Di Navigator, tarik kebijakan JavaScript ke sisi Permintaan Target Endpoint di editor alur.
  11. Simpan.
  12. Ganti nama organisasi dan nama proxy Anda 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);

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) skrip dapat dieksekusi. Misalnya, jika batas 200 md terlampaui, kebijakan akan menampilkan error ini: Javascript.policy_name failed with error: Javascript runtime exceeded limit of 200ms.

 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:

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

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

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

    Output dari tab Properties di alat Debug, yang menampilkan pernyataan cetak.

  4. Pernyataan cetak Anda akan 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

本部分介绍当此政策触发错误时返回的故障代码和错误消息，以及由 Apigee 设置的故障变量。在开发故障规则以处理故障时，请务必了解此信息。如需了解详情，请参阅您需要了解的有关政策错误的信息和处理故障。

运行时错误

政策执行时可能会发生这些错误。

故障代码 HTTP 状态 原因 修复
steps.javascript.ScriptExecutionFailed 500 JavaScript 政策可能会抛出许多不同类型的 ScriptExecutionFailed 错误。 常见的错误类型包括：RangeError、ReferenceError、SyntaxError、TypeError 和 URIError。
steps.javascript.ScriptExecutionFailedLineNumber 500 JavaScript 代码中出现错误。请参阅故障字符串了解详情。 不适用
steps.javascript.ScriptSecurityError 500 JavaScript 执行时出现安全错误。请参阅故障字符串了解详情。 不适用

部署错误

在您部署包含此政策的代理时，可能会发生这些错误。

错误名称 原因 修复
InvalidResourceUrlFormat 如果 JavaScript 政策的 <ResourceURL> 或 <IncludeURL> 元素中指定的资源网址格式无效，则 API 代理的部署将失败。
InvalidResourceUrlReference 如果 <ResourceURL> 或 <IncludeURL> 元素引用了不存在的 JavaScript 文件，则 API 代理的部署将失败。引用的源文件必须存在于 API 代理、环境或组织级别。
WrongResourceType 如果 JavaScript 政策的 <ResourceURL> 或 <IncludeURL> 元素引用除 jsc（JavaScript 文件）以外的任何资源类型，则会在部署期间出现此错误。
NoResourceURLOrSource 如果未声明 <ResourceURL> 元素或此元素内未定义资源网址，则 JavaScript 政策的部署可能会失败，并显示此错误。<ResourceURL> 元素是必需元素。或者，声明了 <IncludeURL> 元素，但未在此元素中定义资源网址。<IncludeURL> 元素是可选的，但如果声明，则必须在 <IncludeURL> 元素中指定资源网址。

故障变量

当此政策在运行时触发错误时，将设置这些变量。如需了解详情，请参阅您需要了解的有关政策错误的信息。

变量 其中 示例
fault.name="fault_name" fault_name 是故障名称，如上面的运行时错误表中所列。故障名称是故障代码的最后一部分。 fault.name Matches "ScriptExecutionFailed"
javascript.policy_name.failed policy_name 是抛出故障的政策的用户指定名称。 javascript.JavaScript-1.failed = true

错误响应示例

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

故障规则示例

<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

Artikel Komunitas Apigee

Anda dapat menemukan artikel terkait ini di Komunitas Apigee: