Model objek JavaScript

Halaman ini berlaku untuk Apigee dan Apigee Hybrid.

Lihat dokumentasi Apigee Edge.

Topik ini membahas Model Objek JavaScript Apigee. Anda harus memahami model ini jika ingin menggunakan kebijakan JavaScript untuk menambahkan JavaScript kustom ke proxy API.

Tentang model objek JavaScript

Model objek JavaScript menentukan objek dengan properti terkait yang tersedia untuk kode JavaScript yang dieksekusi dalam alur proxy Apigee. Gunakan kebijakan JavaScript untuk melampirkan kode kustom ini ke alur proxy API.

Objek yang ditentukan oleh model ini memiliki cakupan dalam alur proxy API, yang berarti bahwa objek dan properti tertentu hanya tersedia pada titik tertentu dalam alur. Saat JavaScript Anda dieksekusi, cakupan akan dibuat untuk eksekusi. Dalam cakupan tersebut, referensi objek ini dibuat:

  • context: Objek yang memberikan akses ke konteks pesan
  • request: Singkatan yang memungkinkan akses ke objek permintaan
  • response: Singkatan yang memungkinkan akses ke objek respons
  • crypto: Menyediakan berbagai fungsi hash
  • print: Fungsi untuk mengeluarkan output
  • properties: Mengizinkan akses baca ke properti konfigurasi pada kebijakan

Objek konteks

Objek context memiliki cakupan global. Fitur ini tersedia di mana saja dalam alur proxy API. Objek ini memiliki empat objek turunan: proxyRequest, proxyResponse, targetRequest, targetResponse. Objek turunan ini dicakup ke permintaan dan respons sekitar, baik permintaan dan respons proxy maupun permintaan dan respons target. Misalnya, jika kebijakan JavaScript dieksekusi di bagian endpoint proxy dari alur, objek context.proxyRequest dan context.proxyResponse berada dalam cakupan. Jika JavaScript berjalan dalam alur target, objek context.targetRequest dan context.targetResponse berada dalam cakupan.

Objek context juga memiliki properti dan metode, yang dijelaskan secara mendetail dalam topik ini. Misalnya, contoh kode JavaScript berikut menggunakan properti context.flow dan memanggil metode get/setVariable() di context. 

if (context.flow=="PROXY_REQ_FLOW") {
     var username = context.getVariable("request.formparam.user");
     context.setVariable("USER.name", username);
}

Metode ini berinteraksi langsung dengan variabel alur. Nilai properti context.flow adalah cakupan alur saat ini. Dalam alur permintaan proxy, parameter ini ditetapkan ke konstanta PROXY_REQ_FLOW. Jika dalam alur respons target, nilai ini ditetapkan ke TARGET_RESP_FLOW. Konstanta ini berguna untuk mengeksekusi kode khusus cakupan. Pengambil memungkinkan Anda mendapatkan variabel alur dan penyetel memungkinkan Anda menyetel variabel alur. Variabel ini umumnya tersedia dalam alur proxy dan dapat digunakan oleh kebijakan lain.

Lihat referensi objek konteks untuk mengetahui detail dan contoh selengkapnya.

Objek kripto

Objek kripto menambahkan dukungan kriptografi berperforma tinggi dan dasar ke Model Objek JavaScript. Lihat referensi objek kripto untuk mengetahui detail dan contoh selengkapnya.

Objek permintaan dan respons

Objek request dan response adalah referensi singkatan ke permintaan dan respons sekitar, baik permintaan dan respons proxy maupun permintaan dan respons target. Objek yang dirujuk oleh variabel ini bergantung pada konteks saat kebijakan JavaScript dieksekusi. Jika JavaScript berjalan dalam alur endpoint proxy, maka variabel permintaan dan respons merujuk ke context.proxyRequest dan context.proxyResponse. Jika JavaScript berjalan dalam alur target, variabel merujuk ke context.targetRequest dan context.targetResponse.

Model objek JavaScript mencakup fungsi print() yang dapat Anda gunakan untuk menampilkan informasi debug ke alat Debug Apigee. Lihat Men-debug dengan pernyataan print() JavaScript.

Objek properti

Saat menggunakan elemen Properties dalam konfigurasi kebijakan, kode JavaScript dapat mengakses nilai properti tersebut menggunakan variabel properties.

Misalnya, jika konfigurasi JavaScript Anda berisi:

<Javascript name='JS-1' >
  <Properties>
    <Property name="number">8675309</Property>
    <Property name="firstname">Jenny</Property>
  </Properties>
  <ResourceURL>jsc://my-code.js</ResourceURL>
</Javascript>

Kemudian di my-code.js, Anda dapat:

  print(properties.firstname);  // prints Jenny
  print(properties.number);  // 8675309

Secara lebih praktis, konfigurasi dapat memungkinkan kode berperilaku berbeda saat dijalankan di lingkungan yang berbeda, pada waktu yang berbeda, atau karena alasan apa pun.

