API merkezinizde API analizini etkinleştirme - kendi kendine yönetilen

Bu makalede, bir lint altyapısını ve tetikleyicileri el ile ayarlayarak Azure API Center'da API analizinin nasıl etkinleştirileceği açıklanmaktadır. Bu özellikler, kuruluş stili kurallarına uymak için API tanımlarınızı analiz ederek hem bireysel hem de özet raporlar oluşturur. API analizi, API tanımlarınızdaki yaygın hataları ve tutarsızlıkları tanımlamanıza ve düzeltmenize yardımcı olur.

Senaryoya genel bakış

Bu senaryoda, Spektral açık kaynak lint altyapısını kullanarak API merkezinizdeki API tanımlarını analiz edebilirsiniz. Azure İşlevleri bir uygulama, API merkezinizdeki olaylara yanıt olarak lint altyapısını çalıştırır. Spektral, JSON veya YAML belirtim belgesinde tanımlanan API'lerin özelleştirilebilir api stili kılavuzundaki kurallara uygun olup olmadığını denetler. API merkezinizde görüntüleyebileceğiniz bir analiz raporu oluşturulur.

Aşağıdaki diyagramda API merkezinizde lint ve analizi etkinleştirme adımları gösterilmektedir.

1. Bir API tanımında Spectral linting altyapısını çalıştıran bir Azure İşlevleri uygulaması dağıtın.

2. İşlev uygulamasını tetikleyen bir Azure API merkezinde olay aboneliği yapılandırın.

3. API merkezinde bir API tanımı eklenerek veya değiştirilerek bir olay tetikleniyor.

4. Olayı aldıktan sonra işlev uygulaması Spektral lint altyapısını çağırır.

5. Linting altyapısı, tanımda tanımlanan API'lerin kuruluşun API stili kılavuzuna uygun olup olmadığını denetler ve bir rapor oluşturur.

6. ANALIZ raporunu API merkezinde görüntüleyin.

Linting altyapısını ve olay aboneliğini dağıtma seçenekleri

Bu makalede, API merkezinizde lint altyapısını ve olay aboneliğini dağıtmak için iki seçenek sağlanır:

• Otomatik dağıtım - Linting altyapısının tek adımlı dağıtımı için Azure geliştirici CLI'sını (azd) kullanın. Bu seçenek, kolaylaştırılmış bir dağıtım işlemi için önerilir.

• El ile dağıtım - Azure İşlevleri uygulamasını dağıtmak ve olay aboneliğini yapılandırmak için adım adım yönergeleri izleyin. Kaynakları el ile dağıtmayı ve yönetmeyi tercih ediyorsanız bu seçenek önerilir.

Sınırlamalar

• Linting şu anda yalnızca OpenAPI veya AsyncAPI belirtim belgeleri gibi JSON veya YAML belirtim dosyalarını destekler.
• Linting altyapısı varsayılan olarak yerleşik spectral:oas kural kümesini kullanır. Kural kümesini genişletmek veya özel API stili kılavuzları oluşturmak için Bkz . Spectral GitHub deposu.
• Lint işlemini çağıran Azure işlev uygulaması ayrı olarak ücretlendirilir ve bunu yönetip korursunuz.

Önkoşullar

• Azure aboneliğinizde bir API merkezi. Henüz oluşturmadıysanız bkz . Hızlı Başlangıç: API merkezinizi oluşturma.

• Aboneliğinizde kayıtlı Event Grid kaynak sağlayıcısı. Event Grid kaynak sağlayıcısını kaydetmeniz gerekiyorsa bkz . Azure Event Grid ile bir iş ortağı tarafından yayımlanan olaylara abone olma.

