Menggunakan komposisi kebijakan

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

Dalam topik ini, Anda akan mempelajari cara membuat mashup menggunakan komposisi kebijakan. Komposisi kebijakan adalah pola proxy Apigee yang memungkinkan Anda menggabungkan hasil dari beberapa backend target menjadi satu respons menggunakan kebijakan.

Untuk ringkasan umum tentang komposisi kebijakan, lihat "Pola komposisi kebijakan" di Cookbook Proxy API yang sama.

Download dan coba kode contoh

Tentang contoh buku resep ini

Contoh buku resep ini mengilustrasikan pola proxy API yang disebut komposisi kebijakan. Pola ini menyediakan satu cara (ada cara lain) untuk menggabungkan data dari beberapa sumber backend. Secara lebih umum, topik ini menunjukkan bagaimana kebijakan dapat digabungkan dan dirantai bersama untuk memberikan hasil yang diinginkan. Untuk gambaran umum tentang pola ini dan yang terkait lainnya, lihat Buku Resep Proxy API yang sama.

Contoh yang dibahas di sini menggunakan komposisi kebijakan untuk menggabungkan data dari kedua API publik:

  • Geocoding Google API: API ini mengonversi alamat (seperti "1600 Amphitheatre Parkway, Mountain View, CA") ke dalam koordinat geografis (seperti lintang 37,423021 dan bujur -122,083739).
  • Elevasi Google API API ini menyediakan antarmuka sederhana untuk melakukan kueri lokasi di atas bumi untuk elevasi layanan otomatis dan data skalabel. Dalam contoh ini, koordinat yang ditampilkan dari Geocoding API akan digunakan sebagai input ke dalam API ini.

Developer aplikasi akan memanggil proxy API ini dengan dua parameter kueri, yaitu kode pos dan negara ID:

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

Respons adalah objek JSON yang menyertakan lokasi yang di-geocode (lintang/bujur) untuk bagian tengah area kode pos yang diberikan dikombinasikan dengan ketinggian pada kode geocode lokasi HTTP/HTTPS.

{  
   "ElevationResponse":{  
      "status":"OK",
      "result":{  
         "location":{  
            "lat":"39.7500713",
            "lng":"-74.1357407"
         },
         "elevation":"0.5045232",
         "resolution":"76.3516159"
      }
   }
}

Sebelum memulai

Jika Anda ingin membaca ringkasan singkat tentang pola komposisi kebijakan, buka "Kebijakan pola komposisi" di Cookbook Proxy API yang sama.

Sebelum mengeksplorasi contoh buku resep ini, Anda juga harus memahami dasar-dasar konsep:

  • Apa yang dimaksud dengan kebijakan dan cara melampirkannya ke proxy. Sebagai pengantar yang baik tentang kebijakan, lihat Apa yang kebijakan?.
  • Struktur alur proxy API, seperti yang dijelaskan dalam Mengonfigurasi alur. Flow 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 di Referensi konfigurasi proxy API. Topik buku resep ini menunjukkan pengembangan lokal (file berbasis sistem) bukan pengembangan berbasis cloud, yang mengharuskan Anda menggunakan UI pengelolaan mengembangkan proxy API.
  • Penggunaan validasi kunci API. Ini adalah bentuk keamanan berbasis aplikasi paling sederhana yang bisa Anda melakukan konfigurasi untuk API. Untuk informasi selengkapnya, lihat API . Anda juga dapat mengikuti kursus API dengan memerlukan kunci API.
  • Pengetahuan praktis tentang XML. Dalam contoh ini, kami membangun proxy API dan kebijakan dengan file XML yang berada di sistem file.

Jika telah mengunduh kode contoh, Anda dapat menemukan semua file yang dibahas dalam topik di folder contoh mashup-policy-cookbook. Bagian berikut membahas kode contoh secara rinci.

Santai dan menerima keadaan

Sebelum beralih ke kebijakan, mari kita lihat alur utama dari contoh kami Proxy API. Alur XML, yang ditampilkan di bawah, memberi tahu banyak hal tentang proxy ini, kebijakan yang digunakan, dan di mana kebijakan-kebijakan ini disebut.

Dalam contoh download, Anda dapat menemukan XML ini dalam file doc-samples/policy-mashup-cookbook/apiproxy/proxies/default.xml.

<ProxyEndpoint name="default">
  <Flows>
    <Flow name="default">
      <Request>
            <!-- Generate request message for the Google Geocoding API -->
            <Step><Name>GenerateGeocodingRequest</Name></Step>
            <!-- Call the Google Geocoding API -->
            <Step><Name>ExecuteGeocodingRequest</Name></Step>
            <!-- Parse the response and set variables -->
            <Step><Name>ParseGeocodingResponse</Name></Step>
            <!-- Generate request message for the Google Elevation API -->
            <Step><Name>AssignElevationParameters</Name></Step>
      </Request>
      <Response>
            <!-- Parse the response message from the Elevation API -->
            <Step><Name>ParseElevationResponse</Name></Step>
            <!-- Generate the final JSON-formatted response with JavaScript -->
            <Step><Name>GenerateResponse</Name></Step>
      </Response>
    </Flow>
  </Flows>

  <HTTPProxyConnection>
    <!-- Add a base path to the ProxyEndpoint for URI pattern matching-->
    <BasePath>/policy-mashup-cookbook</BasePath>
    <!-- Listen on both HTTP and HTTPS endpoints -->
    <VirtualHost>default</VirtualHost>
    <VirtualHost>secure</VirtualHost>
  </HTTPProxyConnection>
  <RouteRule name="default">
    <!-- Connect ProxyEndpoint to named TargetEndpoint under /targets -->
    <TargetEndpoint>default</TargetEndpoint>
  </RouteRule>