Misalnya, berikut menentukan "nama variabel" dan gaya output yang harus dikeluarkan JavaScript:

<Javascript name='JS-2' >
  <Properties>
    <Property name="output">my_output_variable</Property>
    <Property name="prettyPrint">true</Property>
  </Properties>
  <ResourceURL>jsc://emit-results.js</ResourceURL>
</Javascript>
 Kemudian di emit-results.js, kode dapat melakukan hal berikut: 
var result = { prop1: "something", prop2 : "something else" } ;
if (properties.prettyPrint == "true") {
  context.setVariable(properties.output, JSON.stringify(result, null, 2));
}
else {
  context.setVariable(properties.output, JSON.stringify(result));
}

Referensi objek kripto

Objek kripto memungkinkan Anda melakukan fungsi {i>hashing<i} kriptografi dasar di JavaScript.

Objek kripto memiliki cakupan global. Kebijakan ini tersedia di mana saja dalam alur proxy API. Crypto memungkinkan Anda bekerja dengan objek hash berikut:

  • SHA-1
  • SHA256
  • SHA512
  • MD5

Bekerja dengan objek SHA-1

Anda dapat membuat objek SHA-1, memperbaruinya, dan mengonversinya ke nilai hex dan base64.

Membuat objek SHA-1 baru

var _sha1 = crypto.getSHA1();

Memperbarui objek SHA-1

Sintaksis

_sha1.update(value);

Parameter

  • value - (String) Nilai string apa pun.

Contoh

Perbarui objek SHA-1:

_sha1.update("salt_value");

_sha1.update("some text");

Menampilkan objek SHA-1 sebagai string hex

var _hashed_token = _sha1.digest();

Menampilkan objek SHA-1 sebagai string base64

var _hashed_token = _sha1.digest64();

Bekerja dengan objek SHA-256

Anda dapat membuat objek SHA-256, memperbaruinya, dan mengonversinya ke nilai hex dan base64.

Buat objek SHA-256 baru

var _sha256 = crypto.getSHA256();

Memperbarui objek SHA-256

Sintaksis

_sha256.update(value);

Parameter

  • value - (String) Nilai string apa pun.

Contoh

Perbarui objek SHA-256:

_sha256.update("salt_value");

_sha256.update("some text");

Menampilkan objek SHA-256 sebagai string hex

var _hashed_token = _sha256.digest();

Menampilkan objek SHA-256 sebagai string base64

var _hashed_token = _sha256.digest64();

Bekerja dengan objek SHA-512

Anda dapat membuat objek SHA-512, memperbaruinya, dan mengonversinya menjadi nilai hex dan base64.

Buat objek SHA-512 baru

var _sha512 = crypto.getSHA512();

Memperbarui objek SHA-512

Sintaksis

_sha512.update(value);

Parameter

  • value - (String) Nilai string apa pun.

Contoh

Perbarui objek SHA-512:

_sha512.update("salt_value");

_sha512.update("some text");

Menampilkan objek SHA-512 sebagai string hex

var _hashed_token = _sha512.digest();

Menampilkan objek SHA-512 sebagai string base64

var _hashed_token = _sha512.digest64();

Bekerja dengan objek MD5

Anda dapat membuat objek MD5, memperbaruinya, dan mengonversinya ke nilai hex dan base64.

Buat objek MD5 baru

var _md5 = crypto.getMD5();

Memperbarui objek MD5

Sintaksis

_md5.update(value);

Parameter

  • value - (String) Nilai string apa pun.

Contoh

Perbarui objek MD5:

_md5.update("salt_value");

_md5.update("some text");

Menampilkan objek MD5 sebagai string hex

var _hashed_token = _md5.digest();

Menampilkan objek MD5 sebagai string base64

var _hashed_token = _md5.digest64();

Dukungan tanggal/waktu kripto

Objek kripto mendukung pola pemformatan tanggal/waktu.

crypto.dateFormat()

Menampilkan tanggal dalam format string.

Sintaksis

crypto.dateFormat(format, [timezone], [time])

Parameter

  • format - (String) Penerapan yang mendasari parameter ini adalah java.text.SimpleDateFormat. Misalnya: 'YYYY-MM-DD HH:mm:ss.SSS'
  • timezone - (String, opsional) Penerapan yang mendasari parameter ini adalah java.util.TimeZone. Parameter ini sama dengan Default: UTC
  • time - (Angka, opsional) Nilai stempel waktu Unix yang akan diformat. Default: waktu saat ini

Contoh

Mendapatkan waktu saat ini, hingga milidetik:

var _now = crypto.dateFormat('YYYY-MM-DD HH:mm:ss.SSS');

Dapatkan waktu saat ini untuk Zona Waktu Pasifik:

var _pst = crypto.dateFormat('YYYY-MM-DD HH:mm:ss.SSS','PST');

Dapatkan nilai sepuluh detik dari sekarang:

var _timeNow = Number(context.getVariable('system.timestamp'));
var tenSeconds = crypto.dateFormat('YYYY-MM-DD HH:mm:ss.SSS','PST', _timeNow + 10 * 1000);

