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 API alur proxy. Di kode JavaScript khusus, Anda bisa menggunakan objek, metode, dan properti dari model objek JavaScript Apigee. Model objek memungkinkan Anda mendapatkan, variabel dalam konteks alur proxy. Anda juga dapat menggunakan fungsi kriptografi dasar yang disediakan bersama model objek.

Kebijakan ini merupakan Kebijakan yang dapat diperluas dan penggunaan kebijakan ini dapat menimbulkan biaya atau implikasi penggunaan, bergantung pada lisensi Apigee Anda. Untuk mengetahui informasi tentang jenis kebijakan dan implikasi penggunaan, lihat Jenis kebijakan.

Tentang

Ada banyak kasus penggunaan untuk kebijakan JavaScript. Misalnya, Anda bisa mendapatkan dan mengatur alur variabel, mengeksekusi logika khusus dan melakukan penanganan kesalahan, mengekstrak data dari permintaan atau mengedit URL target backend secara dinamis, dan masih banyak lagi. Kebijakan ini memungkinkan Anda menerapkan perilaku kustom yang tidak tercakup dalam kebijakan Apigee standar lainnya. Faktanya, Anda dapat menggunakan kebijakan JavaScript untuk mencapai banyak perilaku yang sama yang diterapkan oleh kebijakan lainnya, seperti MenetapkanMessage dan ExtractVariable.

Satu kasus penggunaan yang tidak kami rekomendasikan untuk kebijakan JavaScript adalah logging. Tujuan Kebijakan MessageLogging jauh lebih cocok untuk logging ke platform {i>logging<i} pihak ketiga seperti Splunk, Sumo, dan Loggly, serta Anda meningkatkan kinerja proxy API dengan menjalankan kebijakan {i>MessageLogging<i} di {i>PostClientFlow<i}, 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 di konfigurasi kebijakan dengan <Source> . Apa pun pilihan Anda, kode JavaScript akan dijalankan saat langkah yang melampirkan kebijakan dijalankan. Untuk opsi {i>source file<i}, kode sumber selalu disimpan dalam lokasi standar dalam paket proxy: apiproxy/resources/jsc. Atau, Anda juga bisa menyimpan kode sumber dalam file sumber daya di tingkat lingkungan atau organisasi. Sebagai lihat petunjuk File resource. Anda dapat upload JavaScript melalui editor proxy UI Apigee.

File sumber JavaScript harus selalu memiliki ekstensi .js.

Apigee mendukung JavaScript yang berjalan pada mesin JavaScript Rhino 1.7.13.

Video

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

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

Sampel

Menulis ulang URL target

Berikut ini kasus penggunaan umum: mengekstrak data dari isi permintaan, menyimpannya dalam flow variabel alur, dan menggunakan variabel alur tersebut di tempat lain dalam alur proxy. Katakanlah Anda memiliki aplikasi tempat pengguna memasukkan nama mereka di formulir HTML dan mengirimkannya. Anda ingin proxy API mengekstrak data formulir dan menambahkannya secara dinamis ke URL yang digunakan untuk memanggil layanan backend. Cara apakah Anda akan melakukannya di kebijakan JavsScript?

