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. Salah satunya menghasilkan antarmuka RESTful ke layanan SOAP backend, dan satu lagi menjalankan "pass through" pesan SOAP ke backend. Kedua teknik tersebut dijelaskan dalam topik ini.

Video ini menyediakan demo menyeluruh tentang cara mengubah layanan SOAP menjadi layanan REST dengan Apigee Edge menggunakan wizard proxy API. Namun, jika Anda menginginkan kontrol lebih besar atas transformasi SOAP ke REST, Anda dapat mem-build proxy menggunakan kebijakan. Untuk informasi selengkapnya, lihat Tutorial: Pembuatan manual proxy SOAP-ke-REST API 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 ke SOAP ke REST memproses WSDL untuk membuat proxy API RESTful. Edge menentukan operasi yang didukung layanan, parameter input, dan sebagainya dari WSDL. Edge "menebak" metode HTTP yang akan digunakan untuk setiap operasi. Biasanya, Edge menerjemahkan operasi menjadi permintaan GET, yang memiliki keuntungan 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 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 SABUN.
  5. Di halaman detail Proxy, berikan file WSDL.
    Kolom Deskripsi
    Berikan 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] proxy API Anda. Edge menggunakan URI jalur dasar untuk mencocokkan dan merutekan pesan permintaan yang masuk ke proxy API yang tepat.

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

    URL resource tambahan akan mengikuti jalur dasar. 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 menerapkan 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 bersifat unik.

    Menggunakan karakter pengganti di jalur dasar

    Gunakan satu atau beberapa karakter pengganti /*/ di jalur dasar proxy API agar proxy API Anda siap menghadapi masa depan. 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 Next.
  9. Pada halaman Kebijakan umum di wizard, konfigurasikan hal-hal berikut:
    • Persyaratan otorisasi keamanan di bagian Keamanan: Otorisasi. Lihat Menambahkan keamanan.
    • Dukungan untuk Cross-origin resource sharing (CORS) di bagian Security: Browser. Lihat Menambahkan dukungan untuk CORS.
    • Kuota untuk melindungi layanan backend Anda dari traffic tinggi di bawah Kuota. Lihat Kuota. (Tidak tersedia jika Otorisasi pass-through dipilih.)
  10. Di halaman WSDL Operations, pilih jenis proxy API REST to SOAP to REST.

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

  11. Pilih Jenis Port dari drop-down untuk menentukan kumpulan operasi yang ingin Anda gunakan. Dalam WSDL, elemen jenis port menentukan operasi yang dapat Anda panggil di layanan web.
  12. Jika ingin, ubah Jalur REST API untuk sebuah operasi. Jalur tersebut akan digunakan sebagai nama resource dalam URL proxy API.
  13. Jika ingin, ubah Verb (metode HTTP) yang terkait dengan operasi.
  14. Klik Next.
  15. Di halaman Virtual hosts di wizard, pilih host virtual yang akan diikat oleh proxy API saat di-deploy. Untuk informasi selengkapnya, lihat Tentang host virtual.
  16. Klik Next.
  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.

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 yang merupakan alamat IP atau nama DNS node Server Pengelolaan.
  2. Pilih APIs > API Proxy di menu navigasi atas.
  3. Klik + API Proxy.
  4. Di wizard Build a Proxy, pilih SOAP service.
  5. Klik Next.
  6. Di halaman Detail, tentukan 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 dari Edge.
    Nama Proxy

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

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

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

    URL resource tambahan akan mengikuti jalur dasar. 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 bersifat unik.

    Menggunakan karakter pengganti di jalur dasar

    Gunakan satu atau beberapa karakter pengganti /*/ di jalur dasar proxy API agar proxy API Anda siap menghadapi masa depan. 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 tentang proxy.
  7. Klik Next.
  8. Di halaman WSDL, pilih jenis proxy API REST ke SOAP ke REST.

    Sebuah tabel akan muncul dan mencantumkan operasi yang "ditemukan" Edge dalam file WSDL. Anda dapat memilih dan mengonfigurasi operasi yang ingin Anda sertakan ke proxy API Anda. 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. Dalam WSDL, elemen jenis port menentukan operasi yang dapat Anda panggil di layanan web.
  10. Jika perlu, 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 ingin, Anda dapat mengubah jalur REST API untuk suatu operasi. Jalur tersebut akan digunakan sebagai nama resource dalam URL proxy API.
  12. Klik seluruh wizard 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.

    Pada 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 merupakan alur kompleks yang mencakup kebijakan untuk mengubah data, mengekstrak dan menetapkan variabel, memanipulasi pesan, dan banyak lagi. Setelah membuat proxy berdasarkan WSDL, lihat alur yang dihasilkan dalam tampilan Pengembangan UI pengelolaan API. Di sana, Anda dapat melihat dengan tepat kebijakan yang telah ditambahkan.

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

