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.
- <Request> - <Request> terdiri dari beberapa <Step> 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.
- <Response> - <Respons> juga menyertakan <Langkah>. Langkah-langkah ini juga memanggil kebijakan yang bertanggung jawab untuk memproses respons dari endpoint target (Google Elevation API).
- <HttpProxyConnection> - Elemen ini menentukan detail tentang cara aplikasi akan terhubung ke proxy API ini, termasuk <BasePath>, yang menentukan cara API ini akan dipanggil.
- <RouteRule> - 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.
- <AssignTo> - Membuat variabel bernama yang disebut GeocodingRequest. Variabel ini mengenkapsulasi objek permintaan yang akan dikirim ke backend oleh Kebijakan ServiceInfo.
- <QueryParams> - 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. - <Verb> - Dalam hal ini, kita membuat permintaan GET sederhana ke Compute Engine API.
- <AssignVariable> - 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.
- <ServiceCallout> - 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.
- <Response> - Elemen ini memberi nama variabel tempat respons disimpan. Seperti yang akan Anda lihat, variabel ini nanti akan diakses oleh {i>ExtractVariables<i} lebih lanjut.
- <HTTPTargetConnection> - 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.
- <Source> - Menentukan variabel respons yang telah kita buat kebijakan ServiceInfo. Ini adalah variabel yang digunakan kebijakan ini untuk 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 didefinisikan oleh Edge's variabel yang telah ditetapkan.
- <JSONPayload> - 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. <RouteRule>
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.