Menggunakan komposisi kebijakan

<AssignMessage name="GenerateGeocodingRequest">
  <AssignTo createNew="true" type="request">GeocodingRequest</AssignTo>
  <Set>
    <QueryParams>
      <QueryParam name="address">{request.queryparam.postalcode}</QueryParam>
      <QueryParam name="region">{request.queryparam.country}</QueryParam>
      <QueryParam name="sensor">false</QueryParam>
    </QueryParams>
    <Verb>GET</Verb>
  </Set>
  <!-- Set variables for use in the final response -->
  <AssignVariable>
    <Name>PostalCode</Name>
    <Ref>request.queryparam.postalcode</Ref>
  </AssignVariable>
  <AssignVariable>
    <Name>Country</Name>
    <Ref>request.queryparam.country</Ref>
  </AssignVariable>
</AssignMessage>

Berikut deskripsi singkat tentang elemen-elemen dalam kebijakan ini. Anda dapat membaca selengkapnya tentang hal ini kebijakan di Tetapkan Kebijakan pesan.

• <AssignMessage name> - Memberi nama kebijakan ini. Namanya adalah digunakan saat kebijakan tersebut direferensikan dalam alur.
• &lt;AssignTo&gt; - Membuat variabel bernama yang disebut GeocodingRequest. Variabel ini mengenkapsulasi objek permintaan yang akan dikirim ke backend oleh Kebijakan ServiceInfo.
• &lt;QueryParams&gt; - Menetapkan parameter kueri yang dibutuhkan oleh panggilan API backend. Dalam hal ini, Geocoding API perlu mengetahui lokasi, yang yang ditunjukkan dengan kode pos dan ID negara. Pengguna aplikasi memberikan informasi ini, dan kita cukup mengekstraknya di sini. Parameter sensor diperlukan oleh API, dan benar atau salah, dan kita hanya melakukan {i>hardcode<i} ke {i>false<i} di sini.
• &lt;Verb&gt; - Dalam hal ini, kita membuat permintaan GET sederhana ke Compute Engine API.
• &lt;AssignVariable&gt; - Variabel ini menyimpan nilai yang kita diteruskan ke API. Dalam contoh ini, variabel akan diakses nanti dalam respons dikembalikan ke klien.

Mengirim permintaan dengan Servicecallout

Langkah berikutnya dalam urutan komposisi kebijakan adalah membuat kebijakan ServiceCallout. Tujuan Kebijakan ServiceInfo, yang tercantum di bawah, mengirimkan objek permintaan yang kita buat di kebijakan MenetapkanMessage sebelumnya ke layanan Google Geocoding, dan menyimpan hasilnya dalam variabel yang disebut GeocodingResponse.

<ServiceCallout name="ExecuteGeocodingRequest">
  <Request variable="GeocodingRequest"/>
  <Response>GeocodingResponse</Response>
  <HTTPTargetConnection>
    <URL>http://maps.googleapis.com/maps/api/geocode/json</URL>
  </HTTPTargetConnection>
</ServiceCallout>

Berikut deskripsi singkat tentang elemen-elemen kebijakan ini.

• &lt;ServiceCallout&gt; - Seperti halnya kebijakan sebelumnya, kebijakan ini memiliki nama.
• <Variabel permintaan> - Ini adalah variabel yang dibuat di kebijakan MenetapkanMessage. Fungsi ini mengenkapsulasi permintaan yang menuju ke API backend.
• &lt;Response&gt; - Elemen ini memberi nama variabel tempat respons disimpan. Seperti yang akan Anda lihat, variabel ini nanti akan diakses oleh {i>ExtractVariables<i} lebih lanjut.
• &lt;HTTPTargetConnection&gt; - Menentukan URL target backend Compute Engine API. Dalam hal ini, kita menetapkan bahwa API akan menampilkan respons JSON.

Sekarang kita memiliki dua kebijakan, satu kebijakan yang menentukan informasi permintaan yang diperlukan untuk menggunakan backend API (Geocoding API Google), dan yang kedua yang benar-benar mengirim permintaan ke API backend. Selanjutnya, kita akan menangani responsnya.

<ExtractVariables name="ParseGeocodingResponse">
  <Source>GeocodingResponse</Source>
  <VariablePrefix>geocoderesponse</VariablePrefix>
  <JSONPayload>
    <Variable name="latitude">
       <JSONPath>$.results[0].geometry.location.lat</JSONPath>
    </Variable>
    <Variable name="longitude">
       <JSONPath>$.results[0].geometry.location.lng</JSONPath>
    </Variable>
  </JSONPayload>
</ExtractVariables>

Elemen utama kebijakan ExtractVariable adalah:

• <ExtractVariables name> - Sekali lagi, nama kebijakan digunakan untuk merujuk pada kebijakan saat digunakan dalam alur.
• &lt;Source&gt; - Menentukan variabel respons yang telah kita buat kebijakan ServiceInfo. Ini adalah variabel yang digunakan kebijakan ini untuk mengekstrak data.
• &lt;VariablePrefix&gt; - Awalan variabel menentukan namespace untuk variabel lain yang dibuat dalam kebijakan ini. Awalan dapat berupa nama apa pun, kecuali untuk nama yang dicadangkan yang didefinisikan oleh Edge's variabel yang telah ditetapkan.
• &lt;JSONPayload&gt; - Elemen ini mengambil data respons yang menarik bagi kita dan memasukkannya ke dalam variabel bernama. Faktanya, Geocoding API menghasilkan banyak lebih banyak informasi daripada lintang dan bujur. Namun, ini adalah satu-satunya nilai yang kita yang diperlukan untuk sampel ini. Anda dapat melihat rendering lengkap JSON yang ditampilkan oleh Geocoding API dalam direktori API dokumentasi tambahan. Nilai geometry.location.lat dan geometry.location.lng hanya dua dari sekian banyak kolom di objek JSON yang ditampilkan.

