Mengekspos layanan SOAP sebagai proxy API

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

Topik ini menjelaskan cara membuat proxy API untuk layanan web berbasis SOAP. Anda dapat membuat dua jenis proxy SOAP di Edge. Satu menghasilkan antarmuka RESTful ke layanan SOAP backend dan yang lainnya melakukan "pass through" pesan SOAP ke backend. Kedua teknik tersebut dijelaskan dalam topik ini.

Video ini memberikan demo menyeluruh tentang cara mengubah layanan SOAP menjadi layanan REST dengan Apigee Edge menggunakan wizard proxy API. Namun, jika ingin memiliki kontrol lebih besar atas transformasi SOAP-ke-REST, Anda dapat membuat proxy menggunakan kebijakan. Untuk informasi selengkapnya, lihat Tutorial: Pembuatan proxy SOAP-to-REST API secara manual di Apigee Edge.

Membuat proxy RESTful API ke layanan berbasis SOAP

Bagian ini menjelaskan cara membuat proxy SOAP API RESTful dengan opsi REST to SOAP to REST di wizard Build a Proxy.

Ringkasan

Opsi REST to SOAP to REST memproses WSDL untuk membuat proxy API RESTful. Edge menentukan dari WSDL operasi yang didukung layanan, parameter input, dan sebagainya. Edge "menebak" metode HTTP yang akan digunakan untuk setiap operasi. Biasanya, Edge menerjemahkan operasi menjadi permintaan GET, yang memiliki keunggulan dapat disimpan dalam cache. Edge juga menyiapkan endpoint target backend, yang dapat bervariasi per operasi SOAP.

Untuk jenis proxy ini, Edge otomatis membuat Spesifikasi OpenAPI, yang dapat Anda gunakan untuk membuat dokumentasi API.

Langkah dasar

Edge

Untuk membuat proxy RESTful API ke layanan berbasis SOAP menggunakan UI Edge:

  1. Login ke apigee.com/edge.
  2. Pilih Develop > API Proxies di menu navigasi sebelah kiri.
  3. Klik +Proxy.
  4. Klik Layanan SOAP.
  5. Di halaman Detail proxy, berikan file WSDL.
    Kolom Deskripsi
    Menyediakan file WSDL

    Pilih sumber WSDL.

    • Dari alamat web (URL) - Masukkan atau tempel URL WSDL.
    • Dari komputer saya - Upload file WSDL dari direktori lokal Anda. Anda dapat mengupload beberapa file jika ada dependensi.
  6. Klik Validasi untuk memvalidasi WSDL.
  7. Masukkan detail proxy berikut:
    Kolom Deskripsi
    Nama Nama yang ditampilkan untuk API Anda. Tentukan karakter alfanumerik, tanda hubung (-), atau garis bawah (_).
    Jalur dasar

    Fragmen URI yang muncul setelah alamat http(s)://[host] dari proxy API Anda. Edge menggunakan URI jalur dasar untuk mencocokkan dan merutekan pesan permintaan masuk ke proxy API yang sesuai.

    CATATAN: Jalur dasar proxy API secara default menggunakan nilai yang ditentukan untuk kolom Name yang dikonversi ke semua huruf kecil.

    Setelah jalur dasar, ada URL resource tambahan. Berikut adalah struktur URL lengkap yang akan digunakan klien untuk memanggil proxy API Anda:

    https://[host]/base_path/conditional_flow_path

    CATATAN: Jalur dasar harus unik; Anda tidak dapat men-deploy dua proxy API dengan jalur dasar yang sama. Jika Anda mengedit proxy API yang di-deploy dan menetapkan jalur dasar ke nilai yang sama dengan jalur dasar proxy API lain, Edge akan otomatis membatalkan deployment proxy API saat Anda menyimpannya. Sebelum dapat men-deploy ulang proxy API, Anda harus mengedit jalur dasar agar unik.

    Menggunakan karakter pengganti di jalur dasar

    Gunakan satu atau beberapa karakter pengganti /*/ di jalur dasar proxy API untuk mempersiapkan proxy API Anda di masa mendatang. Misalnya, jalur dasar /team/*/members memungkinkan klien memanggil https://[host]/team/blue/members dan https://[host]/team/green/members tanpa Anda perlu membuat proxy API baru untuk mendukung tim baru. Perhatikan bahwa /**/ tidak didukung.
    Deskripsi (Opsional) Deskripsi API.
  8. Klik Berikutnya.
  9. Di halaman Common policies pada wizard, konfigurasikan hal berikut:
    • Persyaratan otorisasi keamanan di bagian Keamanan: Otorisasi. Lihat Menambahkan keamanan.
    • Dukungan untuk Cross-origin resource sharing (CORS) di bagian Keamanan: Browser. Lihat Menambahkan dukungan untuk CORS.
    • Kuota untuk melindungi layanan backend Anda dari traffic yang tinggi di bagian Kuota. Lihat Kuota. (Tidak tersedia jika Otorisasi pass-through dipilih.)
  10. Di halaman WSDL operations, pilih jenis proxy API REST to SOAP to REST.

    Tabel akan muncul yang mencantumkan operasi yang "ditemukan" Edge dalam file WSDL. Anda dapat memilih dan mengonfigurasi operasi yang ingin digabungkan ke proxy API. Tabel ditampilkan dalam gambar berikut.

  11. Pilih Port Type dari drop-down untuk menentukan kumpulan operasi yang ingin Anda gunakan. Di WSDL, elemen jenis port menentukan operasi yang dapat Anda panggil di layanan web.
  12. Secara opsional, ubah Jalur REST API untuk operasi. Jalur akan digunakan sebagai nama resource di URL proxy API.
  13. Secara opsional, ubah Verb (metode HTTP) yang terkait dengan operasi.
  14. Klik Berikutnya.
  15. Di halaman Virtual hosts pada wizard, pilih host virtual yang akan diikat oleh proxy API saat di-deploy. Untuk mengetahui informasi selengkapnya, lihat Tentang host virtual.
  16. Klik Berikutnya.
  17. Pilih lingkungan deployment, lalu klik Create and deploy
    Proxy API baru Anda akan dibuat dan di-deploy ke lingkungan yang dipilih.
  18. Klik Edit proxy untuk menampilkan halaman detail untuk proxy API.