Spesifikasi OpenAPI: Untuk melihat Spesifikasi OpenAPI yang dibuat otomatis untuk proxy ini, kunjungi 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 pass-through dengan opsi Pass-Through Proxy pada dialog Create New Proxy.

Ringkasan

Dengan opsi Proxy Pass-through, Anda dapat membuat proxy yang meneruskan pesan SOAP dalam permintaan ke layanan backend "tanpa sentuh", sehingga sangat mudah untuk membuat proxy untuk layanan web berbasis SOAP. Di balik layar, Edge menangani transformasi dan aktivitas alur lainnya secara otomatis. Misalnya, jika permintaan ternyata 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 akan menerjemahkannya kembali ke JSON sebelum mengembalikannya ke klien. Selain itu, Edge menyiapkan endpoint target backend, yang dapat bervariasi per operasi SOAP.

Untuk jenis proxy ini, Edge menghosting WSDL dan membuat flow dalam proxy untuk memungkinkan Anda mengaksesnya. Alamat 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 SABUN.
  5. Pada 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.
    Name

    Nama proxy API.
    Jalur dasar

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

    Catatan: Untuk mengetahui rekomendasi Apigee terkait pembuatan versi API, lihat Pembuatan Versi di e-book Desain API Web: Link yang Tidak Ada.

    Setelah jalur dasar terdapat URL resource tambahan. Berikut ini 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 lainnya, proxy API ini otomatis dibatalkan deploymentnya saat Anda menyimpannya. Anda harus mengedit jalur dasar sebelum dapat men-deploy ulang jalur tersebut.

    Menggunakan karakter pengganti di jalur dasar

    Anda dapat menggunakan satu atau beberapa karakter pengganti /*/ di jalur dasar proxy API agar proxy Anda siap menghadapi masa depan. 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 ditetapkan secara default ke 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 Next.
  7. Pada halaman Kebijakan umum di wizard, konfigurasikan hal-hal berikut:
  8. Pada halaman WSDL, pilih jenis proxy API Pass-Through SOAP.

  9. Pilih Jenis Port dari drop-down untuk menentukan kumpulan operasi yang ingin Anda gunakan. Dalam WSDL, elemen jenis port menentukan operasi yang dapat Anda panggil di layanan web.
  10. Klik Next.
  11. Di halaman Virtual hosts di 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 dibuat dan di-deploy di lingkungan yang dipilih.
  13. Klik Edit proxy untuk menampilkan halaman detail 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 yang merupakan alamat IP atau nama DNS node Server Pengelolaan.
  2. Pilih APIs > API Proxy di menu navigasi atas.
  3. Klik + API Proxy.
  4. Di wizard Build a Proxy, pilih SOAP service.
  5. Klik Next.
  6. Di halaman Detail, tentukan 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 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 masuk ke proxy API yang tepat. (Jalur Dasar ditambahkan ke domain API, yang secara otomatis dihasilkan berdasarkan nama organisasi Anda dan lingkungan tempat proxy API di-deploy.) Praktik terbaiknya adalah menyertakan nomor versi dalam nama project, misalnya, /v1/delayedstockquote. Tindakan ini akan menentukan cara API Anda dipanggil oleh aplikasi konsumen.

    Catatan: Jalur Dasar Proxy ditetapkan secara default ke nilai yang ditentukan untuk Proxy Name yang dikonversi ke semua huruf kecil, kecuali jika Anda secara eksplisit mengedit konten di kolom Jalur Dasar Proxy.
    Deskripsi Deskripsi singkat tentang proxy.

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

    Catatan: Sebuah 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 Pass-Through SOAP, dan daftar operasi seperti GetQuote diatur menurut jenis port.
  10. Pilih kumpulan operasi yang ingin Anda gunakan dari kolom Jenis Port. Dalam WSDL, elemen jenis port menentukan operasi yang dapat Anda panggil di layanan web.
  11. Klik seluruh wizard 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 menghasilkan proxy pass-through, proxy yang dihasilkan sebenarnya merupakan alur kompleks yang mencakup kebijakan untuk mengubah data, mengekstrak serta menetapkan variabel, memanipulasi pesan, dan banyak lagi. Setelah membuat proxy pass-through, lihat alur yang dihasilkan dalam tampilan Pengembangan UI pengelolaan API. Di sana, Anda dapat melihat dengan tepat kebijakan yang telah ditambahkan.

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

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

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

Pengembangan proxy SOAP-ke-REST lanjutan

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