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 dalam kebijakan ini. Anda dapat membaca kebijakan ini selengkapnya di bagian Tetapkan kebijakan Pesan.

• <AssignMessage name> - Memberi nama pada kebijakan ini. Nama ini digunakan saat kebijakan dirujuk dalam alur.
• <AssignTo> - Membuat variabel bernama GeocodingRequest. Variabel ini mengenkapsulasi objek permintaan yang akan dikirim ke backend oleh kebijakan ServiceCallout.
• <QueryParams> - Menetapkan parameter kueri yang diperlukan oleh panggilan API backend. Dalam hal ini, Geocoding API perlu mengetahui lokasi, yang ditunjukkan dengan kode pos, dan ID negara. Pengguna aplikasi memberikan informasi ini, dan kami cukup mengekstraknya di sini. Parameter sensor diperlukan oleh API, dan dapat bernilai benar (true) atau salah (false), dan kita hanya melakukan hardcode ke salah (false) di sini.
• <Verb> - Dalam hal ini, kita membuat permintaan GET sederhana ke API.
• <AssignVariable> - Variabel ini menyimpan nilai yang kita teruskan ke API. Dalam contoh ini, variabel akan diakses nanti dalam respons yang ditampilkan ke klien.

Mengirim permintaan dengan ServiceCallout

Langkah berikutnya dalam urutan komposisi kebijakan adalah membuat kebijakan ServiceCallout. Kebijakan ServiceCallout, yang tercantum di bawah, mengirim objek permintaan yang kami buat di kebijakan TetapkanMessage sebelumnya ke layanan Google Geocoding, dan menyimpan hasilnya dalam variabel bernama 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 kebijakan ini.

• <ServiceCallout> - Kebijakan ini memiliki nama sama seperti kebijakan sebelumnya.
• <Request Variable> - Ini adalah variabel yang dibuat dalam kebijakan AssignMessage. API ini mengenkapsulasi permintaan yang menuju ke API backend.
• <Response> - Elemen ini menamai variabel tempat respons disimpan. Seperti yang akan Anda lihat, variabel ini akan diakses nanti oleh kebijakan ExtractVariables.
• <HTTPTargetConnection> - Menentukan URL target dari API backend. Dalam hal ini, kita menetapkan bahwa API menampilkan respons JSON.

Sekarang kita memiliki dua kebijakan, kebijakan pertama yang menentukan informasi permintaan yang diperlukan untuk menggunakan backend API (Google Geocoding API), dan kebijakan kedua yang benar-benar mengirimkan 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 ke kebijakan tersebut saat digunakan dalam flow.
• <Source> - Menentukan variabel respons yang telah dibuat di kebijakan ServiceCallout. Data ini adalah variabel tempat kebijakan ini mengekstrak data.
• <VariablePrefix> - Awalan variabel menentukan namespace untuk variabel lain yang dibuat dalam kebijakan ini. Awalan dapat berupa nama apa pun, kecuali untuk nama yang dicadangkan yang ditentukan oleh variabel yang telah ditetapkan Edge.
• <JSONPayload> - Elemen ini mengambil data respons yang menarik bagi kita dan memasukkannya ke dalam variabel bernama. Faktanya, Geocoding API menampilkan lebih banyak informasi daripada lintang dan bujur. Namun, ini adalah satu-satunya nilai yang kita perlukan untuk sampel ini. Anda dapat melihat rendering lengkap dari JSON yang ditampilkan oleh Geocoding API di dokumentasi API. Nilai geometry.location.lat dan geometry.location.lng hanyalah dua dari sekian banyak kolom dalam objek JSON yang ditampilkan.

Mungkin tidak jelas, tetapi penting untuk diperhatikan bahwa ExtractVariables menghasilkan dua variabel dengan namanya yang terdiri dari awalan variabel (geocoderesponse) dan nama variabel sebenarnya yang ditentukan dalam kebijakan. Variabel ini disimpan di proxy API dan akan tersedia untuk kebijakan lain dalam alur proxy, seperti yang akan Anda lihat. Variabelnya adalah:

• geocoderesponse.latitude
• geocoderesponse.longitude

Sebagian besar pekerjaan sekarang sudah selesai. Kami telah membuat gabungan dari tiga kebijakan yang membentuk permintaan, memanggil API backend, dan mengurai data JSON yang ditampilkan. Pada langkah terakhir, kita akan memasukkan data dari bagian alur ini ke kebijakan BiddingMessage lain, memanggil API backend kedua (Google Elevation API), dan menampilkan data gabungan 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 dibutuhkan dua parameter kueri. Yang pertama disebut locations dan nilainya adalah lintang dan bujur (nilai yang dipisahkan koma). Parameter lainnya adalah sensor, yang diperlukan dan harus bernilai benar atau salah. Hal terpenting yang perlu diperhatikan pada tahap ini adalah pesan permintaan yang kita buat di sini tidak memerlukan ServiceCallout. Kita tidak perlu memanggil API kedua dari ServiceCallout di tahap ini karena kita dapat memanggil API backend dari TargetEndpoint proxy. Jika Anda memikirkannya, kita memiliki semua data yang diperlukan untuk memanggil Google Elevations API. Pesan permintaan yang dihasilkan pada langkah ini tidak memerlukan ServiceCallout, karena permintaan yang dibuat untuk pipeline permintaan utama 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 Elevation API ditentukan dalam HTTPConnection untuk TargetEndpoint. Elevation API jika Anda ingin mengetahui lebih lanjut. QueryParams yang disimpan sebelumnya, country dan postalcode, tidak lagi diperlukan, sehingga kami menghapusnya di sini.

Jeda singkat: Kembali ke alur

Pada tahap ini, Anda mungkin bertanya-tanya mengapa kami tidak membuat kebijakan ServiceCallout lainnya. Lagi pula, kami membuat pesan lain. Bagaimana pesan tersebut dikirimkan ke target, Google Elevation API? Jawabannya ada dalam elemen <RouteRule> alur. <RouteRule> menentukan tindakan yang harus dilakukan dengan pesan permintaan yang tersisa setelah bagian <Request> dari alur dijalankan. 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 XML TargetProxy 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 selesai.

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

Responsnya mencakup lokasi yang di-geocode untuk pusat kode pos yang diberikan oleh pengguna akhir aplikasi, dikombinasikan dengan elevasi pada lokasi yang di-geocoding tersebut. Data tersebut diambil dari dua API backend, yang digabungkan dengan kebijakan yang terpasang ke proxy API, dan ditampilkan 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 dalam pengembangan proxy API untuk menambahkan fungsi materi iklan ke API Anda.