Edge Klasik (Private Cloud)

Untuk membuat proxy RESTful API ke layanan berbasis SOAP menggunakan UI Edge Klasik:

  1. Login ke http://ms-ip:9000, dengan ms-ip adalah alamat IP atau nama DNS node Server Pengelolaan.
  2. Pilih APIs > API Proxies di menu navigasi atas.
  3. Klik + API Proxy.
  4. Di wizard Build a Proxy, pilih layanan SOAP.
  5. Klik Berikutnya.
  6. Di halaman Detail, buat pilihan ini. Anda harus mengklik Validasi setelah memilih WSDL.
    Di kolom ini lakukan hal ini
    WSDL

    Pilih sumber WSDL.

    • URL - Masukkan URL WSDL yang ingin Anda gunakan.
    • File - Pilih file WSDL di sistem file Anda. Jika ada file dependen tambahan, Anda dapat memilih semuanya.
    • Contoh URL - Pilih dari daftar WSDL untuk layanan web yang tersedia secara publik. Alat ini berguna untuk mencoba fitur proxy SOAP/API Edge.
    Nama Proxy

    Ini adalah nama untuk proxy yang Anda buat.
    Jalur Dasar Proxy

    Fragmen URI yang muncul setelah alamat http(s)://[host] dari proxy API Anda. Edge menggunakan URI jalur dasar untuk mencocokkan dan merutekan pesan permintaan masuk ke proxy API yang sesuai.

    Catatan: Jalur dasar proxy API secara default menggunakan nilai yang ditentukan untuk kolom Name yang dikonversi ke semua huruf kecil.

    Setelah jalur dasar, ada URL resource tambahan. Berikut adalah struktur URL lengkap yang akan digunakan klien untuk memanggil proxy API Anda:

    https://[host]/base_path/conditional_flow_path

    Catatan: Jalur dasar harus unik; Anda tidak dapat men-deploy dua proxy API dengan jalur dasar yang sama. Jika Anda mengedit proxy API yang di-deploy dan menetapkan jalur dasar ke nilai yang sama dengan jalur dasar proxy API lain, Edge akan otomatis membatalkan deployment proxy API saat Anda menyimpannya. Sebelum dapat men-deploy ulang proxy API, Anda harus mengedit jalur dasar agar unik.

    Menggunakan karakter pengganti di jalur dasar

    Gunakan satu atau beberapa karakter pengganti /*/ di jalur dasar proxy API untuk mempersiapkan proxy API Anda di masa mendatang. Misalnya, jalur dasar /team/*/members memungkinkan klien memanggil https://[host]/team/blue/members dan https://[host]/team/green/members tanpa Anda perlu membuat proxy API baru untuk mendukung tim baru. Perhatikan bahwa /**/ tidak didukung.
    Deskripsi Deskripsi singkat proxy.
  7. Klik Berikutnya.
  8. Di halaman WSDL, pilih jenis proxy API REST to SOAP to REST.

    Tabel akan muncul yang mencantumkan operasi yang "ditemukan" Edge dalam file WSDL. Anda dapat memilih dan mengonfigurasi operasi yang ingin digabungkan ke proxy API. Tabel ditampilkan dalam gambar berikut.

    Di halaman operasi WSDL, jenis proxy API ditetapkan ke REST ke SOAP ke REST, dan tabel menampilkan satu baris hasil dengan operasi penambahan.

  9. Pilih kumpulan operasi yang ingin Anda gunakan dari kolom Jenis Port. Di WSDL, elemen jenis port menentukan operasi yang dapat Anda panggil di layanan web.
  10. Secara opsional, ubah Metode HTTP yang terkait dengan operasi.

    Catatan: Edge membuat "tebakan terbaik" dalam menentukan metode HTTP yang akan digunakan untuk setiap operasi. GET umumnya lebih disukai karena permintaan GET dapat disimpan dalam cache.
  11. Jika ingin, ubah jalur REST API untuk operasi. Jalur akan digunakan sebagai nama resource di URL proxy API.
  12. Klik bagian wizard lainnya untuk menambahkan keamanan, memilih host virtual, dan lingkungan deployment.
  13. Di halaman Build, klik Build and Deploy. Edge membuat dan men-deploy proxy API baru berdasarkan WSDL.
  14. Buka halaman ringkasan untuk proxy API baru. Perhatikan bahwa sekumpulan resource telah dibuat berdasarkan operasi yang ditemukan dalam file WSDL.

    Di halaman Ringkasan proxy, daftar Resource memberikan deskripsi mendetail tentang API baru, operasinya, dan parameternya. Anda dapat menganggap representasi ini sebagai dokumentasi referensi API. Edge membuat tampilan model API ini secara otomatis untuk Anda. Cukup luaskan resource untuk melihat deskripsi dan informasi jalurnya.

