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 elemen dalam kebijakan ini. Anda dapat membaca lebih lanjut kebijakan ini di kebijakan Pesan Penetapan.

• <AssignMessage name> - Memberi nama 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 dinyatakan dengan kode pos dan ID negara. Pengguna aplikasi memberikan informasi ini, dan kami hanya mengekstraknya di sini. Parameter sensor diperlukan oleh API, dan berupa benar atau salah, dan kita hanya meng-hardcode-nya ke salah di sini.
• <Verb> - Dalam hal ini, kita membuat permintaan GET sederhana ke API.
• <AssignVariable> - Variabel ini menyimpan nilai yang diteruskan 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, mengirimkan objek permintaan yang kita buat di kebijakan AssignMessage 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 elemen kebijakan ini.

• <ServiceCallout> - Seperti kebijakan sebelumnya, kebijakan ini memiliki nama.
• <Request variable> - Ini adalah variabel yang dibuat di kebijakan AssignMessage. Objek ini merangkum permintaan yang dikirim ke API backend.
• <Response> - Elemen ini memberi nama variabel tempat respons disimpan. Seperti yang akan Anda lihat, variabel ini akan diakses nanti oleh kebijakan ExtractVariables.
• <HTTPTargetConnection> - Menentukan URL target backend API. Dalam hal ini, kita menentukan bahwa API menampilkan respons JSON.

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

<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.
• <Source> - Menentukan variabel respons yang kita buat di kebijakan ServiceCallout. Ini adalah variabel dari kebijakan yang mengekstrak data.
• <VariablePrefix> - Awalan variabel menentukan namespace untuk variabel lain yang dibuat dalam kebijakan ini. Awalan dapat berupa nama apa pun, kecuali nama yang dicadangkan yang ditentukan oleh variabel standar Edge.
• <JSONPayload> - Elemen ini mengambil data respons yang menarik bagi kita dan menempatkannya ke dalam variabel bernama. Faktanya, Geocoding API menampilkan lebih banyak informasi daripada lintang dan bujur. Namun, ini adalah satu-satunya nilai yang kita butuhkan untuk contoh ini. Anda dapat melihat rendering lengkap JSON yang ditampilkan oleh Geocoding API di dokumentasi API. Nilai geometry.location.lat dan geometry.location.lng hanyalah dua dari banyak kolom dalam objek JSON yang ditampilkan.

Mungkin tidak terlihat jelas, tetapi penting untuk melihat bahwa ExtractVariables menghasilkan dua variabel yang namanya 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 kini telah selesai. Kita telah membuat gabungan tiga kebijakan yang membentuk permintaan, memanggil backend API, dan mengurai data JSON yang ditampilkan. Pada langkah terakhir, kita akan memasukkan data dari bagian alur ini ke kebijakan AssignMessage lain, memanggil backend API kedua (Google Elevation API), dan menampilkan data gabungan kita 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 API ini memerlukan dua parameter kueri. Yang pertama disebut locations dan nilainya adalah lintang dan bujur (nilai yang dipisahkan koma). Parameter lainnya adalah sensor, yang wajib diisi dan harus berupa benar atau salah. Hal terpenting yang perlu diperhatikan pada tahap ini adalah bahwa pesan permintaan yang kita buat di sini tidak memerlukan ServiceCallout. Kita tidak perlu memanggil API kedua dari ServiceCallout pada saat ini karena kita dapat memanggil API backend dari TargetEndpoint proxy. Jika Anda memikirkannya, kita memiliki semua data yang diperlukan untuk memanggil Google Elevation API. Pesan permintaan yang dibuat pada langkah ini tidak memerlukan ServiceCallout, karena permintaan 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. (Ingatlah bahwa URL untuk Elevation API ditentukan di HTTPConnection untuk TargetEndpoint.) Dokumentasi Elevation API jika Anda ingin mengetahui lebih lanjut. 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 kita tidak membuat kebijakan ServiceCallout lain. Setelah semuanya, kita membuat pesan lain. Bagaimana pesan tersebut dikirim ke target, Google Elevation API? Jawabannya ada di elemen <RouteRule> dalam alur. <RouteRule> menentukan tindakan yang harus dilakukan terhadap pesan permintaan yang tersisa setelah bagian <Request> dari alur 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 proxy API contoh, 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 kita selesai.

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

Respons mencakup lokasi yang di-geocoding untuk pusat kode pos yang diberikan oleh pengguna akhir aplikasi, yang dikombinasikan dengan ketinggian di lokasi yang di-geocoding tersebut. Data diambil dari dua API backend, digabungkan dengan kebijakan yang dilampirkan 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 cookbook 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 kreatif ke API Anda.