Contoh tambahan. Lihat juga dokumentasi java.text.SimpleDateFormat.

var _pst = crypto.dateFormat('M');
 
var _pst = crypto.dateFormat('EEE, d MMM yyyy HH:mm:ss Z');
 
var _pst = crypto.dateFormat("yyyy-MM-dd'T'HH:mm:ss.SSSZ");

Mengamankan dokumen SOAP menggunakan WS-Security dengan sertifikat X.509

Mengamankan dokumen SOAP menggunakan WS-Security dengan tanda tangan digital RSA/X.509.

crypto.wsSecRsaSign()

Menandatangani dokumen SOAP dan menampilkan payload yang ditandatangani.

Sintaksis

crypto.wsSecRsaSign(payload, options)

Parameter

  • payload - (String) Dokumen SOAP yang akan ditandatangani.
  • options - (Objek) Opsi konfigurasi untuk tanda tangan digital. Tabel berikut mencantumkan opsi konfigurasi yang tersedia. Semua nilai opsi dapat berupa string literal atau template pesan, yang ditunjukkan dengan menggunakan karakter template '{' dan '}'.
    Nama Wajib? Deskripsi
    certificate Wajib Sertifikat yang cocok dengan kunci pribadi dalam format PEM.
    private_key Wajib Variabel alur yang berisi kunci pribadi dalam format PEM.
    c14_inclusive_elements Opsional Daftar URI namespace (bukan awalan) yang dipisahkan koma yang digunakan untuk menambahkan elemen InclusiveElements ke elemen CanonicalizationMethod.
    confirmation Opsional Salah satu dari berikut ini:
    • Daftar nilai tanda tangan dalam elemen SignatureConfirmation yang akan ditandatangani. Jika elemen SignatureConfirmation dengan nilai yang ditentukan tidak ada, elemen tersebut akan disisipkan.
    • String \*all\* yang menunjukkan bahwa elemen SignatureConfirmation yang ada dalam dokumen sumber akan ditandatangani.
    • String kosong yang menunjukkan untuk menyisipkan elemen SignatureConfirmation kosong.
    Tanda tangan konfirmasi ini merupakan tambahan dari elemen yang ditentukan dalam elements-to-sign.
    digest_method Opsional Algoritma ringkasan. Nilai yang valid adalah sha1 atau sha256. Nilai defaultnya adalah sha256.
    ds_prefix Opsional String sederhana yang akan digunakan sebagai awalan untuk namespace.
    elements_to_sign Opsional Array ekspresi XPath untuk elemen yang akan ditandatangani (seperti, ["soapenv:Body"]).
    expiry Opsional Nilai yang akan disisipkan dalam elemen Expires dari Timestamp. Masukkan nilai seperti 120s, 10m, dan 4d untuk menunjukkan 120 detik, 10 menit, dan 4 hari. Defaultnya adalah tidak ada masa berlaku.
    ignore_security_header_placement Opsional Nilai boolean yang menentukan apakah akan memeriksa penempatan header Security yang ada dalam payload yang tidak bertanda tangan. Disediakan untuk kompatibilitas dengan beberapa sistem lama. Menetapkan ke true tidak direkomendasikan karena dapat mengekspos API Anda ke serangan pembungkusan tanda tangan. Nilai defaultnya adalah false.
    issuer_name_style Opsional Format nama penerbit. Nilai yang valid adalah CN atau DN.
    key_identifier_type Opsional Jenis ID utama. Nilai yang valid adalah BinarySecurityToken, BST_DIRECT_REFERENCE, ISSUER_SERIAL, RSA_KEY_VALUE, THUMBPRINT,dan X509_CERT_DIRECT. Nilai defaultnya adalah BinarySecurityToken.
    private_key_password Opsional Kunci sandi, jika kunci pribadi dienkripsi.
    signing_method Opsional Metode yang digunakan untuk menandatangani. Nilai yang valid adalah rsa-sha1 atau rsa-sha256. Secara default, nilainya adalah rsa-sha1; namun, sebaiknya tetapkan ke rsa-sha256.
    soap_version Opsional Versi SOAP. Versi yang valid adalah 1.1 dan 1.2. Default-nya adalah 1.1.
    transform_inclusive_elements Opsional Daftar URI namespace (bukan awalan) yang dipisahkan koma yang digunakan untuk menambahkan elemen InclusiveElements ke elemen Transform.

Contoh

Contoh berikut menunjukkan cara menandatangani dokumen SOAP. Proses ini mengasumsikan bahwa kunci pribadi dan sertifikat dimuat ke dalam variabel alur.

var signed = crypto.wsSecRsaSign(request.content, {
    'private_key': '{private.key.pem}', // Flow variable name
    'certificate': '{public.cert.pem}', // Flow variable name
    'elements_to_sign: 
        'wsu:Timestamp, soap:Body, wsa:To, wsa:MessageID',
    'signing_method': 'rsa-sha256',
    'digest_method': 'sha256',
    expires_in': '180s'
});