Tentang proxy akhir

Saat Edge membuat proxy API berdasarkan WSDL, proxy yang dihasilkan sebenarnya adalah alur kompleks yang mencakup kebijakan untuk mengubah data, mengekstrak dan menetapkan variabel, memanipulasi pesan, dan lainnya. Setelah Anda membuat proxy berdasarkan WSDL, lihat alur yang dihasilkan di tampilan Develop pada UI pengelolaan API. Di sana, Anda dapat melihat dengan tepat kebijakan mana yang telah ditambahkan.

Misalnya, di sisi permintaan, kebijakan AssignMessage digunakan untuk menetapkan URL target. Di sisi respons, kebijakan dieksekusi untuk mengubah respons dari XML menjadi JSON, mengekstrak bagian isi SOAP dari respons menjadi variabel, dan menetapkan pesan respons. Kebijakan ini (dan lainnya) ditambahkan secara otomatis saat Anda membuat proxy.

OpenAPI Spec: Untuk melihat OpenAPI Spec yang dibuat otomatis untuk proxy ini, buka http(s)://[proxy_domain]/[proxy_base_path]/openapi.json. Namun, konversi tidak selalu akurat, karena tidak semua aturan skema XML dapat direpresentasikan dalam Spesifikasi OpenAPI.

Membuat proxy pass-through ke layanan berbasis SOAP

Bagian ini menjelaskan cara membuat proxy pass-through dengan opsi Pass-Through Proxy di dialog Create New Proxy.

Ringkasan

Opsi Pass-Through Proxy memungkinkan Anda membuat proxy yang meneruskan pesan SOAP dalam permintaan ke layanan backend "tanpa disentuh", sehingga sangat mudah untuk membuat proxy untuk layanan web berbasis SOAP. Di balik layar, Edge menangani transformasi dan aktivitas alur lainnya secara otomatis untuk Anda. Misalnya, jika permintaan dalam format JSON, Edge akan mengambil langkah-langkah untuk mengonversinya menjadi pesan SOAP XML yang valid dengan namespace yang benar sebelum mengirimnya ke layanan. Demikian pula, saat layanan menampilkan respons SOAP berbasis XML, Edge menerjemahkannya kembali ke JSON sebelum menampilkannya ke klien. Selain itu, Edge menyiapkan endpoint target backend, yang dapat bervariasi per operasi SOAP.

