API merkezinizdeki API'leri analiz etme - Microsoft tarafından yönetilen

Kuruluşunuzun API merkezi , hem bireysel hem de özet raporlar oluşturarak api tanımlarını kuruluş stili kurallarına uygun olarak analiz etmek için yerleşik, Microsoft tarafından yönetilen lint özellikleri (önizleme) içerir. API analizi, API tanımlarınızdaki yaygın hataları ve tutarsızlıkları tanımlamanıza ve düzeltmenize yardımcı olur.

API analizi ile:

  • Azure API Center, BIR API tanımı eklediğinizde veya güncelleştirdiğinizde API tanımlarınızı otomatik olarak analiz eder. API tanımlarınızın lint işlemi varsayılan olarak bir spectral:oas kural kümesi (API stil kılavuzu) ile yapılır.
  • API çözümleme raporları Azure portalında oluşturulur ve API tanımlarınızın stil kılavuzuna nasıl uygun olduğunu gösterir.
  • Analiz edilen API'lerin kural kümesini ve filtre koşullarını belirtmek için analiz profillerini kullanın. Visual Studio Code için Azure API Center uzantısını kullanarak profilin kural kümesini özelleştirin.

Önemli

İsterseniz, özel bir Azure işlevi kullanarak yerleşik özellikleri geçersiz kılarak kendi kendine yönetilen lint ve analizi etkinleştirebilirsiniz. Yönetilen API analizini kullanmadan önce manuel olarak yönetilen linting işlemleri için kullanılan tüm öğeleri devre dışı bırakın.

Sınırlamalar

  • Şu anda yalnızca JSON veya YAML biçimindeki OpenAPI ve AsyncAPI belirtim belgeleri analiz edilir.
  • Analiz profili sayısı ve analiz edilen maksimum API tanımı sayısı için sınırlar vardır. Analizin tamamlanması birkaç dakika ile 24 saat kadar sürebilir.

Önkoşullar

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

Azure portalında API tanımlarınız için analiz özetini ve analiz raporlarını görüntüleyin. API tanımları analiz ettikten sonra raporlar, yapılandırılan API stili kılavuzuna göre hataları, uyarıları ve bilgileri listeler.

API çözümleme raporunda, analiz için kullanılan kural kümesini ve lint geçişlerinin geçmişini de gözden geçirin.

API merkezinizde analiz ö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.

    Portaldaki API analizi özetinin ekran görüntüsü.

  3. İsterseniz bir API tanımı için API Çözümleme Raporu simgesini seçin. Tanımın API çözümleme raporu, aşağıdaki ekran görüntüsünde gösterildiği gibi görüntülenir.

    Portaldaki bir API analizi raporunun ekran görüntüsü.

    İpucu

    API tanımının menü çubuğundan Çözümleme'yi seçerek API çözümleme raporunu görüntüleyebilirsiniz.

Analiz profillerini yönetme

Azure API Center, API'leri lint etmek ve analiz etmek için analysis profillerini kullanır. Analiz profili bir kural kümesi belirtir ve isteğe bağlı olarak analiz edilen API'ler için koşulları filtreler. Varsayılan çözümleme profili, kural kümesini tüm OpenAPI ve AsyncAPI tanımlarına uygular spectral:oas .

Kural kümesini özelleştirebilir ve varsayılan profilde filtre koşulları tanımlayabilir veya yeni bir profil oluşturabilirsiniz. Örneğin, geliştirme aşamasında olan API'ler için bir profil ve üretimde olan API'ler için farklı bir profil kullanmak isteyebilirsiniz.

Uyarı

API Center'ın Standart planında en fazla üç analiz profili oluşturabilirsiniz. Ücretsiz planda yalnızca tek bir profil desteklenir.

