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. Yang satu membuat RESTful interface 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 end-to-end tentang cara mengubah layanan SOAP menjadi layanan REST dengan Apigee Edge menggunakan wizard proxy API. Namun, jika menginginkan kontrol lebih besar atas transformasi SOAP ke REST, Anda dapat membuat proxy menggunakan kebijakan. Untuk mengetahui informasi selengkapnya, lihat Tutorial: Pembuatan manual proxy API SOAP-ke-REST di Apigee Edge.

Membuat proxy API RESTful ke layanan berbasis SOAP

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

Ringkasan

Opsi REST to SOAP to REST memproses WSDL untuk menghasilkan proxy API RESTful. Edge menentukan dari WSDL operasi yang didukung layanan, parameter input, dan sebagainya. Edge "menebak" metode HTTP mana yang akan digunakan untuk setiap operasi. Biasanya, operasi Edge Translate diterjemahkan menjadi permintaan GET, yang memiliki keunggulan karena dapat di-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 API RESTful 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 SOAP service.
  5. Di halaman Proxy details, berikan file WSDL.
    Kolom Deskripsi
    Menyediakan file WSDL

    Pilih sumber WSDL.

    • Dari alamat web (URL) - Masukkan atau tempelkan 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 (_).
    Base path

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

    NOTE: Jalur dasar proxy API secara default adalah nilai yang ditentukan untuk kolom Name yang dikonversi menjadi huruf kecil semua.

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

    https://[host]/base_path/conditional_flow_path

    NOTE: 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 memastikan proxy API Anda siap untuk 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 Security: Authorization. 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 tinggi di bagian Quota. Lihat Kuota. (Tidak tersedia jika otorisasi Terusan 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 Anda gabungkan ke dalam proxy API. Tabel ini ditampilkan dalam gambar berikut.

  11. Pilih Jenis Port dari menu drop-down untuk menentukan set operasi yang ingin Anda gunakan. Di WSDL, elemen jenis port menentukan operasi yang dapat Anda panggil di layanan web.
  12. Secara opsional, ubah Path REST API untuk suatu operasi. Jalur akan digunakan sebagai nama resource di URL proxy API.
  13. Jika perlu, 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 dibuat dan di-deploy ke lingkungan yang dipilih.
  18. Klik Edit proxy untuk menampilkan halaman detail proxy API.

Classic Edge (Private Cloud)

Untuk membuat proxy API RESTful 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 SOAP service.
  5. Klik Berikutnya.
  6. Di halaman Detail, lakukan pilihan berikut. Anda harus mengklik Validasi setelah memilih WSDL.
    Di kolom ini lakukan 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. Fitur ini berguna untuk mencoba fitur proxy SOAP/API Edge.
    Nama Proxy

    Ini adalah nama 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 tepat.

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

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

    https://[host]/base_path/conditional_flow_path

    Catatan: Base path harus unik; Anda tidak dapat men-deploy dua proxy API dengan base path 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 memastikan proxy API Anda siap untuk 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 Anda gabungkan ke dalam proxy API. Tabel ini ditampilkan dalam gambar berikut.

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

  9. Pilih dari kolom Jenis Port set operasi yang ingin Anda gunakan. 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 di-cache.
  11. Jika perlu, ubah jalur REST API untuk suatu operasi. Jalur akan digunakan sebagai nama resource di URL proxy API.
  12. Klik 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 jalur nya.

Tentang proxy akhir

Saat Edge membuat proxy API berdasarkan WSDL, proxy yang dihasilkan sebenarnya adalah alur kompleks yang mencakup kebijakan untuk mentransformasi data, mengekstrak dan menyetel variabel, memanipulasi pesan, dan lainnya. Setelah 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 dijalankan untuk mengubah respons dari XML menjadi JSON, mengekstrak bagian isi SOAP dari respons ke dalam variabel, dan menetapkan pesan respons. Kebijakan ini (dan kebijakan lainnya) ditambahkan secara otomatis saat Anda membuat proxy.

Spesifikasi OpenAPI: Untuk melihat Spesifikasi OpenAPI 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 ditampilkan dalam Spesifikasi OpenAPI.

Membuat proxy pass-through ke layanan berbasis SOAP

Bagian ini menjelaskan cara membuat proxy terus teruskan dengan opsi Pass-Through Proxy dalam dialog Create New Proxy.

Ringkasan

Opsi Proxy Terusan memungkinkan Anda membuat proxy yang meneruskan pesan SOAP dalam permintaan ke layanan backend "tanpa diubah", sehingga sangat memudahkan pembuatan proxy untuk layanan web berbasis SOAP. Di balik layar, Edge menangani transformasi dan aktivitas alur lainnya secara otomatis untuk Anda. Misalnya, jika permintaan kebetulan dalam format JSON, Edge akan mengambil langkah-langkah untuk mengonversinya menjadi pesan SOAP XML yang valid dengan namespace yang benar sebelum mempostingnya 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 WSDL yang dihosting di 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 SOAP service.
  5. Di halaman Proxy details, berikan detail WSDL.
    Kolom Deskripsi
    WSDL

    Pilih sumber WSDL.

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

    Nama proxy API.
    Base path

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

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

    Setelah jalur dasar adalah URL resource tambahan. Berikut 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 Anda mengedit proxy ini nanti dan menetapkan jalur dasarnya agar sama dengan proxy API lain, proxy API ini akan dibatalkan deployment-nya secara otomatis 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 memastikan 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 menjadi huruf kecil semua, 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 Jenis Port dari menu drop-down untuk menentukan set 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 mengetahui informasi selengkapnya, lihat Tentang host virtual.
  12. Pilih lingkungan deployment, lalu klik Create and deploy
    Proxy API baru Anda dibuat dan di-deploy di lingkungan yang dipilih.
  13. Klik Edit proxy untuk menampilkan halaman detail proxy API.

Classic Edge (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 SOAP service.
  5. Klik Berikutnya.
  6. Di halaman Detail, lakukan pilihan berikut. Anda harus mengklik Validasi setelah memilih WSDL.
    Di kolom ini lakukan 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. Hal ini berguna untuk mencoba fitur proxy SOAP/API di Edge.
    Nama Proxy

    Ini adalah nama 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 masuk ke proxy API yang tepat. (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. Ini akan menentukan cara API Anda dipanggil oleh aplikasi konsumen.

    Catatan: Jalur Dasar Proxy secara default ditetapkan ke nilai yang ditentukan untuk Nama Proxy yang dikonversi menjadi huruf kecil semua, 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 muatan SOAP yang sesuai. Ini adalah payload yang "diteruskan" ke layanan SOAP backend.

    Di halaman WSDL, jenis proxy API ditetapkan ke Pass-Through SOAP, dan daftar operasi seperti GetQuote diatur berdasarkan jenis port.
  10. Pilih dari kolom Jenis Port set operasi yang ingin Anda gunakan. Di WSDL, elemen jenis port menentukan operasi yang dapat Anda panggil di layanan web.
  11. Klik 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 teruskan, proxy yang dihasilkan sebenarnya adalah alur kompleks yang mencakup kebijakan untuk mengubah data, mengekstrak dan menyetel variabel, memanipulasi pesan, dan lainnya. Setelah membuat proxy teruskan, 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 Target Endpoint Preflow dari proxy pass-through. Di sisi permintaan, kebijakan AssignMessage digunakan untuk menetapkan URL target. Di sisi respons, kebijakan dijalankan untuk mengubah respons dari XML menjadi JSON, mengekstrak bagian isi SOAP dari respons ke dalam variabel, dan menetapkan pesan respons. Kebijakan ini (dan kebijakan lainnya) ditambahkan secara otomatis saat Anda membuat proxy.

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

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

Pengembangan proxy SOAP-to-REST tingkat lanjut

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