Untuk jenis proxy ini, Edge menghosting WSDL dan membuat alur di proxy agar Anda dapat mengaksesnya. Alamat ke WSDL yang dihosting Edge ini, http(s)://[proxy_domain]/[proxy_base_path]?wsdl, menjadi URL endpoint layanan baru untuk klien yang memanggil layanan SOAP melalui proxy.

Langkah dasar

Edge

Untuk membuat proxy pass-through ke layanan berbasis SOAP menggunakan UI Edge:

  1. Login ke apigee.com/edge.
  2. Pilih Develop > API Proxies di menu navigasi sebelah kiri.
  3. Klik +Proxy.
  4. Klik Layanan SOAP.
  5. Di halaman Detail proxy, berikan detail WSDL.
    Kolom Deskripsi
    WSDL

    Pilih sumber WSDL.

    • Dari alamat web (URL) - Masukkan atau tempel URL WSDL.
    • Dari komputer saya - Upload file WSDL dari direktori lokal Anda. Anda dapat mengupload beberapa file jika ada dependensi.
    Nama

    Nama proxy API.
    Jalur dasar

    Fragmen URI setelah alamat http(s)://[host] dari proxy API Anda. Edge menggunakan URI jalur dasar untuk mencocokkan dan merutekan pesan permintaan masuk ke proxy API yang sesuai.

    Catatan: Untuk rekomendasi Apigee tentang pembuatan versi API, lihat Pembuatan Versi dalam e-book Web API Design: The Missing Link.

    Setelah jalur dasar, ada URL resource tambahan. Berikut adalah struktur URL lengkap yang akan digunakan klien untuk memanggil proxy API Anda:

    https://[host]/base_path/conditional_flow_path

    Catatan: Jalur dasar harus unik. Jika nanti Anda mengedit proxy ini dan menetapkan jalur dasarnya agar sama dengan proxy API lain, proxy API ini akan otomatis di-undeploy saat Anda menyimpannya. Anda harus mengedit jalur dasar sebelum dapat men-deploy ulang.

    Menggunakan karakter pengganti di jalur dasar

    Anda dapat menggunakan satu atau beberapa karakter pengganti /*/ di jalur dasar proxy API untuk membuat proxy Anda tetap relevan di masa mendatang. Misalnya, jalur dasar /team/*/members memungkinkan klien memanggil https://[host]/team/blue/members dan https://[host]/team/green/members tanpa Anda perlu membuat proxy API baru untuk mendukung tim baru. Perhatikan bahwa /**/ tidak didukung.

    Catatan: Jalur dasar proxy API secara default menggunakan nilai yang ditentukan untuk kolom Nama yang dikonversi ke huruf kecil kecuali jika Anda secara eksplisit mengedit konten di kolom Jalur Dasar.
    Deskripsi (Opsional) Deskripsi API.
  6. Klik Berikutnya.
  7. Di halaman Common policies pada wizard, konfigurasikan hal berikut:
  8. Di halaman WSDL, pilih jenis proxy API Pass-Through SOAP.

  9. Pilih Port Type dari drop-down untuk menentukan kumpulan operasi yang ingin Anda gunakan. Di WSDL, elemen jenis port menentukan operasi yang dapat Anda panggil di layanan web.
  10. Klik Berikutnya.
  11. Di halaman Virtual hosts pada wizard, pilih host virtual yang akan diikat oleh proxy API saat di-deploy. Untuk informasi selengkapnya, lihat Tentang host virtual.
  12. Pilih lingkungan deployment, lalu klik Create and deploy
    Proxy API baru Anda akan dibuat dan di-deploy di lingkungan yang dipilih.
  13. Klik Edit proxy untuk menampilkan halaman detail untuk proxy API.

Edge Klasik (Private Cloud)

