Proxy API pemrograman dengan JavaScript

Anda sedang melihat dokumentasi Apigee Edge.
Buka dokumentasi Apigee X. info

Dalam topik ini, Anda akan mempelajari cara menggunakan JavaScript untuk menambahkan header HTTP secara dinamis ke pesan respons dan cara mengurai respons JSON serta menampilkan subset propertinya ke aplikasi yang meminta.

Mendownload dan mencoba kode contoh

Tentang contoh buku resep ini

Contoh cookbook ini menggambarkan pola proxy API yang mengimplementasikan perilaku API di JavaScript. Contoh JavaScript dirancang untuk menunjukkan cara menggunakan variabel sederhana dan konten pesan. Satu contoh menunjukkan cara mendapatkan dan menyetel variabel. Contoh kedua menunjukkan cara mengurai JSON dan membuat pesan dari hasilnya.

Dua contoh JavaScript ada di proxy API:

  • setHeaders.js: JavaScript ini mendapatkan nilai beberapa variabel yang ditetapkan saat proxy API dipanggil. JavaScript menambahkan variabel tersebut ke pesan respons sehingga Anda dapat melihat nilainya untuk setiap permintaan yang Anda buat.
  • minimize.js: JavaScript ini menunjukkan cara menggunakan konten pesan. Ide di balik contoh ini adalah bahwa layanan sering kali menampilkan lebih banyak data daripada yang diperlukan. Jadi, JavaScript mengurai pesan respons, mengekstrak beberapa properti yang menarik, lalu menggunakannya untuk membuat konten pesan respons.

Kode untuk setHeader.js:

context.setVariable("response.header.X-Apigee-Target", context.getVariable("target.name"));
context.setVariable("response.header.X-Apigee-ApiProxyName", context.getVariable("apiproxy.name"));
context.setVariable("response.header.X-Apigee-ProxyName", context.getVariable("proxy.name"));
context.setVariable("response.header.X-Apigee-ProxyBasePath", context.getVariable("proxy.basepath"));
context.setVariable("response.header.X-Apigee-ProxyPathSuffix", context.getVariable("proxy.pathsuffix"));
context.setVariable("response.header.X-Apigee-ProxyUrl", context.getVariable("proxy.url"));

Kode untuk minimize.js:

// Parse the respose from the target.
var res = JSON.parse(context.proxyResponse.content);

// Pull out only the information we want to see in the response.
var minimizedResponse = { city: res.root.city,
                          state: res.root.state };
          
// Set the response variable. 
context.proxyResponse.content = JSON.stringify(minimizedResponse);

Anda dapat mengakses variabel alur di JavaScript melalui objek konteks. Objek ini adalah bagian dari model objek JavaScript Edge. Untuk mengetahui detail tentang model objek, lihat Model objek JavaScript.

Sebelum memulai

Sebelum mempelajari contoh cookbook ini, Anda juga harus memahami konsep dasar berikut:

  • Apa itu kebijakan dan cara melampirkannya ke proxy. Untuk pengantar yang baik tentang kebijakan, lihat Apa itu kebijakan?.
  • Struktur alur proxy, seperti yang dijelaskan dalam Mengonfigurasi alur. Alur memungkinkan Anda menentukan urutan kebijakan yang dieksekusi oleh proxy API. Dalam contoh ini, beberapa kebijakan dibuat dan ditambahkan ke alur proxy API.
  • Cara project proxy API diatur di sistem file Anda, seperti yang dijelaskan dalam Referensi konfigurasi proxy API.
  • Pengetahuan praktis tentang XML, JSON, dan JavaScript. Dalam contoh ini, Anda akan membuat proxy API dan kebijakannya dengan file XML yang ada di sistem file.

Jika telah mendownload kode contoh, Anda dapat menemukan semua file yang dibahas dalam topik ini di folder contoh javascript-cookbook. Bagian berikut membahas contoh kode secara mendetail.

Memahami alur proxy