Memvalidasi dokumen SOAP menggunakan WS-Security dengan sertifikat X.509

Memvalidasi tanda tangan digital untuk dokumen SOAP menggunakan WS-Security dengan RSA/X.509. Gaambo melakukan validasi untuk memastikan bahwa argumen yang diteruskan valid.

crypto.wsSecRsaValidate()

Memvalidasi tanda tangan digital untuk dokumen SOAP.

Sintaksis

crypto.wsSecRsaValidate(payload, options)

Parameter

  • payload - (String) Dokumen SOAP dengan tanda tangan digital yang akan divalidasi.
  • options - (Objek) Opsi konfigurasi untuk validasi. Tabel berikut mencantumkan opsi konfigurasi yang tersedia. Semua nilai opsi dapat berupa string literal atau template pesan, yang ditunjukkan dengan menggunakan karakter template '{' dan ''}'.
    Nama Wajib? Deskripsi
    accept_subject_cns Opsional Daftar nama umum (CN) yang dipisahkan koma untuk subjek yang merupakan penanda tangan yang dapat diterima. Jika ada tanda tangan yang berasal dari CN yang tidak cocok dengan salah satu CN yang ditentukan, verifikasi akan gagal.
    accept_thumbprints Opsional Daftar SHA-1 thumbprint sertifikat yang dipisahkan koma dan merupakan penanda tangan yang dapat diterima. Jika ada tanda tangan dari sertifikat yang memiliki thumbprint yang tidak cocok dengan salah satu thumbprint yang ditentukan, verifikasi akan gagal. Tentukan hanya salah satu dari accept-thumbprints atau accept-thumbprints-256. Setidaknya salah satu opsi ini diperlukan jika opsi certificate tidak diberikan.
    accept_thumbprints_256 Opsional Daftar SHA-256 thumbprint sertifikat yang dipisahkan koma dan merupakan penanda tangan yang dapat diterima. Jika ada tanda tangan dari sertifikat yang memiliki thumbprint yang tidak cocok dengan salah satu thumbprint yang ditentukan, verifikasi akan gagal. Tentukan hanya salah satu dari accept-thumbprints atau accept-thumbprints-256. Setidaknya salah satu opsi ini diperlukan jika opsi certificate tidak diberikan.
    certificate Opsional Sertifikat yang menyediakan kunci publik untuk memverifikasi tanda tangan. Diperlukan dan digunakan hanya jika KeyInfo dalam dokumen yang ditandatangani tidak secara eksplisit memberikan sertifikat.
    digest_method Opsional Metode ringkasan yang didukung. Nilai yang valid adalah sha1 atau sha256. Jika dihilangkan, metode ringkasan tidak diperiksa.
    ignore_certificate_expiry Opsional Nilai Boolean yang menentukan apakah akan mengabaikan tanggal validitas pada sertifikat yang diberikan. Berguna untuk pengujian. Nilai defaultnya adalah false.
    ignore_expiry Opsional Nilai Boolean yang menentukan apakah akan mengabaikan kolom Timestamp/Expires saat mengevaluasi validitas dokumen SOAP. Nilai defaultnya adalah false.
    ignore_security_header_placement Opsional Nilai boolean yang menentukan apakah akan memeriksa penempatan header keamanan dalam payload yang ditandatangani. Disediakan untuk kompatibilitas dengan beberapa sistem lama. Menetapkan nilai ini ke true tidak direkomendasikan karena dapat mengekspos API ke serangan pembungkusan tanda tangan. Nilai defaultnya adalah false.
    issuer_name_dn_comparison Opsional Metode yang digunakan untuk menentukan apakah dua nama penerbit merujuk pada entitas yang sama. Hanya berlaku jika dokumen yang ditandatangani menyertakan KeyInfo yang membungkus X509IssuerSerial dan issuer-name-style adalah DN (default). Nilai dapat berupa salah satu dari {string, normal, reverse, unordered}. Defaultnya adalah string.
    issuer_name_dn_comparison_exclue_numeric_oids Opsional Metode yang digunakan untuk menentukan apakah dua nama penerbit merujuk ke entitas yang sama. Hanya berlaku jika dokumen yang ditandatangani menyertakan KeyInfo yang membungkus X509IssuerSerial dan issuer-name-style adalah DN (default), dan issuer-name-dn-comparison ditetapkan ke normal, reverse, atau unordered.
    issuer_name_style Opsional Format nama penerbit. Hanya digunakan jika dokumen yang ditandatangani menyertakan KeyInfo yang membungkus X509IssuerSerial. Nilai yang valid mencakup CN atau DN.
    max_lifetime Opsional Masa berlaku maksimum dokumen yang ditandatangani. Masukkan nilai seperti 120s, 10m, dan 4d untuk menunjukkan 120 detik, 10 menit, dan 4 hari. Opsi ini mengharuskan Timestamp menyertakan elemen Created dan Expires. Default ke masa aktif maksimum tidak ada.
    require_expiry Opsional Nilai boolean yang menentukan apakah masa berlaku diperlukan dalam stempel waktu. Sebaiknya nilai ini tetap ditetapkan ke true. Nilai defaultnya adalah true.
    required_sign_elements Opsional Daftar formulir prefix:Tag yang dipisahkan koma atau spasi yang menunjukkan elemen yang harus ditandatangani. Nilai defaultnya adalah soap:Body, wsu:Timestamp. Untuk hanya mewajibkan tanda tangan pada stempel waktu dan bukan isi saat memvalidasi, tetapkan ini ke wsu:Timestamp. Untuk hanya mewajibkan tanda tangan pada isi dan bukan stempel waktu saat memvalidasi, tetapkan ini ke soap:Body. Awalan dan tag peka huruf besar/kecil. Sebaiknya biarkan nilai ini ditetapkan ke default kecuali Anda memiliki alasan khusus untuk mengubahnya.
    signing_method Opsional Metode penandatanganan yang harus cocok dengan metode penandatanganan dalam dokumen yang ditandatangani. Nilai yang valid adalah rsa-sha1 atau rsa-sha256. Jika tidak ada, metode penandatanganan tidak diperiksa.