</ProxyEndpoint>

Berikut adalah ringkasan elemen flow.

  • &lt;Request&gt; - <Request> terdiri dari beberapa &lt;Step&gt; yang kurang penting. Setiap langkah memanggil salah satu kebijakan yang akan kita buat hingga topik ini. Kebijakan ini berkaitan dengan cara membuat pesan permintaan, mengirimkannya, dan menguraikan respons. Pada akhir topik ini, Anda akan memahami peran masing-masing kebijakan izin yang relevan.
  • &lt;Response&gt; - <Respons> juga menyertakan <Langkah>. Langkah-langkah ini juga memanggil kebijakan yang bertanggung jawab untuk memproses respons dari endpoint target (Google Elevation API).
  • &lt;HttpProxyConnection&gt; - Elemen ini menentukan detail tentang cara aplikasi akan terhubung ke proxy API ini, termasuk <BasePath>, yang menentukan cara API ini akan dipanggil.
  • &lt;RouteRule&gt; - Elemen ini menentukan hal yang akan langsung terjadi setelah pesan permintaan masuk diproses. Dalam hal ini, TargetEndpoint dipanggil. Kita akan membahas lebih lanjut langkah penting ini nanti dalam topik ini.

Membuat kebijakan

Bagian berikut membahas setiap kebijakan yang membentuk komposisi kebijakan ini contoh.

Membuat MenetapkanMessage pertama kebijakan

Kebijakan AssignMessage pertama, tercantum di bawah ini, membuat pesan permintaan yang akan dikirim ke Google Geocoding layanan.

Mari kita mulai dengan kode kebijakan, lalu kami akan menjelaskan elemennya secara lebih mendetail. Di kolom contoh download, Anda dapat menemukan XML ini dalam file doc-samples/policy-mashup-cookbook/apiproxy/policies/GenerateGeocodingRequest.xml.

<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.

Seperti sebelumnya, mari kita lihat kodenya terlebih dahulu. Berikut penjelasan detailnya. Anda dapat membaca informasi selengkapnya tentang kebijakan ini di Panggilan Layanan kebijakan kami. Dalam contoh download, Anda dapat menemukan XML ini dalam file doc-samples/policy-mashup-cookbook/apiproxy/policies/ExecuteGeocodingRequest.xml.

<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.

Uraikan respons dengan ExtractVariables

Kebijakan ExtractVariables menyediakan mekanisme sederhana untuk mengurai konten dari pesan respons yang diperoleh dari kebijakan ServiceInfo. ExtractVariables dapat digunakan untuk JSON atau XML, atau dapat digunakan untuk mengekstrak konten dari jalur URI, header HTTP, kueri parameter, dan parameter formulir.

Berikut adalah daftar kebijakan ExtractVariables. Anda dapat membaca selengkapnya tentang kebijakan ini di Mengekstrak Variabel kebijakan kami. Dalam contoh download, Anda dapat menemukan XML ini dalam file doc-samples/policy-mashup-cookbook/apiproxy/policies/ParseGeocodingResponse.xml.

<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.

Membuat yang kedua meminta dengan MenetapkanMessage

Kebijakan MenetapkanMessage berikut menggunakan variabel yang ditampilkan dari backend pertama (Google Geocoding) yang kita simpan, dan menghubungkannya ke permintaan yang ditujukan untuk API kedua (Google Ketinggian). Seperti disebutkan sebelumnya, variabel ini adalah geocoderesponse.latitude dan geocoderesponse.longitude.

Dalam contoh download, Anda dapat menemukan XML ini dalam file doc-samples/policy-mashup-cookbook/apiproxy/policies/AssignElevationParameters.xml.

<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.

Konversikan respons dari XML menjadi JSON

Dalam contoh ini, respons dari Google Elevation API ditampilkan sebagai XML. Untuk "tambahan kredit", mari tambahkan satu kebijakan lagi ke komposit kita untuk mengubah respons dari XML ke JSON.

Contoh ini menggunakan kebijakan JavaScript bernama GenerateResponse, dengan file resource yang berisi kode JavaScript, untuk melakukan konversi. Yang ditampilkan di bawah ini adalah definisi kebijakan GenerateResponse:

<Javascript name="GenerateResponse" timeout="10000">
  <ResourceURL>jsc://GenerateResponse.js</ResourceURL>
</Javascript>

File resource GenerateResponse.js mencakup JavaScript yang digunakan untuk melakukan konversi. Anda bisa melihat kode itu di file doc-samples/policy-mashup-cookbook/apiproxy/resources/JSC/GenerateResponse.js.

Apigee juga menyediakan kebijakan siap pakai, XMLToJSON, untuk mengonversi XML ke JSON. Anda dapat edit ProxyEndpoint untuk menggunakan kebijakan xmltojson yang ditampilkan di bawah sebagai gantinya.

<XMLToJSON name="xmltojson">
  <Options>
  </Options>
  <OutputVariable>response</OutputVariable>
  <Source>response</Source>
</XMLToJSON>

Menguji contoh

Jika Anda belum melakukannya, cobalah untuk mendownload, men-deploy, dan menjalankan policy-mashup-cookbook, yang dapat Anda temukan di folder doc-samples di GitHub repositori contoh Apigee Edge. Hanya ikuti petunjuk di file README di folder policy-mashup-cookbook. Atau, ikuti petunjuk singkat di sini: Menggunakan contoh proxy API.

Ringkasnya, Anda dapat memanggil API gabungan seperti berikut. Ganti {myorg} Anda dengan nama organisasi:

$ 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.