Agar JavaScript dapat dieksekusi di proxy API, Anda harus melampirkannya ke alur menggunakan lampiran kebijakan yang disebut 'Langkah'. Kebijakan jenis Javascript (perhatikan kapitalisasi) hanya berisi referensi ke nama file JavaScript. Anda mengarahkan kebijakan ke file JavaScript menggunakan elemen ResourceURL.

Misalnya, kebijakan berikut mereferensikan file JavaScript bernama setHeader.js.

<Javascript name='setHeaders' timeLimit='200'>
    <ResourceURL>setHeaders.js</ResourceURL>
</Javascript>

Anda dapat melampirkan kebijakan ini ke alur proxy API seperti jenis kebijakan lainnya. Dengan melampirkan kebijakan ke alur proxy API, Anda menunjukkan tempat JavaScript harus dieksekusi. Dengan demikian, Anda dapat menjalankan JavaScript yang berinteraksi dengan pesan permintaan atau pesan respons saat pesan tersebut 'mengalir' melalui proxy API. Dalam contoh ini, kedua JavaScript dijalankan dalam alur respons, karena kebijakan melakukan dua hal: menetapkan header HTTP pada pesan respons dan 'meminimalkan' pesan respons yang ditampilkan Apigee Edge ke aplikasi yang meminta.

Jika Anda membuka konfigurasi alur ini di UI pengelolaan, Anda akan melihat konfigurasi alur di bawah.

Pilih Proxy Endpoints > default > PostFlow di panel Navigator.

Konfigurasi XML yang sesuai untuk ProxyEndpoint bernama 'default' ditampilkan di bawah. 

<ProxyEndpoint name="default">
  <PostFlow>
    <Response>
      <!-- Steps reference policies under /apiproxy/policies -->
      <!-- First, set a few HTTP headers with variables for this transaction. -->
      <Step><Name>setHeaders</Name></Step>
      <!-- Next, transform the response from XML to JSON for easier parsing with JavaScript -->
      <Step><Name>transform</Name></Step>
      <!-- Finally, use JavaScript to create minimized response with just city and state. -->
      <Step><Name>minimize</Name></Step>
    </Response>
  </PostFlow>
  <HTTPProxyConnection>
        <!-- BasePath defines the network address for this API proxy. See the script 'invoke.sh' to see how the complete URL for this API proxy is constructed.-->
    <BasePath>/javascript-cookbook</BasePath>
     <!-- Set VirtualHost to 'secure' to have this API proxy listen on HTTPS. -->
    <VirtualHost>default</VirtualHost>
  </HTTPProxyConnection>
  <RouteRule name="default">
    <TargetEndpoint>default</TargetEndpoint>
  </RouteRule>
</ProxyEndpoint>

Berikut ringkasan elemen alurnya.

  • <Request> - Elemen <Request> terdiri dari beberapa elemen <Step>. Setiap langkah memanggil salah satu kebijakan yang Anda buat melalui bagian topik ini. Kebijakan ini melampirkan JavaScript ke alur proxy API, dan lokasi lampiran kebijakan menentukan kapan JavaScript dieksekusi.
  • <Response> - Elemen <Response> juga mencakup <Steps>. Langkah-langkah ini juga memanggil kebijakan yang bertanggung jawab untuk memproses respons akhir dari target (yang dalam contoh ini adalah target layanan tiruan Apigee--perhatikan setelan HTTPTargetConnection di bagian /apiproxy/targets/default.xml.)
  • <HTTPProxyConnection> - Menentukan host dan jalur URI yang menentukan alamat jaringan yang dipanggil aplikasi untuk menggunakan API ini.
  • <RouteRule> - Elemen ini menentukan konfigurasi TargetEndpoint mana yang dipanggil oleh ProxyEndpoint.

Menambahkan kode JavaScript ke proxy