Contoh

Contoh berikut menunjukkan cara memvalidasi API berbasis SOAP yang ditandatangani. Jika tanda tangan tidak valid, variabel alur wssec_error akan diisi dengan error tertentu.

Var isValid = crypto.wsSecRsaValidate(request.content, {
        MaxLifetime: '300s',
        RequiredSignedElements: [
            '//*[local-name()=\'Body\']'
        ],
        IgnoreCertificateExpiry: false,
        TrustStore: '{truststore.pem}' // Flow variable with trusted certs
    });

 if (!isValid) {
   throw "invalid"
 }

Gunakan getHash() untuk mendapatkan objek hash yang didukung

Contoh

var _hash1 = crypto.getHash('MD5');

var _hash2 = crypto.getHash('SHA-1');

var _hash3 = crypto.getHash('SHA-256');

var _hash4 = crypto.getHash('SHA-512');

Contoh dengan kripto

try {
    // get values to use with hash functions
    var salt = context.getVariable("salt") || 'SomeHardCodedSalt';
    var host = context.getVariable("request.header.Host");
    var unhashedToken = "";

    var _timeNow = Number(context.getVariable('system.timestamp'));
    var now = crypto.dateFormat('YYYY-MM-DD HH:mm:ss.SSS','PST', _timeNow);
    unhashed_token = "|" + now + "|" + host

    // generate a hash with the unhashedToken:
    var sha512 = crypto.getSHA512();
    sha512.update(salt);
    sha512.update(unhashedToken);

    // convert to base64
    var base64Token = sha512.digest64();

    // set headers
    context.setVariable("request.header.now", now);
    context.setVariable("request.header.token", base64Token);

} catch(e) {
    throw 'Error in Javascript';
}

Referensi objek konteks

Objek context dibuat untuk setiap transaksi permintaan/respons yang dieksekusi oleh proxy API. Objek context mengekspos metode untuk mendapatkan, menetapkan, dan menghapus variabel yang terkait dengan setiap transaksi.

Variabel menentukan properti khusus untuk transaksi. Waktu dalam sehari, lokalitas klien yang meminta, agen pengguna klien yang meminta, dan URL layanan target adalah semua contoh variabel yang tersedia di context. Oleh karena itu, context berguna untuk membangun logika yang mengandalkan properti ini untuk menjalankan perilaku kustom.

Lihat Referensi variabel alur dan kebijakan ExtractVariables.

konteks ringkasan objek

Tabel ini secara singkat menjelaskan objek konteks dan turunannya, serta mencantumkan properti yang terikat pada masing-masing objek.

Nama Deskripsi Properti
context Wrapper untuk konteks pipeline pemrosesan pesan dan Flow permintaan dan respons yang dieksekusi oleh ProxyEndpoint dan TargetEndpoint. flow, session
context.proxyRequest Objek yang merepresentasikan pesan permintaan masuk ke ProxyEndpoint (dari aplikasi yang meminta ke proxy API) header, parameter kueri, metode, isi, URL
context.targetRequest Objek yang merepresentasikan pesan permintaan keluar dari TargetEndpoint (dari proxy API ke layanan backend). header, parameter kueri, metode, isi, URL
context.targetResponse Objek yang merepresentasikan pesan respons target masuk (dari layanan backend ke proxy API) header, konten, status
context.proxyResponse Objek yang merepresentasikan pesan respons proxy keluar (dari proxy API ke aplikasi yang meminta) header, konten, status
context.flow Nama alur saat ini. Lihat context.flow.
context.session Peta pasangan nama/nilai yang dapat Anda gunakan untuk meneruskan objek antara dua langkah berbeda yang dijalankan dalam konteks yang sama. Misalnya: context.session['key'] = 123. Untuk mengetahui informasi selengkapnya tentang kapan dan kapan tidak menggunakan objek ini, lihat Apa perbedaan antara context.session['hello'] = {} dan context.setVariable("hello", {}).

