Mengaktifkan linting dan analisis untuk tata kelola API di pusat API Anda

Artikel ini menunjukkan cara mengaktifkan linting untuk menganalisis definisi API di pusat API organisasi Anda agar sesuai dengan aturan gaya API organisasi Anda. Linting menghasilkan laporan analisis yang dapat Anda akses di pusat API Anda. Gunakan linting dan analisis API untuk mendeteksi kesalahan umum dan inkonsistensi dalam definisi API Anda.

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 kepatuhan API dihasilkan yang dapat Anda lihat di pusat API Anda.

Diagram berikut menunjukkan langkah-langkah untuk mengaktifkan linting dan analisis di pusat API Anda.

1. Sebarkan aplikasi Azure Functions yang menjalankan mesin linting Spectral pada definisi API.

2. Konfigurasikan langganan peristiwa di pusat Azure API untuk memicu aplikasi fungsi.

3. Peristiwa dipicu dengan menambahkan atau mengganti definisi API di pusat API.

4. Saat menerima peristiwa, aplikasi fungsi memanggil mesin linting Spectral.

5. Mesin linting memeriksa bahwa API yang ditentukan dalam definisi sesuai dengan panduan gaya API organisasi dan menghasilkan laporan.

6. 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 diinstal secara dinamis saat Anda menjalankan perintah pertama az apic Anda. Pelajari selengkapnya tentang ekstensi Azure CLI.

  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

1. Kloning repositori GitHub dan buka di Visual Studio Code.

2. Ubah direktori ke APICenter-Analyzer folder di repositori.

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

4. Autentikasi dengan Azure Developer CLI dan Azure CLI menggunakan perintah berikut:

   azd auth login
   
   az login
   

5. Jalankan perintah berikut untuk menyebarkan infrastruktur linting ke langganan Azure Anda.

   azd up
   

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

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

1. Kloning repositori GitHub dan buka di Visual Studio Code.

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

3. Secara opsional, jalankan aplikasi fungsi secara lokal untuk mengujinya. Untuk detailnya, lihat file README di repositori.

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

5. Masuk ke portal Azure, dan buka aplikasi fungsi.

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

1. Di portal Azure, navigasikan ke aplikasi fungsi Anda dan pilih Identitas di bawah bagian Pengaturan.
2. 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.

1. Di portal Azure, navigasikan ke pusat API Anda dan pilih Kontrol akses (IAM).
2. Pilih + Tambahkan > penetapan peran.
3. Pilih Peran fungsi pekerjaan lalu pilih Azure API Center Compliance Manager. Pilih Selanjutnya.
4. Pada halaman Anggota , di Tetapkan akses ke, pilih Identitas > terkelola + Pilih anggota.
5. Pada halaman Pilih identitas terkelola, cari dan pilih identitas terkelola aplikasi fungsi. Klik Pilih lalu Berikutnya.
6. Tinjau penetapan peran, dan pilih Tinjau + tetapkan.

Azure CLI

1. 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)
   

2. 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 service show --name <apic-name> --resource-group <resource-group-name> \
       --query "id" --output tsv)
   

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

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

1. Di portal Azure, navigasikan ke pusat API Anda dan pilih Peristiwa.

2. Pada tab Memulai , pilih Azure Function.

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

      

4. Pilih tab Langganan peristiwa dan pilih Refresh. Konfirmasikan bahwa status Provisi langganan peristiwa Berhasil.

   

Azure CLI

1. 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 service show --name <apic-name> --resource-group <resource-group-name> \
       --query "id" --output tsv)
   

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

2. 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)
   

3. 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:

1. Navigasi ke pusat API Anda, dan pilih Peristiwa di menu sebelah kiri.

2. Pilih tab Langganan Peristiwa dan pilih langganan peristiwa untuk aplikasi fungsi Anda.

3. 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:

1. Di portal, navigasikan ke versi API di pusat API tempat Anda menambahkan atau memperbarui definisi API.
2. Di menu sebelah kiri, di bawah Detail, pilih Definisi.
3. Pilih definisi API yang Anda unggah atau perbarui.
4. 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:

1. Di portal, navigasikan ke pusat API Anda.

2. Di menu sebelah kiri, di bawah Tata Kelola, pilih Analisis API. Ringkasan muncul.

   

Konten terkait

Pelajari selengkapnya tentang Event Grid:

• Topik sistem di Azure Event Grid
• Pengiriman push Event Grid - konsep
• Skema Event Grid untuk Azure API Center