Catatan: Jika ingin mencoba contoh ini, asumsikan Anda telah membuat {i>proxy<i} di editor {i>proxy<i}. Saat Anda membuatnya, cukup berikan URL layanan backend: http://www.contoh.com. Untuk contoh ini, kita akan menulis ulang URL backend secara dinamis. Jika Anda tidak mengetahui 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. Tempel kode berikut di editor kode dan simpan proxy. Hal yang penting untuk adalah objek context. Objek ini tersedia untuk kode JavaScript di mana saja dalam alur {i>proxy<i}. Ini digunakan untuk mendapatkan konstanta spesifik per alur, untuk memanggil metode get/set, dan untuk operasi lainnya. Bagian objek ini berasal dari antarmuka model objek JavaScript. Catatan: juga, variabel flow 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, yaitu apa pun yang Anda tentukan saat membuat proxy (misalnya, http://www.contoh.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 New Policy, pilih JavaScript.
7. Beri nama kebijakan tersebut, seperti target-rewrite. Setujui setelan default, lalu simpan kebijakan tersebut.
8. Jika memilih Preflow Endpoint Proxy di Navigator, Anda akan melihat bahwa kebijakan ditambahkan ke alur tersebut.
9. Di Navigator, pilih ikon Target Endpoint PreFlow.
10. Dari Navigator, seret kebijakan JavaScript ke sisi Permintaan Target Endpoint di editor alur.
11. Simpan.
12. Panggil API seperti ini, dengan mengganti nama organisasi dan nama proxy Anda yang benar dengan sesuai:

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 di pada contoh ini. Hal penting yang perlu diperhatikan adalah <ResourceURL> digunakan untuk menentukan file sumber JavaScript yang akan dieksekusi. Pola yang sama ini digunakan untuk setiap file sumber JavaScript: jsc://filename.js. Jika kode JavaScript Anda memerlukan penyertaan, Anda dapat menggunakan satu atau lebih elemen <IncludeURL> untuk seperti yang akan 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 pada saat runtime.

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

Di JavaScript, Anda mengambil nilai properti kebijakan dengan mengaksesnya sebagai properti 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 kesalahan yang dapat Anda gunakan dalam Info JavaScript, lihat Cara yang benar untuk menampilkan error dari kebijakan JavaScript. Saran yang ditawarkan di Komunitas Apigee adalah untuk informasi saja dan tidak selalu merepresentasikan 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>

&lt;Javascript&gt; Atribut

<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 skrip mengeksekusi. 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 sama 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. Atau, gunakan elemen <DisplayName> untuk memberi label kebijakan di editor proxy UI pengelolaan dengan nama natural-language yang berbeda.	T/A	Diperlukan
continueOnError	Setel ke false untuk menampilkan error jika kebijakan gagal. Ini adalah perilaku yang wajar untuk sebagian besar kebijakan. Setel ke true agar eksekusi alur tetap berlanjut bahkan setelah kebijakan gagal. Lihat juga: Aturan error HANYA dipicu dalam status error (tentang continueOnError) Menangani kesalahan dalam alur saat ini	false	Opsional
enabled	Setel ke true untuk menerapkan kebijakan. Setel ke false untuk menonaktifkan kebijakan. Kebijakan tidak akan diterapkan meskipun tetap melekat pada alur.	true	Opsional
async	Atribut ini sudah tidak digunakan lagi.	false	Tidak digunakan lagi

Elemen <DisplayName>

Gunakan selain atribut name untuk memberi label kebijakan di editor proxy UI pengelolaan dengan nama natural-language 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

&lt;IncludeURL&gt; elemen

Menentukan file library JavaScript yang akan dimuat sebagai dependensi ke file JavaScript utama ditentukan dengan elemen <ResourceURL> atau <Source>. Skrip akan dievaluasi dalam dengan urutan yang tercantum dalam kebijakan. Kode Anda bisa menggunakan objek, metode, dan properti model objek JavaScript.

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

Peringatan: Jika file JavaScript Anda disimpan di organisasi atau tingkat lingkungan, pastikan file tersebut diupload dengan benar menggunakan cURL menggunakan -F opsi atau sebagai lampiran file melalui klien REST. Jenis-Konten 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 Sampel.

&lt;Property&gt; elemen

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.

&lt;ResourceURL&gt; elemen

Menentukan file JavaScript utama yang akan dieksekusi dalam alur API. Anda dapat menyimpan file ini pada cakupan proxy API (pada /apiproxy/resources/jsc dalam paket proxy API atau di bagian Skrip di panel Navigator editor proxy API), atau di organisasi, cakupan lingkungan untuk digunakan kembali di beberapa proxy API, seperti yang dijelaskan dalam Mengelola resource. Kode Anda bisa menggunakan objek, metode, dan properti model objek JavaScript.

