Povolení analýzy rozhraní API v centru rozhraní API – samoobslužná správa

Tento článek vysvětluje, jak povolit analýzu rozhraní API v Azure API Center k nastavení lintovacího modulu a spouštěčů. Tyto funkce analyzují definice vašeho rozhraní API pro dodržování pravidel stylu organizace a generují jak jednotlivé, tak souhrnné sestavy. Analýza rozhraní API pomáhá identifikovat a opravit běžné chyby a nekonzistence v definicích rozhraní API.

Následující postupy podporují automatizované nasazení modulu linting a odběru událostí ve vašem centru rozhraní API. Pomocí nástroje příkazového řádku Azure pro vývojáře (azd) můžete provést jednokrokové nasazení infrastruktury pro lintování pro zjednodušení procesu nasazení. Příklady příkazů Azure CLI můžou běžet v PowerShellu nebo prostředí Bash. Podle potřeby jsou k dispozici samostatné příklady příkazů.

Pokud dáváte přednost nastavení motoru a prostředků prostřednictvím manual deployment, přečtěte si GitHub úložiště Azure API Center Analyzer s pokyny k nasazení funkční aplikace a konfiguraci odběru událostí.

Poznámka:

Azure API Center také automaticky konfiguruje výchozí lintovací modul a závislosti pro analýzu rozhraní API. Pokud povolíte samostatně řízenou analýzu, jak je popsáno v tomto článku, přepíšete tyto předdefinované funkce.

Přehled scénáře

V tomto scénáři analyzujete definice API ve vašem centru API pomocí open-source lintovacího nástroje Spectral. Aplikace funkcí vytvořená pomocí Azure Functions spouští lintovací modul v reakci na události ve vašem centru rozhraní API. Spectral kontroluje, že rozhraní API definovaná v dokumentu specifikace JSON nebo YAML odpovídají pravidlům v přizpůsobitelné příručce stylu rozhraní API. Vygeneruje se sestava analýzy, kterou můžete zobrazit v centru rozhraní API.

Následující diagram znázorňuje kroky pro povolení lintování a analýzy ve vašem centru rozhraní API.

Diagram znázorňující, jak funguje lintování rozhraní API v Azure API Center.

  1. Nasazujte aplikační funkci, která spouští lintovací engine Spectral v rámci definice API.

  2. Nakonfigurujte odběr událostí v centru rozhraní API Azure, který aktivuje aplikaci funkcí.

  3. Událost se aktivuje přidáním nebo nahrazením definice rozhraní API v centru rozhraní API.

  4. Při přijetí události funkční aplikace vyvolá modul lintování Spectral.

  5. Lintovací modul ověřuje, že rozhraní API definovaná v dokumentaci odpovídají stylistické příručce pro API organizace a generuje report.

  6. Zobrazte zprávu o analýze v centru rozhraní API.

Omezení

  • Linting aktuálně podporuje pouze soubory specifikace JSON nebo YAML, jako jsou dokumenty specifikace OpenAPI nebo AsyncAPI.

  • Modul linting ve výchozím nastavení používá integrovanou spectral:oas sadu pravidel. Pokud chcete rozšířit sadu pravidel nebo vytvořit vlastní styl rozhraní API guides, podívejte se na úložiště Spectral na GitHub.

  • Funkční aplikace, která vyvolává lintování, je účtována samostatně a vy ji spravujete a udržujete.

Požadavky

Použití azd deploymentu pro funkční aplikaci a předplatné událostí

Následující postupy poskytují automatizované kroky pro Azure Developer CLI (azd) ke konfiguraci aplikace funkcí a odběru událostí, které umožňují provádění lintingu a analýzu ve vašem API centru.

Poznámka:

Pokud upřednostňujete nastavení modulu a prostředků pomocí manuálního nasazení, přečtěte si GitHub úložiště Azure API Center Analyzer pro pokyny k nasazení funkční aplikace a konfiguraci odběru událostí.

