Mengaktifkan analisis API di pusat API Anda - dikelola sendiri

Artikel
12/03/2024

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 memerlukan apic-extension ekstensi Azure CLI. Jika Anda belum menggunakan az apic perintah, ekstensi dapat diinstal secara dinamis saat Anda menjalankan perintah pertama az 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

Azure Developer CLI (azd)

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 menemukan oas.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 menemukan oas.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.

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

Aktifkan identitas aplikasi fungsi yang ditetapkan sistem menggunakan perintah az functionapp identity assign . Ganti <function-app-name> dan <resource-group-name> dengan nama aplikasi fungsi dan nama grup sumber daya Anda. Perintah berikut menyimpan ID utama identitas terkelola yang ditetapkan sistem dalam principalID variabel.

#! /bin/bash
principalID=$(az functionapp identity assign --name <function-app-name> \
    --resource-group <resource-group-name> --identities [system] \
    --query "principalId" --output tsv)

# PowerShell syntax
$principalID=$(az functionapp identity assign --name <function-app-name> `
    --resource-group <resource-group-name> --identities [system] `
    --query "principalId" --output tsv)

Dapatkan ID sumber daya pusat API Anda. Ganti <apic-name> dan <resource-group-name> dengan nama pusat API dan nama grup sumber daya Anda.

#! /bin/bash
apicID=$(az apic show --name <apic-name> --resource-group <resource-group-name> \
    --query "id" --output tsv)

# PowerShell syntax
$apicID=$(az apic show --name <apic-name> --resource-group <resource-group-name> `
    --query "id" --output tsv)

Tetapkan identitas terkelola aplikasi fungsi peran Azure API Center Compliance Manager di pusat API menggunakan perintah az role assignment create .

#! /bin/bash
az role assignment create \
    --role "Azure API Center Compliance Manager" \
    --assignee-object-id $principalID \
    --assignee-principal-type ServicePrincipal \
    --scope $apicID

# PowerShell syntax
az role assignment create `
    --role "Azure API Center Compliance Manager" `
    --assignee-object-id $principalID `
    --assignee-principal-type ServicePrincipal `
    --scope $apicID

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.

Portal
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:
1. Masukkan Nama deskriptif untuk langganan peristiwa, dan pilih Skema Event Grid.
2. Di Detail topik, masukkan Nama topik sistem pilihan Anda.
3. Di Jenis Peristiwa, pilih peristiwa berikut:
  - Definisi API ditambahkan
  - Definisi API diperbarui
4. Di Detail Titik Akhir, pilih Azure Function > Mengonfigurasi titik akhir.
5. Pada halaman Pilih Azure Function , pilih aplikasi fungsi dan fungsi apicenter-linter yang Anda konfigurasikan. Klik Konfirmasi pilihan.
6. Pilih Buat.
Pilih tab Langganan peristiwa dan pilih Refresh. Konfirmasikan bahwa status Provisi langganan peristiwa Berhasil.

Dapatkan ID sumber daya pusat API Anda. Ganti <apic-name> dan <resource-group-name> dengan nama pusat API dan nama grup sumber daya Anda.

#! /bin/bash
apicID=$(az apic show --name <apic-name> --resource-group <resource-group-name> \
    --query "id" --output tsv)

# PowerShell syntax
$apicID=$(az apic show --name <apic-name> --resource-group <resource-group-name> `
    --query "id" --output tsv)

Dapatkan ID sumber daya fungsi di aplikasi fungsi. Dalam contoh ini, nama fungsinya adalah apicenter-analyzer. Ganti <function-app-name> dan <resource-group-name> dengan nama aplikasi fungsi dan nama grup sumber daya Anda.

#! /bin/bash
functionID=$(az functionapp function show --name <function-app-name> \
    --function-name apicenter-analyzer --resource-group <resource-group-name> \
    --query "id" --output tsv)

# PowerShell syntax
$functionID=$(az functionapp function show --name <function-app-name> `
    --function-name apicenter-analyzer --resource-group <resource-group-name> `
    --query "id" --output tsv)

Buat langganan peristiwa menggunakan perintah az eventgrid event-subscription create . Langganan yang dibuat mencakup peristiwa untuk menambahkan atau memperbarui definisi API.

#! /bin/bash
az eventgrid event-subscription create --name MyEventSubscription \
    --source-resource-id "$apicID" --endpoint "$functionID" \
    --endpoint-type azurefunction --included-event-types \
    Microsoft.ApiCenter.ApiDefinitionAdded Microsoft.ApiCenter.ApiDefinitionUpdated

# PowerShell syntax
az eventgrid event-subscription create --name MyEventSubscription `
    --source-resource-id "$apicID" --endpoint "$functionID" `
    --endpoint-type azurefunction --included-event-types `
    Microsoft.ApiCenter.ApiDefinitionAdded Microsoft.ApiCenter.ApiDefinitionUpdated

Output perintah memperlihatkan detail langganan peristiwa. Anda juga bisa mendapatkan detail menggunakan perintah az eventgrid event-subscription show . Contoh:

az eventgrid event-subscription show --name MyEventSubscription --source-resource-id "$apicID"

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.

Pelajari selengkapnya tentang Event Grid:

Bagikan melalui

Mengaktifkan analisis API di pusat API Anda - dikelola sendiri

Gambaran umum skenario

Opsi untuk menyebarkan mesin linting dan langganan peristiwa

Batasan

Prasyarat

`azd` penyebaran aplikasi Azure Functions dan langganan peristiwa

Prasyarat lain untuk opsi ini

Jalankan sampel menggunakan `azd`

Langkah-langkah manual untuk mengonfigurasi aplikasi Azure Functions dan langganan peristiwa

Prasyarat lain untuk opsi ini

Langkah 1. Menyebarkan aplikasi Azure Functions Anda

Langkah 2. Mengonfigurasi identitas terkelola di aplikasi fungsi Anda

Langkah 3. Mengonfigurasi langganan peristiwa di pusat API Anda

Memicu peristiwa di pusat API Anda

Melihat laporan analisis API

Laporan analisis untuk definisi API

Ringkasan analisis API

Saran dan Komentar

Sumber Daya Tambahan:

Bagikan melalui

Mengaktifkan analisis API di pusat API Anda - dikelola sendiri

Gambaran umum skenario

Opsi untuk menyebarkan mesin linting dan langganan peristiwa

Batasan

Prasyarat

azd penyebaran aplikasi Azure Functions dan langganan peristiwa

Prasyarat lain untuk opsi ini

Jalankan sampel menggunakan azd

Langkah-langkah manual untuk mengonfigurasi aplikasi Azure Functions dan langganan peristiwa

Prasyarat lain untuk opsi ini

Langkah 1. Menyebarkan aplikasi Azure Functions Anda

Langkah 2. Mengonfigurasi identitas terkelola di aplikasi fungsi Anda

Langkah 3. Mengonfigurasi langganan peristiwa di pusat API Anda

Memicu peristiwa di pusat API Anda

Melihat laporan analisis API

Laporan analisis untuk definisi API

Ringkasan analisis API

Konten terkait

Saran dan Komentar

Sumber Daya Tambahan:

`azd` penyebaran aplikasi Azure Functions dan langganan peristiwa

Jalankan sampel menggunakan `azd`