• Azure CLI için:

  • Azure Cloud Shell'de Bash ortamını kullanın. Daha fazla bilgi için bkz . Azure Cloud Shell'de Bash için hızlı başlangıç.

    

  • CLI başvuru komutlarını yerel olarak çalıştırmayı tercih ediyorsanız Azure CLI'yı yükleyin . Windows veya macOS üzerinde çalışıyorsanız Azure CLI’yi bir Docker kapsayıcısında çalıştırmayı değerlendirin. Daha fazla bilgi için bkz . Docker kapsayıcısında Azure CLI'yi çalıştırma.

    • Yerel yükleme kullanıyorsanız az login komutunu kullanarak Azure CLI ile oturum açın. Kimlik doğrulama işlemini tamamlamak için terminalinizde görüntülenen adımları izleyin. Diğer oturum açma seçenekleri için bkz . Azure CLI ile oturum açma.

    • İstendiğinde, ilk kullanımda Azure CLI uzantısını yükleyin. Uzantılar hakkında daha fazla bilgi için bkz. Azure CLI ile uzantıları kullanma.

    • Yüklü sürümü ve bağımlı kitaplıkları bulmak için az version komutunu çalıştırın. En son sürüme yükseltmek için az upgrade komutunu çalıştırın.

  Not

  az apic komutları Için Azure CLI uzantısı gerekir apic-extension . Komutları kullanmadıysanız az apic , ilk az apic komutunuzu çalıştırdığınızda uzantı dinamik olarak yüklenebilir veya uzantıyı el ile yükleyebilirsiniz. Azure CLI uzantıları hakkında daha fazla bilgi edinin.

  içindeki en son değişiklikler ve güncelleştirmeler için sürüm notlarınıapic-extensioninceleyin. Bazı özellikler, uzantının önizlemesini veya belirli bir sürümünü gerektirebilir.

  Not

  Bu makaledeki Azure CLI komut örnekleri PowerShell veya bash kabuğunda çalıştırılabilir. Farklı değişken söz dizimi nedeniyle gerektiğinde, iki kabuk için ayrı komut örnekleri sağlanır.

azdAzure İşlevleri uygulama ve olay aboneliği dağıtımı

Bu bölümde, API merkezinizde lint ve analizi etkinleştiren Azure İşlevleri uygulamasını ve olay aboneliğini yapılandırmak için Azure Geliştirici CLI'sini kullanarak otomatik adımlar sağlanır. Kaynakları el ile de yapılandırabilirsiniz.

Bu seçenek için diğer önkoşullar

• Azure Developer CLI (azd)

Kullanarak örneği çalıştırma azd

1. GitHub deposunu kopyalayın ve Visual Studio Code'da açın.

2. Dizini APICenter-Analyzer depodaki klasöre değiştirin.

3. resources/rulesets klasöründe bir oas.yaml dosya bulabilirsiniz. Bu dosya geçerli API stili kılavuzunuzu yansıtır ve kuruluş gereksinimlerinize ve gereksinimlerinize göre değiştirilebilir.

4. Aşağıdaki komutları kullanarak Azure Geliştirici CLI'sı ve Azure CLI ile kimlik doğrulaması yapın:

   azd auth login
   
   az login
   

5. Linting altyapısını Azure aboneliğinize dağıtmak için aşağıdaki komutu çalıştırın.

   azd up
   

6. Ortam adı ve API merkezi adı gibi gerekli dağıtım bilgilerini ve ayarlarını sağlamak için istemleri izleyin. Ayrıntılar için bkz . Azure Geliştirici CLI'sını (azd) kullanarak örneği çalıştırma.

   Not

   Dağıtım birkaç dakika sürebilir.

7. Dağıtım tamamlandıktan sonra Azure portalında API merkezinize gidin. Soldaki menüde Olaylar>Olay abonelikleri'ni seçerek oluşturulan olay aboneliğini görüntüleyin.

Artık olay aboneliğini tetikleyip lint altyapısını çalıştırmak için API merkezinize bir API tanım dosyası yükleyebilirsiniz.

Azure İşlevleri uygulama ve olay aboneliğini yapılandırmaya yönelik el ile adımlar

Bu bölümde, API merkezinizde lint ve analizi etkinleştirmek için Azure İşlevleri uygulamasını ve olay aboneliğini yapılandırmak için el ile dağıtım adımları sağlanır. Otomatik dağıtım için Azure Geliştirici CLI'sini de kullanabilirsiniz.

Bu seçenek için diğer önkoşullar

• Azure İşlevleri uzantısı v1.10.4 veya üzeri olan Visual Studio Code.

1. Adım. Azure İşlevleri uygulamanızı dağıtma

API tanımlarında linting işlevini çalıştıran Azure İşlevleri uygulamasını dağıtmak için:

1. GitHub deposunu kopyalayın ve Visual Studio Code'da açın.

2. resources/rulesets klasöründe bir oas.yaml dosya bulabilirsiniz. Bu dosya geçerli API stili kılavuzunuzu yansıtır ve kuruluş gereksinimlerinize ve gereksinimlerinize göre değiştirilebilir.

3. İsteğe bağlı olarak, test etmek için işlev uygulamasını yerel olarak çalıştırın. Ayrıntılar için depodaki README dosyasına bakın.

4. İşlev uygulamasını Azure'a dağıtın. Adımlar için bkz . Hızlı Başlangıç: Visual Studio Code kullanarak TypeScript ile Azure'da işlev oluşturma.

   Not

   İşlev uygulamasının dağıtılması birkaç dakika sürebilir.