Ini mungkin tidak jelas, tetapi penting untuk melihat bahwa ExtractVariables menghasilkan dua variabel yang namanya terdiri dari awalan variabel (respons geocode) dan nama variabel yang ditentukan dalam kebijakan. Variabel-variabel ini disimpan dalam Proxy API dan akan tersedia untuk kebijakan lain dalam alur proxy, seperti yang akan Anda baca. Variabelnya adalah:

• geocoderesponse.latitude
• geocoderesponse.longitude

Sebagian besar pekerjaan kini sudah selesai. Kami telah membuat gabungan dari tiga kebijakan yang membentuk permintaan backend, memanggil API backend, dan mengurai data JSON yang ditampilkan. Pada langkah terakhir, kita akan memasukkan data dari bagian alur ini ke kebijakan MenetapkanMessage lain, panggil backend kedua API (Google Elevation API), dan mengembalikan data yang digabungkan ke developer aplikasi.

<AssignMessage name="AssignElevationParameters">
<Remove>
    <QueryParams>
      <QueryParam name="country"/>
      <QueryParam name="postalcode"/>
    </QueryParams>
  </Remove>
  <Set>
    <QueryParams>
      <QueryParam name="locations">{geocoderesponse.latitude},{geocoderesponse.longitude}</QueryParam>
      <QueryParam name="sensor">false</QueryParam>
    </QueryParams>
  </Set>
</AssignMessage>

Jika Anda memeriksa Google Elevation API, Anda akan melihat bahwa itu membutuhkan dua parameter kueri. Yang pertama disebut locations serta nilainya adalah lintang dan bujur (nilai yang dipisahkan koma). Parameter lainnya adalah sensor, yang wajib ada dan harus menjadi benar atau salah. Hal yang paling penting untuk diperhatikan pada tahap ini adalah bahwa permintaan pesan yang kita buat di sini tidak memerlukan ServiceInfo. Kita tidak perlu memanggil metode API dari ServiceInfo pada tahap ini karena kita bisa memanggil API backend dari TargetEndpoint. Jika Anda memikirkannya, kita memiliki semua data yang diperlukan untuk memanggil Google Elevations Pesan permintaan yang dihasilkan dalam langkah ini tidak memerlukan ServiceInfo, karena yang dibuat untuk pipeline permintaan utama, sehingga hanya akan diteruskan oleh ProxyEndpoint ke TargetEndpoint, mengikuti RouteRule yang dikonfigurasi untuk proxy API ini. TargetEndpoint mengelola koneksi dengan API jarak jauh. (Ingat bahwa URL untuk elevasi API ditentukan di HTTPConnection untuk TargetEndpoint. API Elevation dokumentasi jika Anda ingin tahu lebih banyak. QueryParams yang kita simpan sebelumnya, country dan postalcode tidak lagi diperlukan, jadi kita menghapusnya di sini.

Jeda singkat: Kembali ke alur

Pada tahap ini, Anda mungkin bertanya-tanya mengapa kami tidak membuat kebijakan ServiceInfo lain. Sesudah semua, kita membuat pesan lain. Bagaimana pesan itu dikirim ke target, jaringan Google Elevation API? Jawabannya ada di <RouteRule> elemen alur. &lt;RouteRule&gt; menentukan apa yang harus dilakukan dengan pesan permintaan yang tersisa setelah <Request> bagian dari alurnya telah dieksekusi. TargetEndpoint yang ditentukan oleh <RouteRule> ini memberi tahu Proxy API untuk mengirimkan pesan ke http://maps.googleapis.com/maps/api/elevation/xml.

Jika Anda mendownload contoh proxy API, Anda dapat menemukan TargetProxy XML dalam file doc-samples/policy-mashup-cookbook/apiproxy/targets/default.xml.

<TargetEndpoint name="default">
  <HTTPTargetConnection>
    <!-- This is where we define the target. For this sample we just use a simple URL. -->
    <URL>http://maps.googleapis.com/maps/api/elevation/xml</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

Sekarang, kita hanya perlu memproses respons dari Google Elevation API dan kita selesai.

$ curl "http://{myorg}-test.apigee.net/policy-mashup-cookbook?country=us&postalcode=08008"

Respons mencakup lokasi geocode untuk pusat kode pos yang disediakan oleh pengguna akhir aplikasi, dikombinasikan dengan elevasi di lokasi yang di-geocode tersebut. Data tersebut yang diambil dari dua API backend, digabungkan dengan kebijakan yang dilampirkan ke proxy API, dan yang dikembalikan ke klien dalam satu respons.

{  
   "country":"us",
   "postalcode":"08008",
   "elevation":{  
      "meters":0.5045232,
      "feet":1.6552599030345978
   },
   "location":{  
      "latitude":39.75007129999999,
      "longitude":-74.1357407
   }
}

Ringkasan

Topik buku resep ini menjelaskan cara menggunakan pola komposisi kebijakan untuk membuat mashup data dari beberapa sumber backend. Komposisi kebijakan adalah pola umum yang digunakan di API pengembangan proxy untuk menambahkan fungsi materi iklan ke API Anda.