Spusťte ukázku pomocí azd

  1. Naklonujte ukázkové úložiště Azure API Center Analyzer GitHub do místního počítače.

  2. Spusťte Visual Studio Code a vyberte File>Open Folder (Ctrl+K, Ctrl+O). Přejděte do APICenter-Analyzer složky pro klonované úložiště a zvolte Vybrat složku.

  3. V panelu s aktivitami v aplikaci Visual Studio Code vyberte možnost Průzkumník (Ctrl + Shift + E), aby se zobrazila struktura složek úložiště.

    • resources/rulesets Rozbalte složku a všimněte si oas.yaml souboru. Tento soubor odráží aktuálního průvodce stylem rozhraní API. Tento soubor můžete upravit tak, aby vyhovoval potřebám vaší organizace.

    • src/functions Rozbalte složku a všimněte si ApiAnalyzerFunction.ts souboru. Tento soubor poskytuje kód funkce pro aplikaci funkcí. Tento soubor můžete upravit tak, aby upravte chování funkce tak, aby splňovalo požadavky vaší aplikace.

  4. Otevřete terminál v Visual Studio Code a ověřte se pomocí rozhraní příkazového řádku pro vývojáře Azure (azd):

    azd auth login

    Návod

    Spuštěním následujících příkazů se můžete vyhnout problémům s ověřováním ve vývojových prostředích:

    1. Vytvořte nové vývojové prostředí: azd env new
    2. Získání ID tenanta: az account show --query tenantId -o tsv (zkopírujte výstupní ID pro pozdější použití)
    3. Odhlásit se: azd auth logout příkaz
    4. Přihlaste se azd pomocí své tenantId hodnoty z kroku 2: azd auth login --tenant-id <tenant_ID>

    Po úspěšném ověření se ve výstupu příkazu zobrazí Přihlášen/a k Azure jako <your_user_alias>.

  5. Dále se přihlaste k Azure portal pomocí Azure CLI:

    az login

    Zobrazí se výzva k zadání přihlašovacích údajů pro přihlášení k Azure.

    Okno prohlížeče potvrdí úspěšné přihlášení. Zavřete okno a vraťte se k tomuto postupu.

  6. Spuštěním následujícího příkazu nasaďte infrastrukturu linting do vašeho Azure předplatného.

    Pro tento příkaz potřebujete následující informace. Většina těchto hodnot je k dispozici na stránce Overview prostředku rozhraní API v Azure Portal.

    • Název a ID předplatného
    • Název centra rozhraní API
    • Název skupiny prostředků pro centrum rozhraní API
    • Oblast nasazení aplikace funkcí (může se lišit od oblasti centra rozhraní API)
    azd up

  7. Podle pokynů zadejte požadované informace a nastavení nasazení. Další informace najdete v tématu Spuštění ukázky pomocí Azure Developer CLI (azd).

    V průběhu nasazení se ve výstupu zobrazí dokončené úlohy zřizování:

    Poznámka:

    Zřízení aplikace funkcí a jeho nasazení do Azure může trvat několik minut.

    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)

    Výstup obsahuje odkaz pro monitorování průběhu nasazení v Azure portal.

  8. Po dokončení zřizování proces nasadí novou funkční aplikaci do portálu Azure.

    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. Po dokončení nasazení ověřte, že je nová aplikace funkcí přítomna, a že byla funkce publikována.

    Pokud funkce apicenter-analyer není uvedená nebo Status není Enabledpublikujte funkci pomocí nástrojů Azure Functions Core Tools.

  10. Konfigurovat odběr událostí pomocí PowerShellu nebo prostředí Bash v Visual Studio Code.

Funkce potvrzena na portálu Azure

Po dokončení nasazení ověřte, že se nová funkční aplikace nachází v portálu Azure a funkce byla publikována.

  1. Přihlaste se k části Azure portal, přejděte do části Function App a vyberte novou aplikaci funkcí v seznamu.

  2. Na stránce Přehled nové funkční aplikace potvrďte, že stav funkční aplikace je Spuštěno.

  3. V části Funkce potvrďte, že apicenter-analyer je funkce uvedená a stav je povolený.

    Screenshot funkční aplikace v portálu Azure zobrazující stav Spuštěno a povolenou funkci.

Publikování funkce apicenter-analyzer pomocí nástrojů Azure Functions Core Tools

Pokud proces nasazení nepublikuje funkci apicenter-analyer do aplikace funkcí v Azure portal, můžete v terminálu Visual Studio Code spustit následující příkazy a proces dokončit.

  1. Spuštěním následujícího příkazu ověřte, že funkce není publikovaná v aplikaci funkcí:

    Poznámka:

    Tento příkaz používá novou skupinu prostředků vytvořenou procesem nasazení pro aplikaci funkcí, a ne skupinu prostředků centra rozhraní API. Nahraďte <function-app-name> názvem vaší funkční aplikace a <new_resource_group_for_function_app> názvem skupiny prostředků pro tuto funkční aplikaci.

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

    Výstup příkazu by měl být prázdný.

  2. V Průzkumníkusrc/functions rozbalte složku a otevřete ApiAnalyzerFunction.ts soubor. Tato akce potvrdí, že je prostředí nastavené tak, aby hledalo obsah ve správném umístění.

  3. Ověřte, že vaše prostředí zahrnuje npm package manager a prostředí node runtime, a podle potřeby nainstalujte všechny nástroje.

    node --version
npm --version

  4. Podle potřeby nainstalujte nástroje Azure Functions Code do prostředí:

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

  5. Spuštěním následujícího příkazu publikujte kód funkce do aplikace funkcí v Azure portal. Nahraďte <function-app-name> názvem vaší funkční aplikace.

    func azure functionapp publish <function_app_name> --typescript

    Příkaz zobrazí následující výstup:

    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. V Azure portal potvrďte, že je apicenter-analyzer funkce nyní publikovaná a povolená pro vaši funkční aplikaci.

Konfigurace odběru událostí

Po úspěšném publikování funkce do aplikace funkcí v Azure portal můžete ve svém centru rozhraní API vytvořit odběr událostí, který aktivuje aplikaci funkcí při nahrání nebo aktualizaci definičního souboru rozhraní API.

  1. Získejte ID zdroje vašeho centra API. Nahraďte <apic-name> názvem vašeho centra API a <resource-group-name> názvem skupiny prostředků pro vaše centrum API.

    #! /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. Získejte ID prostředku funkce ve funkční aplikaci. V tomto příkladu je název funkce apicenter-analyzer. Nahraďte <function-app-name> názvem vaší aplikace funkcí a <resource-group-name> názvem skupiny prostředků pro vaši aplikaci funkcí.

    #! /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. Vytvořte odběr událostí pomocí příkazu az eventgrid event-subscription create. Vytvořené předplatné obsahuje události pro přidání nebo aktualizaci definic rozhraní 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

    Výstup příkazu zobrazuje podrobnosti odběru událostí. Podrobnosti můžete získat také pomocí příkazu az eventgrid event-subscription show:

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

    Poznámka:

    Rozšíření odběru událostí do aplikace funkcí může chvíli trvat.

  4. Přejděte do centra rozhraní API v portálu Azure a potvrďte nové odběry událostí v části Events>Event Subscriptions.

Spouštěcí událost v centru API

Pokud chcete otestovat odběr událostí, zkuste nahrát nebo aktualizovat definiční soubor rozhraní API přidružený k verzi rozhraní API v centru rozhraní API. Nahrajte například dokument OpenAPI nebo AsyncAPI. Po aktivaci odběru událostí funkční aplikace vyvolá lintovací modul rozhraní API k analyzování definice rozhraní API.

Ověření, že se aktivuje odběr událostí:

  1. Přejděte do centra rozhraní API a vyberte Události.

  2. Vyberte kartu Odběry událostí a vyberte odběr událostí pro vaši aplikaci funkcí.

  3. Zkontrolujte metriky, zda je odběr událostí aktivován a lintování je úspěšně vyvoláno.

    Snímek obrazovky s metrikami odběru událostí na portálu

    Poznámka:

    Zobrazení metrik může trvat několik minut.

Jakmile systém analyzuje definici rozhraní API, modul linting vygeneruje sestavu na základě nakonfigurovaného průvodce stylem rozhraní API.

Zobrazení sestav analýzy rozhraní API

Sestavu analýzy definice rozhraní API můžete zobrazit v portálu Azure. Po analýze definice rozhraní API sestava uvádí chyby, upozornění a informace na základě nakonfigurovaného průvodce stylem rozhraní API.

Na portálu můžete také zobrazit souhrn analýz pro všechny definice rozhraní API ve vašem API centru.

Sestava analýzy pro definici rozhraní API

Zobrazení sestavy analýzy pro definici rozhraní API ve vašem centru API:

  1. Na portálu přejděte do centra rozhraní API, rozbalte Inventář a vyberte Prostředky.

  2. V seznamu Asset vyberte rozhraní API, pro které jste přidali nebo aktualizovali definici rozhraní API.

  3. Vyberte Verze a potom rozbalte řádek pro rozhraní API, který chcete prozkoumat.

  4. V části Definice vyberte název definice, kterou jste nahráli nebo aktualizovali.

  5. Vyberte kartu Analýza .

    Snímek obrazovky karty Analýza definice rozhraní API v Azure portálu.

Otevře se sestava Analýzy rozhraní API a zobrazí definici rozhraní API včetně chyb, upozornění a informací dle nakonfigurovaného průvodce pro styl rozhraní API. Následující snímek obrazovky ukazuje příklad sestavy analýzy rozhraní API.

Snímek obrazovky sestavy analýzy rozhraní API v portálu

Souhrn analýzy rozhraní API

Můžete zobrazit souhrn analytických sestav pro všechny definice rozhraní API ve vašem centru API.

  • Na portálu přejděte do centra rozhraní API, rozbalte zásady správného řízení a vyberte Analýza rozhraní API.

    Snímek obrazovky se souhrnem analýzy rozhraní API na portálu

  • Ikona napravo na každém řádku otevře sestavu analýzy rozhraní API pro definici.

Související obsah

  • Last updated on