Metode objek konteks

context.getVariable()

Mengambil nilai variabel standar atau kustom.

Sintaksis

context.getVariable("variable-name");

Contoh

Untuk mendapatkan nilai tahun ini:

var year = context.getVariable('system.time.year');

context.setVariable()

Menetapkan nilai untuk variabel kustom atau untuk variabel bawaan yang dapat ditulis.

Sintaksis

context.setVariable("variable-name", value);

Contoh

Skenario umum untuk menyetel variabel adalah saat proxy API harus menulis URL target secara dinamis. JavaScript berikut mendapatkan nilai variabel bernama USER.name, menambahkan nilai tersebut sebagai parameter kueri ke URL http://mocktarget.apigee.net?user=, lalu menetapkan target.url yang telah ditentukan sebelumnya ke nilai tersebut.

context.setVariable("target.url", "http://mocktarget.apigee.net/user?user="+context.getVariable("USER.name"));

context.removeVariable()

Menghapus variabel dari konteks.

Sintaksis

context.removeVariable('variable-name');

properti objek konteks

context.flow

Properti flow adalah string yang mengidentifikasi alur proxy API saat ini. Properti ini digunakan untuk menunjukkan Alur yang menjadi tempat JavaScript terlampir. Nilai yang didukung adalah:

  • PROXY_REQ_FLOW
  • PROXY_RESP_FLOW
  • TARGET_REQ_FLOW
  • TARGET_RESP_FLOW

Setiap nama Flow mencakup PreFlow, PostFlow, dan Flow bersyarat yang ditentukan dalam ProxyEndpoint atau TargetEndpoint.

Properti opsional ini berguna saat JavaScript umum dieksekusi di lebih dari satu Flow, tetapi mungkin berbeda perilakunya bergantung pada Flow tempat JavaScript dieksekusi. Gunakan properti Alur untuk modul JavaScript yang dimaksudkan untuk digunakan kembali di beberapa proxy API, yang kodenya diperlukan untuk memeriksa Alur saat ini sebelum menjalankan logika.

Contoh

Menetapkan header HTTP hanya pada targetRequest Flow:

if (context.flow=="TARGET_REQ_FLOW") {
     context.targetRequest.headers['TARGET-HEADER-X']='foo';
}

Setel konten hanya di proxyResponse Flow:

if (context.flow=="PROXY_RESP_FLOW") {
     context.proxyResponse.content='bar';
}

context.session

Peta pasangan nama/nilai yang dapat digunakan untuk meneruskan objek antara dua kebijakan yang dijalankan dalam konteks pesan yang sama.

Contoh

Menetapkan nilai dalam sesi:

context.session['key']  = 123;

Dapatkan nilai dari sesi:

var value = context.session['key']; // 123

Turunan objek konteks

Seperti yang ditunjukkan di bawah, Flow proxy API yang lengkap mencakup empat fase berbeda, yang masing-masing memiliki objek pesan terkait yang merupakan turunan dari objek konteks:

  • context.proxyRequest: Pesan permintaan masuk yang diterima dari klien yang meminta.
  • context.targetRequest: Pesan permintaan keluar yang dikirim ke layanan backend.
  • context.proxyResponse: Pesan respons keluar yang ditampilkan ke klien yang meminta.
  • context.targetResponse: Pesan permintaan masuk yang diterima dari layanan backend.

Diagram permintaan dan respons yang melewati endpoint proxy dan endpoint target.

Bagian berikut menjelaskan metode dan properti objek ini:

context.*Meminta objek turunan

Untuk setiap transaksi HTTP yang dijalankan di proxy API, dua objek pesan permintaan dibuat: satu masuk (permintaan dari klien) dan satu keluar (permintaan yang dihasilkan oleh proxy API dan dikirimkan ke target backend).

Objek context memiliki objek turunan yang merepresentasikan pesan permintaan ini: context.proxyRequest dan context.targetRequest. Objek ini memungkinkan Anda mengakses properti dalam alur permintaan yang berada dalam cakupan saat kode JavaScript dieksekusi.

context.*Meminta properti objek turunan

Nama properti Deskripsi
url

Properti url adalah properti baca/tulis praktis yang menggabungkan skema, host, port, jalur, dan parameter kueri untuk targetRequest.

URL lengkap permintaan terdiri dari properti berikut:

  • protokol: Protokol URL (misalnya, HTTP, HTTPS)
  • port: Port (misalnya, :80, :443)
  • host: Host URL (misalnya, www.example.com)
  • path: Jalur URI (misalnya, /v1/mocktarget)

Saat mendapatkan url, URL akan ditampilkan dalam format berikut:

protocol://host:port/path?queryParams

Contoh:

context.targetRequest.url = 'http://www.example.com/path?q1=1'
context.targetRequest.protocol ='https';
headers

