Menerbitkan Api Microsoft Azure Data Manager for Energy ke gateway API yang aman
Azure API Management berfungsi sebagai perantara penting antara aplikasi klien dan API backend. Ini memudahkan klien untuk mengakses layanan dengan menyembunyikan detail teknis dan memberikan kontrol organisasi atas keamanan API.
Dengan menerbitkan Api Azure Data Manager for Energy melalui Azure API Management, Anda dapat menggunakan kemampuan Azure Data Manager for Energy Private Link untuk lalu lintas privat dan menghapus akses publik langsung sepenuhnya ke instans Anda.
Artikel ini menjelaskan cara menyiapkan Azure API Management untuk mengamankan Api Azure Data Manager for Energy.
Prasyarat
Anda memerlukan komponen, alat, dan informasi berikut yang tersedia untuk menyelesaikan panduan ini:
Jaringan virtual dengan dua subnet tersedia, satu untuk titik akhir privat Azure Data Manager for Energy dan yang lainnya untuk injeksi jaringan virtual Azure API Management.
Azure Data Manager for Energy dikonfigurasi dengan tautan privat yang disebarkan ke subnet.
Azure API Management disediakan dan disebarkan ke jaringan virtual menggunakan injeksi jaringan virtual. Pilih Mode eksternal , atau lihat bagian Opsi lain untuk Mode internal .
Editor kode seperti Visual Studio Code untuk memodifikasi spesifikasi Azure Data Manager for Energy OpenAPI untuk setiap API yang diterbitkan.
Unduh spesifikasi Azure Data Manager for Energy OpenAPI dari repositori GitHub adme-samples . Navigasi ke direktori rest-apis dan pilih versi yang sesuai untuk aplikasi Anda.
Dari pendaftaran aplikasi untuk aplikasi Azure Data Manager for Energy yang digunakan pada waktu provisi, perhatikan ID Penyewa dan ID Klien:
Menyiapkan instans API Management
Gunakan langkah-langkah berikut untuk membuat perubahan konfigurasi pada instans Azure API Management Anda:
Dari panel Semua sumber daya , pilih instans Azure API Management yang digunakan untuk panduan ini.
Navigasi ke halaman Pengaturan produk dengan memilihnya dari pengelompokan pengaturan API:
Pada halaman Produk, pilih tombol Tambahkan untuk membuat Produk baru. Produk Azure API Management memungkinkan Anda membuat pengelompokan API yang digabungkan secara longgar yang dapat diatur dan dikelola bersama-sama. Kami membuat Produk untuk Api Azure Data Manager for Energy kami.
Pada halaman Tambahkan produk, masukkan nilai yang dijelaskan dalam tabel berikut ini untuk membuat produk.
Pengaturan Nilai Nama Tampilan "Azure Data Manager untuk Produk Energi" ID "adme-product" Deskripsi Masukkan deskripsi yang menunjukkan kepada pengembang API mana yang kami kelompokkan Diterbitkan Centang kotak ini untuk menerbitkan Produk yang kami buat Membutuhkan langganan Centang kotak ini untuk memberikan otorisasi dasar untuk API kami Membutuhkan persetujuan Pilih secara opsional jika Anda ingin administrator meninjau dan menerima atau menolak upaya langganan ke produk ini. Jika tidak dipilih, upaya langganan akan disetujui secara otomatis. Batas jumlah langganan Secara opsional, batasi jumlah beberapa langganan simultan. Istilah hukum Secara opsional tentukan ketentuan penggunaan untuk produk yang harus diterima pelanggan untuk menggunakan produk. API Kita dapat mengabaikan fitur ini. Kami mengaitkan API nanti di artikel ini Pilih Buat untuk membuat produk baru.
Setelah pembuatan produk selesai, portal mengembalikan Anda ke halaman Produk. Pilih produk Azure Data Manager for Energy Product kami yang baru dibuat untuk masuk ke halaman Sumber daya produk. Pilih item menu Pengaturan kebijakan dari menu pengaturan.
Pada panel Pemrosesan masuk, pilih <ikon /> , yang memungkinkan Anda mengubah kebijakan untuk produk. Anda menambahkan tiga set kebijakan untuk meningkatkan keamanan solusi:
- Memvalidasi Token ID Entra untuk memastikan permintaan yang tidak diaauthenticated tertangkap di gateway API
- Kuota dan Batas Tarif untuk mengontrol tingkat permintaan dan total permintaan/data yang ditransfer
- Atur Header untuk menghapus header yang dikembalikan oleh API backend, yang mungkin mengungkapkan detail sensitif ke pelaku jahat potensial
Tambahkan kebijakan validate-azure-ad-token berikut ke konfigurasi kami dalam tag masuk dan di bawah tag dasar. Pastikan untuk memperbarui templat dengan detail aplikasi ID Microsoft Entra yang dicatat dalam prasyarat.
<validate-azure-ad-token tenant-id="INSERT_TENANT_ID"> <client-application-ids> <application-id>INSERT_APP_ID</application-id> </client-application-ids> </validate-azure-ad-token>Di bawah kebijakan validate-azure-ad-token, tambahkan kebijakan kuota dan batas tarif berikut. Perbarui nilai konfigurasi kebijakan yang sesuai untuk konsumen Anda.
<rate-limit calls="20" renewal-period="90" remaining-calls-variable-name="remainingCallsPerSubscription"/> <quota calls="10000" bandwidth="40000" renewal-period="3600" />Ke bagian keluar editor kebijakan dan di bawah tag dasar, tambahkan kebijakan set-header berikut.
<set-header name="x-envoy-upstream-service-time" exists-action="delete" /> <set-header name="x-internal-uri-pattern" exists-action="delete" />Pilih Simpan untuk menerapkan perubahan.
Navigasikan kembali ke sumber daya API Management di portal Azure. Pilih item menu Backend dan pilih tombol + Tambahkan.
Pada modal Backend, masukkan nilai yang dijelaskan dalam tabel berikut untuk membuat backend.
Pengaturan Nilai Nama "adme-backend" Deskripsi Masukkan deskripsi yang menunjukkan kepada pengembang bahwa backend ini terkait dengan Api Azure Data Manager for Energy Jenis URL Kustom Runtime URL Masukkan _ex Azure Data Manager for Energy URI Anda. https://INSERT_ADME_NAME.energy.azure.com/Memvalidasi rantai sertifikat Dicentang Memvalidasi nama sertifikat Dicentang 
Pilih Buat untuk membuat backend. Backend yang baru dibuat ini akan digunakan di bagian berikutnya saat kami menerbitkan API.
Mengimpor Azure Data Manager untuk API Energi
Gunakan langkah-langkah berikut untuk mengimpor, mengonfigurasi, dan menerbitkan Api Azure Data Manager for Energy ke gateway Azure API Management:
Navigasikan kembali ke instans Azure API Management yang digunakan di bagian terakhir.
Pilih item menu API dari menu, lalu pilih tombol + Tambahkan API .
Pilih OpenAPI di bawah judul Buat dari definisi .
Di jendela Buat dari modal spesifikasi OpenAPI, pilih tombol Penuh .
Temukan spesifikasi OpenAPI yang Anda unduh sebagai bagian dari prasyarat dan buka spesifikasi Skema menggunakan editor kode pilihan Anda. Cari kata "server" dan catat URL server di file ex. /api/schema-service/v1/.
Pilih Pilih file dan pilih spesifikasi API Skema . Ketika unggahan selesai, jendela modal memuat beberapa nilai dari spesifikasi.
Untuk bidang lain, masukkan nilai yang dijelaskan dalam tabel berikut ini:
Pengaturan Nilai Menyertakan parameter kueri yang diperlukan dalam templat operasi Dicentang Nama tampilan Masukkan nama tampilan yang masuk akal bagi pengembang aplikasi misalnya. Azure Data Manager for Energy Schema Service Nama API Management menyarankan nama kebab-cased. Secara opsional, nama dapat diubah tetapi harus unik untuk instans Deskripsi Spesifikasi OpenAPI mungkin menentukan deskripsi, jika demikian deskripsi secara otomatis terisi. Secara opsional, perbarui deskripsi per kasus penggunaan Anda. Skema URL Pilih "Keduanya" Akhiran URL API Masukkan akhiran untuk semua Api Azure Data Manager for Energy (mis. adme). Kemudian masukkan URL server dari langkah 5. Nilai akhir akan terlihat seperti /adme/api/schema-service/v1/. Akhiran memungkinkan kami mematuhi klien dan kit pengembangan perangkat lunak yang ada yang biasanya terhubung ke Api Azure Data Manager for Energy secara langsung Tag Secara opsional masukkan tag Produk Pilih produk "Azure Data Manager for Energy" yang dibuat di bagian sebelumnya Penting
Validasi akhiran URL API, ini adalah penyebab umum kesalahan dalam menerbitkan API Azure Data Manager for Energy
Pilih Buat untuk membuat fasad API.
Pilih fasad API Skema yang baru dibuat dari daftar API dan pilih pada Semua operasi pada daftar operasi. Pada panel Pemrosesan masuk, pilih< ikon />untuk mengedit dokumen kebijakan.
Untuk mengonfigurasi API, tambahkan dua set kebijakan:
- Atur Layanan Backend untuk merutekan permintaan ke Azure Data Manager untuk instans Energi
- Tulis ulang URI untuk menghapus awalan adme dan membangun permintaan ke API backend. Pernyataan kebijakan ini menggunakan ekspresi kebijakan untuk menambahkan nilai templat Url Operasi saat ini secara dinamis ke URL server kami.
Catat URL server dari langkah 5. Di bawah tag dasar , di bagian masuk , sisipkan dua pernyataan kebijakan berikut.
<set-backend-service backend-id="adme-backend" /><!-- replace the '/api/schema-service/v1' with the server URL for this API specification you noted in step 5 --> <rewrite-uri template="@{return "/api/schema-service/v1"+context.Operation.UrlTemplate;}" />Pilih Simpan untuk menerapkan perubahan.
Uji API dengan memilih operasi info Versi GET dari daftar operasi. Lalu pilih tab Uji untuk menavigasi ke Azure API Management Test Console.
Masukkan nilai yang dijelaskan dalam tabel berikut ini. Buat token autentikasi untuk Azure Data Manager for Energy Anda. Pilih Kirim untuk menguji API.
Pengaturan Nilai data-partition-id ID partisi data untuk instans Azure Data Manager for Energy Anda Produk Pilih produk Azure Data Manager for Energy yang dibuat sebelumnya Authorization "Pembawa" dan token autentikasi yang Anda buat 
Jika API dikonfigurasi dengan benar, Anda akan melihat respons HTTP 200 - OK yang terlihat mirip dengan cuplikan layar. Jika tidak, periksa bagian Pemecahan Masalah.
Ulangi langkah-langkah di atas untuk setiap Azure Data Manager for Energy API dan spesifikasi terkait.
Pemecahan Masalah
Selama pengujian API melalui Azure API Management, jika Anda mengalami kesalahan, mereka biasanya menunjuk ke masalah konfigurasi. Berdasarkan kesalahan, tinjau langkah-langkah resolusi potensial.
| Kode | Pesan kesalahan | Detail |
|---|---|---|
HTTP 401 Unauthorized |
Invalid Azure AD JWT |
Periksa untuk memastikan Anda memiliki header autentikasi yang valid untuk Penyewa ID Microsoft Entra dan Aplikasi Klien untuk instans Azure Data Manager for Energy Anda. |
HTTP 401 Unauthorized |
Azure AD JWT not present |
Periksa untuk memastikan header autentikasi ditambahkan ke permintaan pengujian Anda. |
HTTP 404 Not Found |
Kesalahan ini biasanya berarti bahwa permintaan ke API backend sedang dibuat ke URL yang salah. Lacak permintaan API Anda di API Management untuk memahami URL apa yang dihasilkan untuk permintaan backend dan pastikan url tersebut valid. Jika tidak, periksa kembali kebijakan penulisan ulang url atau backend. | |
HTTP 500 Internal Server Error |
Internal server error |
Kesalahan ini biasanya mencerminkan masalah dalam membuat permintaan ke API backend. Biasanya, dalam skenario ini, masalahnya terkait dengan layanan nama domain (DNS). Periksa untuk memastikan ada zona DNS privat yang dikonfigurasi di jaringan virtual Anda atau resolusi DNS kustom Anda memiliki penerus yang sesuai. Lacak permintaan API Anda di API Management untuk memahami permintaan backend apa yang dibuat dan kesalahan apa yang dilaporkan API Management saat mencoba membuat permintaan. |
Pertimbangan lain
Mode jaringan virtual internal API Management
Mode internal sepenuhnya mengisolasi Azure API Management alih-alih mengekspos titik akhir melalui alamat IP publik. Dalam konfigurasi ini, organisasi dapat memastikan bahwa semua Azure Data Manager for Energy bersifat internal. Karena Azure Data Manager for Energy adalah solusi kolaborasi untuk bekerja dengan mitra dan pelanggan, skenario ini mungkin tidak bermanfaat apa adanya.
App Gateway dengan firewall aplikasi web
Alih-alih menggunakan mode jaringan virtual internal saja, banyak organisasi memilih untuk menerapkan mekanisme proksi terbalik aman untuk mengekspos mode internal instans Azure API Management ke mitra dan pelanggan eksternal. Instans mode internal tetap sepenuhnya terisolasi dengan ingress yang dikontrol ketat yang harus melalui proksi.
Azure App Gateway adalah layanan umum untuk digunakan sebagai proksi terbalik. Azure App Gateway juga memiliki kemampuan firewall aplikasi web (WAF), yang secara aktif mendeteksi potensi serangan terhadap kerentanan dalam aplikasi dan API Anda.
Mengonfigurasi Azure API Management dengan domain kustom
Fitur umum lain dari arsitektur ini adalah menerapkan domain kustom ke API. Meskipun Azure Data Manager for Energy tidak mendukung fitur ini, Anda dapat mengonfigurasi domain kustom di Azure API Management sebagai gantinya.
Sertifikat untuk domain adalah prasyarat. Namun, Azure API Management mendukung pembuatan sertifikat terkelola gratis untuk domain kustom Anda.