Halaman ini diterjemahkan oleh Cloud Translation API.

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

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.

File sumber JavaScript harus memiliki ekstensi .js.

Apigee mendukung JavaScript yang berjalan di mesin JavaScript Rhino 1.7.13.

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.

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. Objek 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 di 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);

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 di Komunitas Apigee hanya untuk tujuan informasi dan tidak selalu mewakili praktik terbaik yang direkomendasikan oleh Google.

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

Catatan penggunaan

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 Alat Debug, klik Output dari semua Transaksi untuk membuka panel output.
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

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.

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.

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

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

Menangani error

Referensi elemen

Atribut <Javascript>

Elemen <DisplayName>

Elemen <IncludeURL>

Elemen <Property>

Atribut

Contoh

Elemen <ResourceURL>

Contoh

Elemen <Source>

Contoh

Elemen <SSLInfo>

Catatan penggunaan

Men-debug kode kebijakan JavaScript

Variabel Alur

Referensi error

Error runtime

Error saat deployment

Variabel error

Contoh respons error

Contoh aturan error

Skema

Topik terkait

Artikel Komunitas Apigee

Kebijakan JavaScript