Header permintaan HTTP sebagai pemetaan String => List

Contoh:

Untuk permintaan HTTP ini:

POST /v1/blogs HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer ylSkZIjbdWybfs4fUQe9BqP0LH5Z
JavaScript berikut: 
context.proxyRequest.headers['Content-Type'];
context.proxyRequest.headers['Authorization'];

akan menampilkan nilai berikut

application/json
Bearer ylSkZIjbdWybfs4fUQe9BqP0LH5Z
queryParams

Parameter kueri pesan permintaan sebagai pemetaan String => List.

Contoh:

"?city=PaloAlto&city=NewYork"

dapat diakses sebagai:

context.proxyRequest.queryParams['city'];  // == 'PaloAlto'
context.proxyRequest.queryParams['city'][0]     // == 'PaloAlto'
context.proxyRequest.queryParams['city'][1];    // == 'NewYork'
context.proxyRequest.queryParams['city'].length(); // == 2
method

Kata kerja HTTP (GET, POST, PUT, DELETE. PATCH, dll.) yang terkait dengan permintaan

Contoh:

Untuk permintaan ini:

POST /v1/blogs HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer ylSkZIjbdWybfs4fUQe9BqP0LH5Z

JavaScript berikut:

context.proxyRequest.method;

akan menampilkan nilai berikut

POST
body

Isi pesan (payload) permintaan HTTP.

Isi permintaan memiliki anggota berikut:

  • context.targetRequest.body.asXML;
  • context.targetRequest.body.asJSON;
  • context.targetRequest.body.asForm;

Contoh:

Untuk isi XML:

<customer number='1'>
<name>Fred<name/>
<customer/>

Untuk mengakses elemen objek XML sebagai berikut:

var name = context.targetRequest.body.asXML.name;

Untuk mengakses atribut XML, gunakan notasi @.

var number = context.targetRequest.body.asXML.@number;

Untuk isi permintaan JSON:

{
"a":  1 ,
"b" : "2"
}
 
var a = context.proxyRequest.body.asJSON.a;    // == 1
var b = context.proxyRequest.body.asJSON.b;    // == 2

Untuk membaca parameter formulir:

"vehicle=Car&vehicle=Truck"
 
v0 = context.proxyRequest.body.asForm['vehicle'][0];
v1 = context.proxyRequest.body.asForm['vehicle'][1];

Objek turunan context.*Response

Untuk setiap transaksi HTTP yang dieksekusi di proxy API, dua objek pesan respons dibuat: satu masuk (respons dari layanan backend) dan satu keluar (respons yang dikirim kembali ke klien).

Objek konteks memiliki objek turunan yang merepresentasikan pesan respons ini: context.proxyResponse dan context.targetResponse. Objek ini memungkinkan Anda mengakses properti dalam alur respons yang berada dalam cakupan saat kode JavaScript dieksekusi.

Properti objek context.*Response

Nama properti Deskripsi
headers

Header HTTP pesan respons sebagai pemetaan String => List.

Contoh:

var cookie = context.targetResponse.headers['Set-Cookie'];
status

Kode status dengan pesan status sebagai properti. Kode status dan pesan status tersedia sebagai properti.

Contoh:

var status = context.targetResponse.status.code;   // 200
var msg = context.targetResponse.status.message;   // "OK"
content

Isi HTTP (konten payload) pesan respons.

Konten respons memiliki anggota berikut:

context.targetResponse.content.asXML;
context.targetResponse.content.asJSON;

Menggunakan notasi .asXML

Ada cara praktis untuk menelusuri dokumen XML menggunakan notasi .asXML. Bagian ini menjelaskan cara menggunakan notasi ini, dan perbedaannya dengan request.content dan context.proxyRequest.content.

Contoh:

request.content.asXML

atau

context.proxyRequest.content.asXML

Bentuk *.content dan *.content.asXML dapat digunakan dalam konteks string, dan JavaScript akan memaksa keduanya menjadi string. Dalam kasus pertama (*.content), string mencakup semua deklarasi serta komentar XML. Dalam kasus terakhir (*.content.asXML), nilai string dari hasil dibersihkan dari deklarasi dan komentar.

Contoh

msg.content:

<?xml version="1.0" encoding="UTF-8"?>
<yahoo:error xmlns:yahoo="http://yahooapis.com/v1/base.rng" xml:lang="en-US">
   <yahoo:description>Please provide valid credentials. OAuth oauth_problem="unable_to_determine_oauth_type", realm="yahooapis.com"
   </yahoo:description>
</yahoo:error>
<!-- mg023.mail.gq1.yahoo.com uncompressed/chunked Sat Dec 14 01:23:35 UTC 2013 -->

msg.content.asXML:

<?xml version="1.0" encoding="UTF-8"?>
<yahoo:error xmlns:yahoo="http://yahooapis.com/v1/base.rng" xml:lang="en-US">
   <yahoo:description>Please provide valid credentials. OAuth oauth_problem="unable_to_determine_oauth_type", realm="yahooapis.com"
   </yahoo:description>