JavaScript (seperti skrip Python, file JAR Java, file XSLT, dan sebagainya) disimpan sebagai resource. Saat Anda baru mulai menggunakan JavaScript, sebaiknya simpan file JavaScript di proxy API. Seiring kemajuan Anda, JavaScript harus dibuat seumum dan dapat digunakan kembali mungkin, lalu disimpan di tingkat lingkungan atau organisasi. Dengan demikian, Anda tidak perlu menyimpan file JavaScript yang sama di beberapa proxy API, yang dapat dengan cepat menjadi sulit dikelola.

Untuk mempelajari cara menyimpan resource di tingkat organisasi dan lingkungan, lihat File resource.

Cobalah

Untuk mengetahui petunjuk tentang cara men-deploy dan memanggil proxy, lihat README cookbook JavaScript.

Mengimpor dan men-deploy proxy API

Setelah melakukan perubahan, Anda dapat Menyimpan proxy API di alat pembuat proxy API di UI pengelolaan.

Atau, Anda dapat menjalankan perintah berikut di direktori /api-platform-samples/doc-samples/javascript-cookbook.

$ sh deploy.sh

Menguji JavaScript

Jalankan perintah berikut di direktori /api-platform-samples/doc-samples/javascript-cookbook.

$ sh invoke.sh

Flag curl -v digunakan dalam skrip shell untuk melihat header HTTP pada pesan respons yang diubah oleh JavaScript.

Anda dapat mengirimkan permintaan secara langsung sebagai berikut:

$ curl -v http://{org_name}-test.apigee.net/javascript-cookbook

Jika JavaScript dieksekusi dengan benar, Anda akan melihat respons seperti berikut:

< X-Apigee-Demo-Target: default
< X-Apigee-Demo-ApiProxyName: simple-javascript
< X-Apigee-Demo-ProxyName: default
< X-Apigee-Demo-ProxyBasePath: /javascript-cookbook
< X-Apigee-Demo-ProxyPathSuffix: /xml
< X-Apigee-Demo-ProxyUrl: http://rrt331ea.us-ea.4.apigee.com/javascript-cookbook/xml
 
{"city":"San Jose","state":"CA"}

Sekarang Anda dapat mengubah JavaScript untuk mencoba hal baru, men-deploy ulang proxy API, dan memverifikasi hasil dengan mengirimkan permintaan yang sama. Selalu pastikan Anda men-deploy proxy API yang berisi JavaScript agar perubahan diterapkan.

Error skrip

Anda pasti akan melihat error saat menulis JavaScript. Format error JavaScript yang akan Anda lihat dikeluarkan oleh proxy API ditampilkan di bawah.

{  
   "fault":{  
      "faultstring":"Execution of rewriteTargetUrl failed with error: Javascript runtime error: \"TypeError: Cannot find function getVariable in object TARGET_REQ_FLOW. (rewriteTargetUrl_js#1). at line 1 \"",
      "detail":{  
         "errorcode":"steps.javascript.ScriptExecutionFailed"
      }
   }
}

Kapan JavaScript digunakan

Di Apigee Edge, biasanya ada lebih dari satu cara untuk menerapkan fungsi tertentu. Gunakan kebijakan siap pakai jika memungkinkan, dan hindari keinginan untuk mengodekan semua logika proxy API di JavaScript. Meskipun Apigee Edge memanfaatkan JavaScript yang dikompilasi untuk meningkatkan performa, kemungkinan JavaScript tidak akan berperforma sebaik Kebijakan. JavaScript mungkin lebih sulit dikelola dan di-debug. Cadangkan JavaScript untuk fungsi yang unik sesuai dengan kebutuhan Anda.

Jika performa menjadi masalah untuk fungsi kustom, gunakan Java jika memungkinkan.

Ringkasan

Dalam topik cookbook ini, Anda telah mempelajari cara menyertakan JavaScript dalam konfigurasi proxy API untuk menerapkan perilaku kustom. Perilaku kustom yang diterapkan oleh sampel menunjukkan cara mendapatkan dan variabel, serta cara mengurai JSON dan membuat pesan respons kustom.