Mengaktifkan analisis API di pusat API Anda - dikelola sendiri
Artikel ini menjelaskan cara mengaktifkan analisis API di Azure API Center dengan menyiapkan mesin dan pemicu linting secara manual. Kemampuan ini menganalisis definisi API Anda untuk kepatuhan terhadap aturan gaya organisasi, menghasilkan laporan individual dan ringkasan. Analisis API membantu mengidentifikasi dan memperbaiki kesalahan umum dan inkonsistensi dalam definisi API Anda.
Catatan
Dalam pratinjau, Azure API Center secara otomatis mengonfigurasi mesin dan dependensi linting default untuk analisis API. Jika Anda mengaktifkan analisis yang dikelola sendiri seperti yang dijelaskan dalam artikel ini, Anda mengambil alih fitur bawaan ini.
Gambaran umum skenario
Dalam skenario ini, Anda menganalisis definisi API di pusat API Anda dengan menggunakan mesin Spectral sumber terbuka linting. Aplikasi Azure Functions menjalankan mesin linting sebagai respons terhadap peristiwa di pusat API Anda. Spectral memeriksa bahwa API yang ditentukan dalam dokumen spesifikasi JSON atau YAML sesuai dengan aturan dalam panduan gaya API yang dapat disesuaikan. Laporan analisis dihasilkan yang dapat Anda lihat di pusat API Anda.
Diagram berikut menunjukkan langkah-langkah untuk mengaktifkan linting dan analisis di pusat API Anda.
Sebarkan aplikasi Azure Functions yang menjalankan mesin linting Spectral pada definisi API.
Konfigurasikan langganan peristiwa di pusat Azure API untuk memicu aplikasi fungsi.
Peristiwa dipicu dengan menambahkan atau mengganti definisi API di pusat API.
Saat menerima peristiwa, aplikasi fungsi memanggil mesin linting Spectral.
Mesin linting memeriksa bahwa API yang ditentukan dalam definisi sesuai dengan panduan gaya API organisasi dan menghasilkan laporan.
Lihat laporan analisis di pusat API.
Opsi untuk menyebarkan mesin linting dan langganan peristiwa
Artikel ini menyediakan dua opsi untuk menyebarkan mesin linting dan langganan peristiwa di pusat API Anda:
Penyebaran otomatis - Gunakan CLI pengembang Azure (
azd
) untuk penyebaran satu langkah infrastruktur linting. Opsi ini direkomendasikan untuk proses penyebaran yang disederhanakan.Penyebaran manual - Ikuti panduan langkah demi langkah untuk menyebarkan aplikasi Azure Functions dan mengonfigurasi langganan peristiwa. Opsi ini direkomendasikan jika Anda lebih suka menyebarkan dan mengelola sumber daya secara manual.
Batasan
- Linting saat ini hanya mendukung file spesifikasi JSON atau YAML, seperti dokumen spesifikasi OpenAPI atau AsyncAPI.
- Secara default, mesin linting menggunakan ruleset bawaan.
spectral:oas
Untuk memperluas set aturan atau membuat panduan gaya API kustom, lihat repositori Spectral GitHub. - Aplikasi fungsi Azure yang memanggil linting dibebankan secara terpisah, dan Anda mengelola dan memeliharanya.
Prasyarat
Pusat API di langganan Azure Anda. Jika Anda belum membuatnya, lihat Mulai Cepat: Membuat pusat API Anda.
Penyedia sumber daya Event Grid terdaftar di langganan Anda. Jika Anda perlu mendaftarkan penyedia sumber daya Event Grid, lihat Berlangganan peristiwa yang diterbitkan oleh mitra dengan Azure Event Grid.
Untuk Azure CLI:
Gunakan lingkungan Bash di Azure Cloud Shell. Untuk informasi selengkapnya, lihat Mulai Cepat untuk Bash di Azure Cloud Shell.
Jika Anda lebih suka menjalankan perintah referensi CLI secara lokal, instal Azure CLI. Jika Anda menjalankan Windows atau macOS, pertimbangkan untuk menjalankan Azure CLI dalam kontainer Docker. Untuk informasi lebih lanjut, lihat Cara menjalankan Azure CLI di kontainer Docker.
Jika Anda menggunakan instalasi lokal, masuk ke Azure CLI dengan menggunakan perintah login az. Untuk menyelesaikan proses autentikasi, ikuti langkah-langkah yang ditampilkan di terminal Anda. Untuk opsi masuk lainnya, lihat Masuk dengan Azure CLI.
Saat Anda diminta, instal ekstensi Azure CLI pada penggunaan pertama. Untuk informasi selengkapnya tentang ekstensi, lihat Menggunakan ekstensi dengan Azure CLI.
Jalankan versi az untuk menemukan versi dan pustaka dependen yang diinstal. Untuk meningkatkan ke versi terbaru, jalankan peningkatan az.
Catatan
az apic
perintah memerlukanapic-extension
ekstensi Azure CLI. Jika Anda belum menggunakanaz apic
perintah, ekstensi dapat diinstal secara dinamis saat Anda menjalankan perintah pertamaaz apic
, atau Anda dapat menginstal ekstensi secara manual. Pelajari selengkapnya tentang ekstensi Azure CLI.Lihat catatan rilis untuk perubahan dan pembaruan terbaru di
apic-extension
. Fitur tertentu mungkin memerlukan pratinjau atau versi ekstensi tertentu.Catatan
Contoh perintah Azure CLI dalam artikel ini dapat berjalan di PowerShell atau shell bash. Jika diperlukan karena sintaks variabel yang berbeda, contoh perintah terpisah disediakan untuk dua shell.
azd
penyebaran aplikasi Azure Functions dan langganan peristiwa
Bagian ini menyediakan langkah-langkah otomatis menggunakan Azure Developer CLI untuk mengonfigurasi aplikasi Azure Functions dan langganan peristiwa yang mengaktifkan linting dan analisis di pusat API Anda. Anda juga dapat mengonfigurasi sumber daya secara manual.
Prasyarat lain untuk opsi ini
Jalankan sampel menggunakan azd
Kloning repositori GitHub dan buka di Visual Studio Code.
Ubah direktori ke
APICenter-Analyzer
folder di repositori.resources/rulesets
Di folder, Anda dapat menemukanoas.yaml
file. File ini mencerminkan panduan gaya API Anda saat ini dan dapat dimodifikasi berdasarkan kebutuhan dan persyaratan organisasi Anda.Autentikasi dengan Azure Developer CLI dan Azure CLI menggunakan perintah berikut:
azd auth login az login
Jalankan perintah berikut untuk menyebarkan infrastruktur linting ke langganan Azure Anda.
azd up
Ikuti perintah untuk memberikan informasi dan pengaturan penyebaran yang diperlukan, seperti nama lingkungan dan nama pusat API. Untuk detailnya, lihat Menjalankan sampel menggunakan Azure Developer CLI (azd).
Catatan
Penyebaran mungkin perlu waktu beberapa menit.
Setelah penyebaran selesai, navigasikan ke pusat API Anda di portal Azure. Di menu sebelah kiri, pilih langganan Peristiwa>Peristiwa untuk melihat langganan peristiwa yang dibuat.
Anda sekarang dapat mengunggah file definisi API ke pusat API Anda untuk memicu langganan peristiwa dan menjalankan mesin linting.
Langkah-langkah manual untuk mengonfigurasi aplikasi Azure Functions dan langganan peristiwa
Bagian ini menyediakan langkah-langkah penyebaran manual untuk mengonfigurasi aplikasi Azure Functions dan langganan peristiwa untuk mengaktifkan linting dan analisis di pusat API Anda. Anda juga dapat menggunakan Azure Developer CLI untuk penyebaran otomatis.
Prasyarat lain untuk opsi ini
- Visual Studio Code dengan ekstensi Azure Functions v1.10.4 atau yang lebih baru.
Langkah 1. Menyebarkan aplikasi Azure Functions Anda
Untuk menyebarkan aplikasi Azure Functions yang menjalankan fungsi linting pada definisi API:
Kloning repositori GitHub dan buka di Visual Studio Code.
resources/rulesets
Di folder, Anda dapat menemukanoas.yaml
file. File ini mencerminkan panduan gaya API Anda saat ini dan dapat dimodifikasi berdasarkan kebutuhan dan persyaratan organisasi Anda.Secara opsional, jalankan aplikasi fungsi secara lokal untuk mengujinya. Untuk detailnya, lihat file README di repositori.
Sebarkan aplikasi fungsi ke Azure. Untuk langkah-langkahnya, lihat Mulai Cepat: Membuat fungsi di Azure dengan TypeScript menggunakan Visual Studio Code.
Catatan
Menyebarkan aplikasi fungsi mungkin memakan waktu beberapa menit.
Masuk ke portal Azure, dan buka aplikasi fungsi.
Pada halaman Gambaran Umum , periksa detail berikut ini:
- Konfirmasikan bahwa Status aplikasi fungsi Sedang Berjalan.
- Di bawah Functions, konfirmasikan bahwa Statusfungsi apicenter-analyzer Diaktifkan.
Langkah 2. Mengonfigurasi identitas terkelola di aplikasi fungsi Anda
Untuk mengaktifkan aplikasi fungsi untuk mengakses pusat API, konfigurasikan identitas terkelola untuk aplikasi fungsi. Langkah-langkah berikut menunjukkan cara mengaktifkan dan mengonfigurasi identitas terkelola yang ditetapkan sistem untuk aplikasi fungsi menggunakan portal Azure atau Azure CLI.
- Di portal Azure, navigasikan ke aplikasi fungsi Anda dan pilih Identitas di bawah bagian Pengaturan.
- Pada tab Sistem yang ditetapkan, atur Status ke Aktif lalu pilih Simpan.
Sekarang setelah identitas terkelola diaktifkan, tetapkan peran Azure API Center Compliance Manager untuk mengakses pusat API.
- Di portal Azure, navigasikan ke pusat API Anda dan pilih Kontrol akses (IAM).
- Pilih + Tambahkan > penetapan peran.
- Pilih Peran fungsi pekerjaan lalu pilih Azure API Center Compliance Manager. Pilih Selanjutnya.
- Pada halaman Anggota , di Tetapkan akses ke, pilih Identitas > terkelola + Pilih anggota.
- Pada halaman Pilih identitas terkelola, cari dan pilih identitas terkelola aplikasi fungsi. Klik Pilih lalu Berikutnya.
- Tinjau penetapan peran, dan pilih Tinjau + tetapkan.
Langkah 3. Mengonfigurasi langganan peristiwa di pusat API Anda
Sekarang buat langganan peristiwa di pusat API Anda untuk memicu aplikasi fungsi saat file definisi API diunggah atau diperbarui. Langkah-langkah berikut menunjukkan cara membuat langganan peristiwa menggunakan portal Azure atau Azure CLI.
Di portal Azure, navigasikan ke pusat API Anda dan pilih Peristiwa.
Pada tab Memulai , pilih Azure Function.
Pada halaman Buat Langganan Peristiwa, lakukan hal berikut ini:
Masukkan Nama deskriptif untuk langganan peristiwa, dan pilih Skema Event Grid.
Di Detail topik, masukkan Nama topik sistem pilihan Anda.
Di Jenis Peristiwa, pilih peristiwa berikut:
- Definisi API ditambahkan
- Definisi API diperbarui
Di Detail Titik Akhir, pilih Azure Function > Mengonfigurasi titik akhir.
Pada halaman Pilih Azure Function , pilih aplikasi fungsi dan fungsi apicenter-linter yang Anda konfigurasikan. Klik Konfirmasi pilihan.
Pilih Buat.
Pilih tab Langganan peristiwa dan pilih Refresh. Konfirmasikan bahwa status Provisi langganan peristiwa Berhasil.
Catatan
Mungkin perlu waktu singkat agar langganan peristiwa disebarluaskan ke aplikasi fungsi.
Memicu peristiwa di pusat API Anda
Untuk menguji langganan peristiwa, coba unggah atau perbarui file definisi API yang terkait dengan versi API di pusat API Anda. Misalnya, unggah dokumen OpenAPI atau AsyncAPI. Setelah langganan peristiwa dipicu, aplikasi fungsi memanggil mesin linting API untuk menganalisis definisi API.
- Untuk langkah-langkah terperinci untuk menambahkan definisi API, versi API, dan API ke pusat API Anda, lihat Tutorial: Mendaftarkan API di pusat API Anda.
- Untuk membuat API dengan mengunggah file definisi API menggunakan Azure CLI, lihat Mendaftarkan API dari file spesifikasi.
Untuk mengonfirmasi bahwa langganan peristiwa dipicu:
Navigasi ke pusat API Anda, dan pilih Peristiwa di menu sebelah kiri.
Pilih tab Langganan Peristiwa dan pilih langganan peristiwa untuk aplikasi fungsi Anda.
Tinjau metrik untuk mengonfirmasi bahwa langganan peristiwa dipicu dan bahwa linting berhasil dipanggil.
Catatan
Mungkin perlu waktu beberapa menit agar metrik muncul.
Setelah menganalisis definisi API, mesin linting menghasilkan laporan berdasarkan panduan gaya API yang dikonfigurasi.
Melihat laporan analisis API
Anda dapat melihat laporan analisis untuk definisi API Anda di portal Azure. Setelah definisi API dianalisis, laporan mencantumkan kesalahan, peringatan, dan informasi berdasarkan panduan gaya API yang dikonfigurasi.
Di portal, Anda juga dapat melihat ringkasan laporan analisis untuk semua definisi API di pusat API Anda.
Laporan analisis untuk definisi API
Untuk melihat laporan analisis untuk definisi API di pusat API Anda:
- Di portal, navigasikan ke versi API di pusat API tempat Anda menambahkan atau memperbarui definisi API.
- Di menu sebelah kiri, di bawah Detail, pilih Definisi.
- Pilih definisi API yang Anda unggah atau perbarui.
- Pilih tab Analisis .
Laporan Analisis API terbuka, dan menampilkan definisi api dan kesalahan, peringatan, dan informasi berdasarkan panduan gaya API yang dikonfigurasi. Cuplikan layar berikut menunjukkan contoh laporan analisis API.
Ringkasan analisis API
Untuk melihat ringkasan laporan analisis untuk semua definisi API di pusat API Anda:
Di portal, navigasikan ke pusat API Anda.
Di menu sebelah kiri, di bawah Tata Kelola, pilih Analisis API. Ringkasan muncul.
Konten terkait
Pelajari selengkapnya tentang Event Grid: