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

Bu makalede, Azure API Center'da linting altyapısı ve tetikleyicileri ayarlamak için API analizinin nasıl etkinleştirileceği açıklanı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.

Aşağıdaki yordamlar, API merkezinizde linting altyapısının ve olay aboneliğinin otomatik dağıtımını destekler. Kolaylaştırılmış bir dağıtım işlemi için lint altyapısının tek adımlı dağıtımı için Azure Geliştirici CLI'sını (azd) kullanın. Azure CLI komut örnekleri PowerShell'de veya bash kabuğunda çalıştırılabilir. Gerektiğinde ayrı komut örnekleri sağlanır.

Altyapıyı ve kaynakları manual deployment aracılığıyla ayarlamayı tercih ediyorsanız, işlev uygulamasını dağıtma ve olay aboneliğini yapılandırma yönergeleri için Azure API Center Analyzer GitHub deposuna bakın.

Not

Azure API Center ayrıca api analizi için varsayılan linting altyapısını ve bağımlılıklarını otomatik olarak yapılandırıyor. Bu makalede açıklandığı gibi kendi kendine yönetilen analizi etkinleştirirseniz, bu yerleşik özellikleri geçersiz kılarsınız.

Senaryoya genel bakış

Bu senaryoda, Spectral open source linting altyapısını kullanarak API merkezinizdeki API tanımlarını analiz edebilirsiniz. Azure Functions ile oluşturulan bir işlev uygulaması, API merkezinizdeki olaylara yanıt olarak lint motorunu ç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 motorunu çalıştıran bir fonksiyon 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 motorunu ç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.

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 stil kılavuzları oluşturmak için GitHub'daki Spectral deposuna bakınız.

• Lint işlemini çağıran işlev uygulaması ayrı olarak ücretlendirilir ve bunu yönetip korursunuz.

Önkoşullar

• Azure aboneliğinizde bir API merkezi. Abonelik oluşturmak için 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 Developer CLI (azd). Makinenize yüklemek istediğiniz ortamı seçin ve aşağıdaki işlemde kullanmak için azd yükleyin.

• Azure Functions Core Tools. Aşağıdaki yordam için kullanmayı planladığınız ortama makinenizdeki temel araçları yükleyin. Araçların ayarlarınız PATH tarafından erişilebilir olduğundan emin olun.

• Azure CLI için:

  • bash ortamını Azure Cloud Shell kullanın. Daha fazla bilgi için bkz. Azure Cloud Shell ile Başlarken.

    

  • CLI referans komutlarını yerel olarak çalıştırmayı tercih ediyorsanız, Azure CLI'yi yükleyin. Windows veya macOS üzerinde çalıştırıyorsanız, Azure CLI bir Docker kapsayıcısında çalıştırmayı göz önünde bulundurun. Daha fazla bilgi için bkz. Docker kapsayıcısında Azure CLI çalıştırma.

    • Yerel yükleme kullanıyorsanız az login komutunu kullanarak Azure CLI 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 kullanarak Azure'a Kimlik Doğrulama.

    • İ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 ve yönetme.

    • 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 çalıştırın.

  Not

  az apic komutları apic-extension Azure CLI uzantısını gerektirir. uzantı, ilk az apic komutunuzu çalıştırdığınızda dinamik olarak yüklenebilir veya uzantıyı el ile yükleyebilirsiniz. Daha fazla bilgi için bkz. Azure CLI Uzantılarını Yönetme: Yükleme, Güncelleştirme ve Kaldırma.

  apic-extension en son değişiklikler ve güncelleştirmeler için bkz. release notes. Bazı özellikler için bir önizleme veya uzantının belirli bir sürümü gerekebilir.

İşlev uygulaması ve olay aboneliği için azd dağıtımı kullanma

Aşağıdaki yordamlar, API merkezinizde lint ve analizi etkinleştiren işlev uygulamasını ve olay aboneliğini yapılandırmak için Azure Geliştirici CLI'sı (azd) için otomatik adımlar sağlar.

Not

altyapıyı ve kaynakları manual deployment ile ayarlamayı tercih ediyorsanız, işlev uygulamasını dağıtma ve olay aboneliğini yapılandırma yönergeleri için Azure API Center Analyzer GitHub deposuna bakın.

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

1. Örnek Azure API Center Analyzer GitHub deposunu yerel makinenize kopyalayın.

2. Visual Studio Code'u başlatın ve Dosya> klasörünü Aç (Ctrl+K, Ctrl+O). APICenter-Analyzer Kopyalanan deponun klasörüne gidin ve Klasör seç'i seçin.

3. Visual Studio Code Etkinlik Çubuğu'ndan Gezgin (Ctrl+Shift+E) seçeneğini tıklayın, böylece depo klasör yapısını görüntüleyebilirsiniz.

   • resources/rulesets klasörünü genişletin ve oas.yaml dosyasına dikkat edin. Bu dosya geçerli API stili kılavuzunuzu yansıtır. Bu dosyayı kuruluş gereksinimlerinizi karşılayacak şekilde değiştirebilirsiniz.

   • src/functions klasörünü genişletin ve ApiAnalyzerFunction.ts dosyasına dikkat edin. Bu dosya, işlev uygulaması için işlev kodunu sağlar. İşlev davranışını uygulama gereksinimlerinizi karşılayacak şekilde ayarlamak için bu dosyayı değiştirebilirsiniz.

4. Visual Studio Code'da bir terminal açın ve Azure Developer CLI (azd) ile kimlik doğrulaması:

   azd auth login
   

   Tavsiye

   Aşağıdaki komutları çalıştırarak geliştirme ortamlarında kimlik doğrulaması sorunlarını önleyebilirsiniz:

   1. Yeni bir geliştirme ortamı oluşturun: azd env new
   2. Kiracı kimliğinizi alın: az account show --query tenantId -o tsv (çıkış kimliğini daha sonra için kopyalayın)
   3. Oturumu kapat: azd auth logout komutu
   4. azd 2. adımdan değeriniz tenantId ile oturum açın:azd auth login --tenant-id <tenant_ID>

   Başarıyla kimlik doğrulaması yaptığınızda, komut çıktısı size <your_user_alias> olarak Azure'ye giriş gösterir.

5. Ardından, Azure CLI kullanarak Azure portal oturum açın:

   az login
   

   Azure oturum açmak için kimlik bilgilerinizi girmeniz istenir.

   Bir tarayıcı penceresi başarılı oturum açma işlemlerinizi onaylar. Pencereyi kapatın ve bu işleme dönün.

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

   Bu komut için aşağıdaki bilgilere ihtiyacınız vardır. Bu değerlerin çoğu, Azure portal API center kaynağınızın Overview sayfasında bulunur.

   • Abonelik adı ve kimliği
   • API merkezi adı
   • API merkezi için kaynak grubu adı
   • İşlev uygulamasının dağıtım bölgesi (API merkezi bölgenizden farklı olabilir)

   azd up
   

7. Gerekli dağıtım bilgilerini ve ayarlarını sağlamak için istemleri izleyin. Daha fazla bilgi için bkz. Azure Developer CLI (azd) kullanarak örneği çalıştırma.

   Dağıtım ilerledikçe çıktı tamamlanmış sağlama görevlerini gösterir:

   Not

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

   Packaging services (azd package)
   
   (✓) Done: Packaging service function
   - Build Output: C:\GitHub\APICenter-Analyzer
   - Package Output: C:\Users\<user>\AppData\Local\Temp\api-center-analyzer-function-azddeploy-0123456789.zip
   
   Loading azd .env file from current environment
   
   Provisioning Azure resources (azd provision)
   Provisioning Azure resources can take some time.
   
   Subscription: <your_selected_subscription>
   Location: <your_selected_region_for_this_process>
   
   You can view detailed progress in the Azure Portal:
   
   https://portal.azure.com/#view/HubsExtension/DeploymentDetailsBlade/~/overview/id/%2Fsubscriptions%2F00001111-a2a2-b3b3-c4c4-dddddd555555%2Fproviders%2FMicrosoft.Resources%2Fdeployments%2F<your_azd_environment_name-0123456789>
   
   (✓) Done: Resource group: <new_resource_group_for_function_app> (5.494s)
   (✓) Done: App Service plan: <new_app_service_plan> (5.414s)
   (✓) Done: Storage account: <new_storage_account> (25.918s)
   (✓) Done: Log Analytics workspace: <new_workspace> (25.25s)
   (✓) Done: Application Insights: <new_application_insights> (5.628s)
   (✓) Done: Portal dashboard: <new_dashboard> (1.63s)
   (✓) Done: Function App: <new_function_app> (39.402s)
   

   Çıktı, Azure portal dağıtım ilerleme durumunu izlemeye yönelik bir bağlantı içerir.

8. Sağlama tamamlandıktan sonra işlem yeni işlev uygulamasını Azure portal dağıtır:

   Deploying services (azd deploy)
   
   (✓) Done: Deploying service function
   - Endpoint: https://<new_function_app>.azurewebsites.net/
   
   Configuring EventGrid subscription for API Center
   
   Examples from AI knowledge base
   

9. Dağıtım tamamlandığında, yeni işlev uygulamasının mevcut olduğunu ve işlevin yayımlandığını doğrulayın.

   apicenter-analyer işlevi listelenmiyorsa veya StatusEnabled değilse, Azure Functions Temel Araçları'nı kullanarak işlevi yayınlayın.

10. Visual Studio Code'da PowerShell veya bash kabuğu kullanarak olay aboneliğini yapılandırın.

Azure portal'de yayımlanan işlevi onayla

Dağıtım tamamlandığında, yeni işlev uygulamasının Azure portal mevcut olduğunu ve işlevin yayımlandığını onaylayın.

1. Azure portal'a giriş yapın, Function Uygulaması sekmesine gidin ve listeden yeni işlev uygulamanızı seçin.

2. Yeni işlev uygulamasının Genel Bakış sayfasında, işlev uygulamasının DurumununÇalışıyor olduğunu onaylayın.

3. İşlevler bölümünde işlevin apicenter-analyer listelendiğini ve Durum'unEtkin olduğunu onaylayın.

   

Azure Functions Core Tools ile apicenter-analyzer işlevini yayımlama

Dağıtım işlemi Azure portal işlev uygulamasına apicenter-analyer işlevini yayımlamazsa, Visual Studio Code terminalinde aşağıdaki komutları çalıştırabilir ve işlemi tamamlayabilirsiniz.

1. İşlevin işlev uygulamasında yayımlanmadığından emin olmak için aşağıdaki komutu çalıştırın:

   Not

   Bu komut, API merkezinizin kaynak grubunu değil işlev uygulaması için dağıtım işlemi tarafından oluşturulan yeni kaynak grubunu kullanır. <function-app-name> ve <new_resource_group_for_function_app>'i, işlev uygulamanızın adı ve işlev uygulamasının kaynak grubunun adı ile değiştirin.

   az functionapp function list --name <function_app_name> --resource-group <new_resource_group_for_function_app> --query "[].name" -o tsv
   

   Komut çıkışı boş olmalıdır.

2. Gezgin'de klasörü genişletin src/functions ve dosyayı açınApiAnalyzerFunction.ts. Bu eylem, ortamın içeriği doğru konumda aramak üzere ayarlandığını onaylar.

3. Ortamınızın npm package manager ve düğüm çalışma zamanı ortamını içerdiğini onaylayın ve gerektiğinde tüm araçları yükleyin:

   node --version
   npm --version
   

4. Gerektiğinde Azure Functions Kod Araçları'nı ortama yükleyin:

   npm install -g azure-functions-core-tools@4 --unsafe-perm true
   

5. İşlev kodunu Azure portal işlev uygulamasında yayımlamak için aşağıdaki komutu çalıştırın. <function-app-name> değerini işlev uygulamanızın adıyla değiştirin.

   func azure functionapp publish <function_app_name> --typescript
   

   Komut aşağıdaki çıkışı gösterir:

   Getting site publishing info...
   [2026-02-26T19:58:38.779Z] Starting the function app deployment...
   Uploading package...
   Uploading 33.8 MB [###############################################################################]
   Upload completed successfully.
   Deployment completed successfully.
   apicenter-analyzer - [eventGridTrigger]
   

6. Azure portalda, apicenter-analyzer işlevinin artık yayınlandığını ve işlev uygulamanız için etkinleştirildiğini onaylayın.

Olay aboneliğini yapılandırma

İşlev, Azure portal işlev uygulamasına başarıyla yayımlandıktan sonra, API tanım dosyası karşıya yüklendiğinde veya güncelleştirildiğinde işlev uygulamasını tetikleyecek şekilde API merkezinizde bir olay aboneliği oluşturabilirsiniz.

1. API merkezinizin kaynak kimliğini alın. API merkeziniz için <apic-name> ve <resource-group-name> yerine, API merkezinizin adını ve kaynak grubunun adını yazın.

   #! /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)
   

2. İşlev uygulamasında işlevin kaynak kimliğini alın. Bu örnekte işlev adı apicenter-analyzer'dır. <function-app-name> ve <resource-group-name> yerine işlev uygulamanızın adını ve işlev uygulamanızın kaynak grubunun adını yazın.

   #! /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. az eventgrid event-subscription create komutunu kullanarak bir olay aboneliği oluşturun. Oluşturulan abonelik, API tanımlarını ekleme veya güncelleştirme olaylarını içerir.

   #! /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
   

   Komut çıktısı olay aboneliğinin ayrıntılarını gösterir. Ayrıca az eventgrid event-subscription show komutunu kullanarak da ayrıntıları alabilirsiniz:

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

   Not

   Olay aboneliğinin işlev uygulamasına yayılması kısa bir süre alabilir.

4. Azure portal API merkezinize gidin ve Events>Event Subscriptions altında yeni olay aboneliğini onaylayın.

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ı yükleyerek bir API oluşturmak için Belirtim dosyasından API kaydetme kısmına bakın.

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

1. API merkezinize göz atın ve Olaylar'ı seçin.

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

3. Ölçümleri gözden geçirerek olay aboneliğinin tetiklendiğini ve lint kontrolünün başarıyla gerçekleştirildiğini doğrulayın.

   

   Not

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

Sistem 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 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 merkezinize gidin, Envanter'i genişletin ve Varlıklar'ı seçin.

2. Varlık listesinde, api tanımını eklediğiniz veya güncelleştirdiğiniz API'yi seçin.

3. Sürümler'i seçin ve ardından API'nin incelendiği satırı genişletin.

4. Tanım'ın altında karşıya yüklediğiniz veya güncelleştirdiğiniz tanım adını seçin.

5. Çö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ı için analiz raporlarının özetini görüntüleyebilirsiniz.

• Portalda API merkezinize gidin, İdare'yi genişletin ve API Analizi'ni seçin.

  

• Her satırdaki sağ taraftaki simge, tanım için API Çözümleme Raporu'nı açar.

İlgili içerik

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