<ResourceURL>jsc://my-javascript.js</ResourceURL>

Default:	Tidak ada
Kehadiran:	<ResourceURL> atau <Source> wajib diisi. Jika <ResourceURL> dan <Source> sama-sama ada <ResourceURL> akan diabaikan.
Jenis:	String

Contoh

Lihat Contoh Dasar di bagian Sampel.

&lt;Source&gt; elemen

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

Default:	Tidak ada
Kehadiran:	<ResourceURL> atau <Source> wajib diisi. Jika <ResourceURL> dan <Source> sama-sama 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>

&lt;SSLInfo&gt; elemen

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 konfigurasi TLS untuk klien HTTP adalah proses yang sama dengan yang Anda gunakan untuk mengkonfigurasi TLS untuk TargetEndpoint/TargetServer. Lihat Opsi untuk mengonfigurasi TLS untuk informasi selengkapnya.

Catatan penggunaan

Peringatan: Panggilan sistem tidak diizinkan oleh keamanan model transformer. Misalnya: pembacaan atau penulisan sistem file internal, atau mendapatkan info pengguna saat ini, daftar proses, atau pemakaian CPU/memori. Meskipun beberapa panggilan tersebut mungkin berfungsi, panggilan tidak didukung dan dapat dinonaktifkan secara aktif kapan saja. Untuk kompatibilitas dengan versi baru, Anda harus hindari melakukan panggilan semacam itu dalam kode Anda.

Proses debug kode kebijakan JavaScript

Menggunakan fungsi print() untuk menampilkan informasi debug ke transaksi panel output di alat Debug. Untuk mengetahui detail dan contohnya, lihat Debug dengan JavaScript Pernyataan print().

Untuk melihat pernyataan cetak di Debug:

1. Buka Alat debug dan mulai sesi pelacakan untuk proxy yang berisi JavaScript Anda lebih lanjut.
2. Panggil proxy.
3. Di Alat Debug, klik Output from all Transactions untuk membuka 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 secara 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 mengatur (dan mendapatkan) alur variabel dalam kode JavaScript Anda dengan memanggil metode pada objek konteks. Pola umum akan 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 kesalahan dan pesan error yang ditampilkan dan variabel kesalahan yang disetel oleh Apigee saat kebijakan ini memicu error. Informasi ini penting untuk diketahui apakah Anda mengembangkan aturan fault untuk menangani kesalahan. Untuk mempelajari lebih lanjut, lihat Yang perlu Anda ketahui tentang error kebijakan dan Menangani kesalahan.

Error runtime

Error ini dapat terjadi saat kebijakan dieksekusi.

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

Kode kesalahan	Status HTTP	Penyebab	Perbaikan
steps.javascript.ScriptExecutionFailed	500	Kebijakan JavaScript dapat menampilkan berbagai jenis error ScriptExecutionFailed. Jenis error yang umum ditemui mencakup RangeError, ReferenceError, SyntaxError, TypeError, dan URIError.
steps.javascript.ScriptExecutionFailedLineNumber	500	Terjadi error di kode JavaScript. Lihat string fault untuk mengetahui detailnya.	T/A
steps.javascript.ScriptSecurityError	500	Terjadi error keamanan saat JavaScript dieksekusi. Lihat string fault 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	Perbaikan
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 direferensikan harus ada proxy API, lingkungan, atau tingkat organisasi.
WrongResourceType	Error ini terjadi selama deployment jika elemen <ResourceURL> atau <IncludeURL> dari kebijakan JavaScript merujuk ke jenis resource apa pun 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 kesalahan

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

Contoh respons error

Catatan: Untuk penanganan error, praktik terbaiknya adalah menjebak bagian errorcode dari respons error. Jangan mengandalkan teks di faultstring, karena bisa 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 kesalahan

<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 dalam JavaScript?