Analiz profili oluşturmak için:

  1. Azure portalında API merkezinize gidin.
  2. Sol taraftaki menüde Yönetim altında API Analizi>Analiz profillerini> yönet ve + Analiz profili oluştur'u seçin.
  3. Yeni analiz profili oluştur bölmesinde profil için bir Ad ve Açıklama girin.
  4. Kural Kümesi'nde, kural kümesinin analiz türü (linting motoru) görüntülenir. Şu anda yalnızca Spectral desteklenmektedir.
  5. Filtre koşullarını tanımla altında, profilin uygulandığı API tanımları için bir veya daha fazla filtre koşulu ekleyin.
  6. Oluştur'u seçin.

Portalda analiz profili oluşturma işleminin ekran görüntüsü.

Profil oluşturulur ve bir kural kümesi iskeleti oluşturulur. Geçerli kural kümesini görüntülemek için profili seçin ve bağlam (...) menüsünde Kural kümesini görüntüle'yi seçin.

Kural kümesini özelleştirmek için aşağıdaki bölümlere geçin.

Profilin kural kümesini özelleştirme

Profilin kural kümesini özelleştirmek için Azure API Center için Visual Studio Code uzantısını kullanın. Kural kümesini özelleştirdikten ve yerel olarak test ettikten sonra API merkezinize geri dağıtabilirsiniz.

  1. Visual Studio Code'da Etkinlik Çubuğu'ndan Azure API Center simgesini seçin.
  2. API Center bölmesinde, üzerinde çalıştığınız API center kaynağını genişletin ve Profiller'i genişletin.
  3. Değiştirmek istediğiniz profili genişletin ve ruleset.yaml seçeneğini seçin.
  4. İçeriği gerektiği gibi değiştirin veya yerine koyun.
  5. Değişikliklerinizi olarak ruleset.yamlkaydedin.

Kural kümesini yerel olarak test edin

Özel kural kümesini API merkezinize dağıtmadan önce yerel olarak doğrulayın. Visual Studio Code için Azure API Center uzantısı, Spectral ile API spesifikasyonu kontrolü için tümleşik destek sağlar.

  1. Visual Studio Code'da, Komut Paleti'ni açmak için Ctrl+Shift+P klavye kısayolunu kullanın.

  2. Azure API Center: Etkin API Stil Kılavuzu'nu ayarlayın ve Enter tuşuna basın.

  3. Yerel Dosya Seç seçeneğini seçin ve özelleştirdiğiniz ruleset.yaml dosyasını belirtin. Enter tuşuna basın.

    Bu adım, özel kural kümesini yerel kod denetimi için aktif API stil kılavuzu yapar.

Artık OpenAPI tabanlı bir API tanım dosyasını açtığınızda, Visual Studio Code'da yerel bir linting işlemi otomatik olarak tetikleniyor. Sonuçlar düzenleyicide ve Problemler penceresinde (Görünüm > Problemler veya Ctrl+Shift+M) satır içi olarak görüntülenir.

İpucu

Kuruluşunuzdaki API geliştiricileri, API'leri API merkezinize kaydetmeden önce API tanımlarını geliştirmeye yardımcı olmak için bu yerel lint özelliğini de kullanabilir.

Visual Studio Code'da API tanımını lint etme ekran görüntüsü.

Lint sonuçlarını gözden geçirin. Kural kümesinde gerekli ayarlamaları yapın ve istediğiniz şekilde performans gösterene kadar yerel olarak test etmeye devam edin.

Kural kümesini API merkezinize dağıtma

Özel kural kümesini API merkezinize dağıtmak için:

  1. Visual Studio Code'da Etkinlik Çubuğu'ndan Azure API Center simgesini seçin.
  2. API Center bölmesinde, kural kümesini özelleştirdiğiniz API center kaynağını genişletin.
  3. Profiller'i genişletin.
  4. Kural kümesini özelleştirdiğiniz profile sağ tıklayın ve Kuralları API Center'a Dağıt'ı seçin.

Kurallar API merkezinize başarıyla dağıtıldıktan sonra size bir ileti bildirir. Linting altyapısı, profildeki API tanımlarını analiz etmek için güncelleştirilmiş kural kümesini kullanır.

Güncelleştirilmiş kural kümesiyle lint sonuçlarını görmek için portalda API çözümleme raporlarını görüntüleyin.

İlgili içerik

  • Last updated on