5. Azure portalında oturum açın ve işlev uygulamasına gidin.

6. Genel Bakış sayfasında aşağıdaki ayrıntıları denetleyin:

   • İşlev uygulamasının Durumunun Çalışıyor olduğunu onaylayın.
   • İşlevler'in altında apicenter-analyzer işlevinin Durumunun Etkin olduğunu onaylayın.

   

2. Adım. İşlev uygulamanızda yönetilen kimliği yapılandırma

İşlev uygulamasının API merkezine erişmesini sağlamak için işlev uygulaması için yönetilen bir kimlik yapılandırın. Aşağıdaki adımlarda, Azure portalını veya Azure CLI'yı kullanarak işlev uygulaması için sistem tarafından atanan yönetilen kimliği etkinleştirme ve yapılandırma adımları gösterilmektedir.

3. Adım. API merkezinizde olay aboneliğini yapılandırma

Şimdi API tanım dosyası karşıya yüklendiğinde veya güncelleştirildiğinde işlev uygulamasını tetikleyecek bir olay aboneliği oluşturun. Aşağıdaki adımlarda Azure portalını veya Azure CLI'yi kullanarak olay aboneliğinin nasıl oluşturulacağı gösterilmektedir.

API merkezinizde olay tetikleme

Olay aboneliğini test etmek için API merkezinizdeki bir API sürümüyle ilişkili API tanım dosyasını karşıya yüklemeyi veya güncelleştirmeyi deneyin. Örneğin, bir OpenAPI veya AsyncAPI belgesi yükleyin. Olay aboneliği tetiklendiğinde işlev uygulaması API tanımını analiz etmek için API linting altyapısını çağırır.

• API merkezinize API, API sürümü ve API tanımı eklemeye yönelik ayrıntılı adımlar için bkz . Öğretici: API'leri API merkezinize kaydetme.
• Azure CLI kullanarak bir API tanım dosyasını karşıya yükleyerek API oluşturmak için bkz . Api'yi belirtim dosyasından kaydetme.

Olay aboneliğinin tetiklendiğini onaylamak için:

1. API merkezinize gidin ve sol menüden Olaylar'ı seçin.

2. Olay Abonelikleri sekmesini seçin ve işlev uygulamanız için olay aboneliğini seçin.

3. Olay aboneliğinin tetiklendiğini ve lint işleminin başarıyla başlatıldığını onaylamak için ölçümleri gözden geçirin.

   

   Not

   Ölçümlerin görünmesi birkaç dakika sürebilir.

API tanımını analiz ettikten sonra, linting altyapısı yapılandırılan API stili kılavuzuna göre bir rapor oluşturur.

API çözümleme raporlarını görüntüleme

API tanımınızın analiz raporunu Azure portalında görüntüleyebilirsiniz. Bir API tanımı çözümlendiğinde, rapor yapılandırılan API stili kılavuzuna göre hataları, uyarıları ve bilgileri listeler.

Portalda, API merkezinizdeki tüm API tanımları için analiz raporlarının özetini de görüntüleyebilirsiniz.

API tanımı için analiz raporu

API merkezinizdeki bir API tanımının analiz raporunu görüntülemek için:

1. Portalda API tanımını eklediğiniz veya güncelleştirdiğiniz API merkezinizdeki API sürümüne gidin.
2. Soldaki menüde, Ayrıntılar'ın altında Tanımlar'ı seçin.
3. Karşıya yüklediğiniz veya güncelleştirdiğiniz API tanımını seçin.
4. Çözümleme sekmesini seçin.

API Çözümleme Raporu açılır ve yapılandırılan API stili kılavuzuna göre API tanımını ve hatalarını, uyarılarını ve bilgilerini görüntüler. Aşağıdaki ekran görüntüsünde BIR API çözümleme raporu örneği gösterilmektedir.

API analizi özeti

API merkezinizdeki tüm API tanımlarının analiz raporlarının özetini görüntülemek için:

1. Portalda API merkezinize gidin.

2. Sol taraftaki menüde, İdare'nin altında API Analizi'ni seçin. Özet görüntülenir.

   

İlgili içerik

Event Grid hakkında daha fazla bilgi edinin:

• API merkezinizde API analizini etkinleştirme - Microsoft tarafından yönetilen
• Azure Event Grid'deki sistem konuları
• Event Grid anında iletme teslimi - kavramlar
• Azure API Center için Event Grid şeması