Kebijakan JavaScript

Halaman ini berlaku untuk Apigee dan Apigee Hybrid.

Lihat 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 model objek JavaScript Apigee. Model objek memungkinkan Anda mendapatkan, menyetel, 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 mengetahui informasi tentang jenis kebijakan dan implikasi penggunaannya, lihat Jenis kebijakan.

Tentang

Ada banyak kasus penggunaan untuk kebijakan JavaScript. Misalnya, Anda dapat mengambil dan menyetel variabel alur, menjalankan logika kustom dan melakukan penanganan kesalahan, 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. Sebenarnya, Anda dapat menggunakan kebijakan JavaScript untuk mencapai banyak perilaku yang sama yang diterapkan oleh kebijakan lain, seperti AssignMessage dan ExtractVariable.

Salah satu kasus penggunaan yang tidak kami rekomendasikan untuk kebijakan JavaScript adalah logging. Kebijakan MessageLogging jauh lebih cocok untuk mencatat 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 dieksekusi atau Anda dapat menyertakan kode JavaScript langsung dalam konfigurasi kebijakan dengan elemen <Source>. Bagaimanapun juga, kode JavaScript dieksekusi saat langkah yang dilampiri 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 mendapatkan petunjuk, 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 menunjukkan 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 aliran, dan menggunakan variabel aliran tersebut di tempat lain dalam aliran 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 melakukannya dalam kebijakan JavaScript?

Catatan: Jika Anda ingin mencoba contoh ini, kami mengasumsikan 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 Develop.
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. Digunakan untuk mendapatkan konstanta khusus alur, 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 bawaan baca/tulis yang dapat diakses dalam alur Permintaan Target. Saat kita menetapkan variabel tersebut dengan URL API, Apigee melakukan panggilan backend ke URL tersebut. Pada dasarnya, kita telah menulis ulang URL target asli, yaitu 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);
   }
6. Dari menu Kebijakan Baru, pilih JavaScript.
7. Beri nama kebijakan, seperti target-rewrite. Terima setelan default, lalu simpan kebijakan.
8. Jika Anda memilih Proxy Endpoint Preflow di Navigator, Anda akan melihat bahwa kebijakan telah ditambahkan ke alur tersebut.
9. Di Navigator, pilih ikon Target Endpoint PreFlow.
10. Dari Navigator, tarik kebijakan JavaScript ke sisi Permintaan Target Endpoint di editor alur.
11. Simpan.
12. Panggil API seperti ini, dengan mengganti nama org 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

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

• Konfigurasi properti. Di sini, nilai propertinya 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 teknik penanganan error yang dapat Anda gunakan dalam panggilan JavaScript, lihat Cara yang benar untuk menampilkan error dari kebijakan JavaScript. Saran yang diberikan di Komunitas Apigee hanya untuk 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 eksekusi skrip. Misalnya, jika batas 200 md terlampaui, kebijakan akan memunculkan 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

The following table describes attributes that are common to all policy parent elements:

Attribute	Description	Default	Presence
name	The internal name of the policy. The value of the name attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters. Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.	N/A	Required
continueOnError	Set to false to return an error when a policy fails. This is expected behavior for most policies. Set to true to have flow execution continue even after a policy fails. See also: Fault rules are triggered ONLY in an error state (about continueOnError) Handling faults within the current flow	false	Optional
enabled	Set to true to enforce the policy. Set to false to turn off the policy. The policy will not be enforced even if it remains attached to a flow.	true	Optional
async	This attribute is deprecated.	false	Deprecated

<DisplayName> element

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, natural-language name.

<DisplayName>Policy Display Name</DisplayName>

Default	N/A If you omit this element, the value of the policy's name attribute is used.
Presence	Optional
Type	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 pencantumannya 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 proxy atau lingkungan, pastikan file tersebut diupload 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

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 di 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 disisipkan 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 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: operasi baca atau tulis sistem file internal, atau mendapatkan info pengguna saat ini, daftar proses, atau pemakaian CPU/memori. Meskipun beberapa panggilan tersebut mungkin berfungsi, panggilan tersebut tidak didukung dan dapat dinonaktifkan secara aktif kapan saja. Untuk kompatibilitas ke depan, Anda sebaiknya menghindari membuat 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 pernyataan Debug dengan JavaScript print().

Untuk melihat pernyataan cetak di Debug:

1. Buka alat Debug dan mulai sesi rekaman aktivitas 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 menyetel (dan mendapatkan) variabel alur dalam kode JavaScript dengan memanggil metode pada objek konteks. Pola umum 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

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.

Tip: Need help resolving an error? Click in the Fix column for detailed troubleshooting information.

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.

Tip: Need help resolving an error? Click next to the error's cause description to visit the troubleshooting page.

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:

• Bagaimana cara menangani header multi-nilai di JavaScript?