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, cara mengurai respons JSON, dan menampilkan subset propertinya ke aplikasi yang meminta.

Download dan coba kode contoh

Tentang contoh buku resep ini

Contoh Cookbook ini menggambarkan pola proxy API tempat Anda menerapkan perilaku API di JavaScript. Contoh JavaScript didesain untuk menunjukkan cara bekerja dengan variabel sederhana dan konten pesan. Satu contoh menunjukkan cara mendapatkan dan menetapkan variabel. Contoh kedua menunjukkan cara mengurai JSON dan membuat pesan dari hasilnya.

Dua contoh JavaScript berada di proxy API:

  • setHeaders.js: JavaScript ini mendapatkan nilai dari beberapa variabel yang ditetapkan saat proxy API dipanggil. JavaScript akan menambahkan variabel tersebut ke pesan respons sehingga Anda dapat melihat nilainya untuk setiap permintaan yang dibuat.
  • minimize.js: JavaScript ini menunjukkan cara menangani konten pesan. Gagasan di balik contoh ini adalah bahwa layanan sering kali menampilkan lebih banyak data daripada yang diperlukan. Jadi, JavaScript akan 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 Edge JavaScript. Untuk mengetahui detail tentang model objek, lihat model objek JavaScript.

Sebelum memulai

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

  • Pengertian kebijakan dan cara melampirkannya ke proxy. Untuk pengantar kebijakan yang bagus, lihat Apa itu kebijakan?.
  • Struktur alur proxy, seperti yang dijelaskan dalam Mengonfigurasi alur. Alur memungkinkan Anda menentukan urutan kebijakan yang dijalankan oleh proxy API. Dalam contoh ini, beberapa kebijakan dibuat dan ditambahkan ke alur proxy API.
  • Cara project proxy API diatur pada sistem file Anda, seperti yang dijelaskan dalam Referensi konfigurasi proxy API.
  • Pengetahuan tentang XML, JSON, dan JavaScript. Dalam contoh ini, Anda membangun proxy API dan kebijakannya dengan file XML yang berada pada sistem file.

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

Memahami alur proxy

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

Misalnya, kebijakan berikut merujuk ke file JavaScript yang bernama setHeader.js.

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

Anda dapat melampirkan kebijakan ini ke alur proxy API seperti yang dilakukan pada jenis kebijakan lainnya. Dengan melampirkan kebijakan ke alur proxy API, Anda menunjukkan tempat JavaScript harus dijalankan. Hal ini memungkinkan Anda menjalankan JavaScript yang berinteraksi dengan pesan permintaan atau pesan respons saat pesan tersebut 'mengalir' melalui proxy API. Dalam contoh ini, kedua JavaScript dieksekusi 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 membuka konfigurasi flow ini di UI pengelolaan, Anda akan melihat konfigurasi flow di bawah.

Pilih Proxy Endpoints > default > PostFlow di panel Navigator.

Konfigurasi XML terkait untuk ProxyEndpoint yang bernama 'default' ditunjukkan di bawah ini.

<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 adalah ringkasan elemen alurnya.

  • <Request> - Elemen <Request> terdiri dari beberapa elemen <Step>. Setiap langkah akan memanggil salah satu kebijakan yang Anda buat hingga seluruh 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 menetapkan 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. Jika Anda baru mulai menggunakan JavaScript, paling mudah untuk menyimpan file JavaScript di proxy API. Saat Anda melanjutkan, JavaScript harus dibuat seumum mungkin dan sebisa mungkin dapat digunakan kembali, 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 tidak dapat dikelola.

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

Cobalah

Untuk mendapatkan petunjuk tentang cara men-deploy dan memanggil proxy, lihat README buku resep JavaScript.

Mengimpor dan men-deploy proxy API

Setelah melakukan perubahan, Anda dapat Menyimpan proxy API di alat builder 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 dimodifikasi oleh JavaScript.

Anda dapat langsung mengirimkan permintaan sebagai berikut:

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

Jika JavaScript dijalankan 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"}

Kini Anda dapat mengubah JavaScript untuk mencoba hal baru, men-deploy ulang proxy API, dan memverifikasi hasilnya 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 diterbitkan oleh proxy API ditampilkan di bawah ini.

{  
   "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 menggunakan JavaScript

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

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

Ringkasan

Dalam topik buku resep ini, Anda telah mempelajari cara JavaScript dapat disertakan dalam konfigurasi proxy API untuk mengimplementasikan perilaku kustom. Perilaku kustom yang diterapkan oleh contoh ini menunjukkan cara mendapatkan variabel dan cara mengurai JSON serta membuat pesan respons kustom.