Untuk membuat proxy pass-through ke layanan berbasis SOAP menggunakan UI Edge Klasik:

  1. Login ke http://ms-ip:9000, dengan ms-ip adalah alamat IP atau nama DNS node Server Pengelolaan.
  2. Pilih APIs > API Proxies di menu navigasi atas.
  3. Klik + API Proxy.
  4. Di wizard Build a Proxy, pilih layanan SOAP.
  5. Klik Berikutnya.
  6. Di halaman Detail, buat pilihan ini. Anda harus mengklik Validasi setelah memilih WSDL.
    Di kolom ini lakukan hal ini
    WSDL

    Pilih sumber WSDL.

    • URL - Masukkan URL WSDL yang ingin Anda gunakan.
    • File - Pilih file WSDL di sistem file Anda. Jika ada file dependen tambahan, Anda dapat memilih semuanya.
    • Contoh URL - Pilih dari daftar WSDL untuk layanan web yang tersedia secara publik. Alat ini berguna untuk mencoba fitur proxy SOAP/API Edge.
    Nama Proxy

    Ini adalah nama untuk proxy yang Anda buat.
    Jalur Dasar Proxy Jalur Dasar Proxy adalah fragmen URI yang secara unik mengidentifikasi API yang diekspos oleh proxy API ini. Layanan API menggunakan URI Jalur Dasar untuk mencocokkan dan merutekan pesan permintaan yang masuk ke proxy API yang sesuai. (Jalur Dasar ditambahkan ke domain API, yang dibuat secara otomatis berdasarkan nama organisasi dan lingkungan tempat proxy API di-deploy.) Sebaiknya sertakan nomor versi dalam nama project, misalnya, /v1/delayedstockquote. Hal ini akan menentukan cara API Anda dipanggil oleh aplikasi konsumen.

    Catatan: Jalur Dasar Proxy secara default menggunakan nilai yang ditentukan untuk Nama Proxy yang dikonversi menjadi huruf kecil, kecuali jika Anda secara eksplisit mengedit konten di kolom Jalur Dasar Proxy.
    Deskripsi Deskripsi singkat proxy.

  8. Klik Berikutnya.
  9. Di halaman WSDL, pilih jenis proxy API Pass-Through SOAP.

    Catatan: Tabel akan muncul yang mencantumkan setiap operasi WSDL dan payload SOAP yang sesuai. Ini adalah payload yang "diteruskan" ke layanan SOAP backend.

    Di halaman WSDL, jenis proxy API ditetapkan ke SOAP Pass-Through, dan daftar operasi seperti GetQuote diatur menurut jenis port.
  10. Pilih kumpulan operasi yang ingin Anda gunakan dari kolom Jenis Port. Di WSDL, elemen jenis port menentukan operasi yang dapat Anda panggil di layanan web.
  11. Klik bagian wizard lainnya untuk menambahkan keamanan, memilih host virtual, dan lingkungan deployment.
  12. Di halaman Build, klik Build and Deploy. Edge membuat dan men-deploy proxy API baru berdasarkan WSDL.

Tentang proxy akhir

Saat Edge membuat proxy pass-through, proxy yang dihasilkan sebenarnya adalah alur kompleks yang menyertakan kebijakan untuk mengubah data, mengekstrak dan menetapkan variabel, memanipulasi pesan, dan lainnya. Setelah Anda membuat proxy pass-through, lihat alur yang dihasilkan di Tampilan Develop pada UI pengelolaan API. Di sana, Anda dapat melihat dengan tepat kebijakan mana yang telah ditambahkan.

Misalnya, gambar berikut menunjukkan bagian Praaliran Endpoint Target dari proxy pass-through. Di sisi permintaan, kebijakan AssignMessage digunakan untuk menetapkan URL target. Di sisi respons, kebijakan dieksekusi untuk mengubah respons dari XML menjadi JSON, mengekstrak bagian isi SOAP dari respons menjadi variabel, dan menetapkan pesan respons. Kebijakan ini (dan lainnya) ditambahkan secara otomatis saat Anda membuat proxy.

Pada tampilan Develop, di panel Flow, panah menggambarkan alur dari permintaan ke respons, dan ikon menggambarkan kebijakan.

WSDL yang dihosting Edge: Untuk melihat WSDL yang dihosting Edge yang dibuat untuk jenis proxy ini, buka http(s)://[proxy_domain]/[proxy_base_path]?wsdl.

Pengembangan proxy SOAP-to-REST lanjutan

Bagian sebelumnya membahas pembuatan proxy SOAP-to-REST API menggunakan wizard proxy API di Edge. Namun, jika Anda menginginkan kontrol yang lebih terperinci atas transformasi SOAP-ke-REST, Anda dapat mengabaikan otomatisasi yang disediakan oleh wizard dan membuat proxy dengan menambahkan dan mengonfigurasi kebijakan secara manual untuk mendapatkan perilaku yang Anda inginkan. Untuk informasi selengkapnya, lihat Tutorial: Pembuatan proxy SOAP-to-REST API secara manual di Apigee Edge.