</yahoo:error>

Selain itu, Anda dapat menggunakan formulir .asXML untuk menjelajahi hierarki XML, dengan menentukan nama elemen dan atribut. Anda tidak dapat menjelajahi hierarki menggunakan sintaksis lainnya.

Men-debug dengan pernyataan print() JavaScript

Jika Anda menggunakan kebijakan JavaScript untuk mengeksekusi kode JavaScript kustom, perhatikan bahwa Anda dapat menggunakan fungsi print() untuk menampilkan informasi debug ke Alat debug. Fungsi ini tersedia langsung melalui model objek JavaScript. Contoh:

if (context.flow=="PROXY_REQ_FLOW") {
     print("In proxy request flow");
     var username = context.getVariable("request.queryparam.user");
     print("Got query param: " + username);
     context.setVariable("USER.name", username);
     print("Set query param: " + context.getVariable("USER.name"));
}


if (context.flow=="TARGET_REQ_FLOW") {
     print("In target request flow");
     var username = context.getVariable("USER.name");
     var url = "http://mocktarget.apigee.net/user?"
     context.setVariable("target.url", url + "user=" + username);
     print("Callout to URL: ", context.getVariable("target.url"));
}

Untuk melihat output, pilih Output dari semua transaksi di bagian bawah jendela Debug. Anda juga dapat menemukan output di properti Debug yang disebut stepExecution-stdout.

Membuat panggilan JavaScript dengan httpClient

Gunakan httpClient untuk membuat beberapa permintaan HTTP asinkron paralel ke URL apa pun dari dalam kode JavaScript kustom yang dieksekusi dalam alur proxy API. Objek httpClient diekspos oleh model objek Javascript Apigee.

Tentang httpClient

Objek httpClient diekspos ke kode JavaScript kustom yang berjalan di Apigee melalui model objek JavaScript. Untuk melampirkan JavaScript kustom ke proxy API, Anda menggunakan kebijakan JavaScript. Saat kebijakan berjalan, kode JavaScript kustom akan dieksekusi.

Objek httpClient berguna untuk mengembangkan layanan komposit atau mashup. Misalnya, Anda dapat menggabungkan beberapa panggilan backend ke dalam satu metode API.

Berikut pola penggunaan dasarnya. Buat instance objek Request, tetapkan URL ke objek tersebut (misalnya, ke layanan backend yang ingin Anda panggil), dan panggil httpClient.send dengan objek permintaan tersebut.

var myRequest = new Request();
myRequest.url = "http://www.example.com";
var exchangeObj = httpClient.send(myRequest);

Referensi httpClient

Klien HTTP mengekspos dua metode: get() dan send().

httpClient.get()

Metode praktis untuk permintaan GET HTTP sederhana, tanpa dukungan untuk header HTTP.

Penggunaan

var exchangeObj = httpClient.get(url);

Menampilkan

Metode ini menampilkan objek exchange. Objek ini tidak memiliki properti, dan mengekspos metode berikut:

  • isError(): (Boolean) Menampilkan true jika httpClient tidak dapat terhubung ke server. Kode status HTTP 4xx dan 5xx menghasilkan isError() false, karena koneksi selesai dan kode respons yang valid ditampilkan. Jika isError() menampilkan true, maka panggilan ke getResponse() akan menampilkan undefined JavaScript.
  • isSuccess(): (Boolean) Menampilkan true jika pengiriman selesai dan berhasil.
  • isComplete(): (Boolean) Menampilkan true jika permintaan selesai.
  • waitForComplete(): Menjeda thread hingga permintaan selesai (berhasil atau error).
  • getResponse(): (objek) Menampilkan objek respons jika httpClient.send() selesai dan berhasil. Objek yang ditampilkan memiliki metode dan properti yang identik dengan objek context.proxyResponse. Lihat ringkasan objek konteks.
  • getError(): (string) Jika panggilan ke httpClient.send() menghasilkan error, menampilkan pesan error sebagai string.

Contoh

Kirim objek Permintaan yang dikonfigurasi sepenuhnya yang berisi properti permintaan HTTP. Gunakan callback non-blocking untuk memproses respons.

// Add the required the headers for making a specific API request
var headers = {'X-SOME-HEADER' : 'some value' };
// Make a GET API request along with headers
var myRequest = new Request("http://www.example.com","GET",headers);

// Define the callback function and process the response from the GET API request
function onComplete(response,error) {
 // Check if the HTTP request was successful
    if (response) {
      context.setVariable('example.status', response.status);
     } else {
      context.setVariable('example.error', 'Woops: ' + error);
     }
}

// Specify the callback Function as an argument
httpClient.get(myRequest, onComplete);

Menggunakan kebijakan JavaScript

Gunakan kebijakan JavaScript untuk melampirkan kode JavaScript kustom ke alur proxy. Lihat Kebijakan JavaScript.

Topik terkait