API-elemzés engedélyezése az API-központban – ön által felügyelt

Ez a cikk bemutatja, hogyan engedélyezheti az API-elemzést a Azure API Centerben a linting motor és az eseményindítók beállításához. Ezek a képességek elemzik az API-definíciókat a szervezeti stílusszabályok betartásához, és egyéni és összefoglaló jelentéseket is létrehoznak. Az API-elemzés segít azonosítani és kijavítani az API-definíciókban előforduló gyakori hibákat és inkonzisztenciákat.

Az alábbi eljárások támogatják a linting motor és az esemény-előfizetés automatikus üzembe helyezését az API-központban. A Azure fejlesztői parancssori felület (azd) használatával egylépéses üzembe helyezést biztosít a linting infrastruktúra számára az egyszerűsített üzembe helyezési folyamat érdekében. Az Azure CLI parancsok példái a PowerShellben vagy bash héjban futtathatók. Szükség esetén külön parancs példákat is biztosítunk.

Ha manual üzembe helyezéssel szeretné beállítani a motort és az erőforrásokat, tekintse meg az Azure API Center Analyzer GitHub adattárat, amely útmutatást nyújt a függvényalkalmazás üzembe helyezéséhez és az esemény-előfizetés konfigurálásához.

Megjegyzés

Azure API Center emellett automatikusan konfigurálja az API-elemzés alapértelmezett linting motorját és függőségeit. Ha engedélyezi az önkiszolgáló elemzést a jelen cikkben leírtak szerint, felülbírálja ezeket a beépített funkciókat.

Forgatókönyv áttekintése

Ebben a forgatókönyvben az API-központ API-definícióit a Spectral open source linting motor használatával elemezheti. Egy Azure Functions beépített függvényalkalmazás futtatja a linting motort az API-központ eseményeire válaszul. A spektrális ellenőrzés ellenőrzi, hogy a JSON- vagy YAML-specifikációs dokumentumban meghatározott API-k megfelelnek-e a testre szabható API-stílusok útmutatójának. Létrejön egy elemzési jelentés, amelyet az API-központban tekinthet meg.

Az alábbi ábra a linting és az elemzés API-központban való engedélyezésének lépéseit mutatja be.

Diagram az API-linting működéséről az Azure API Centerben.

  1. Helyezzen üzembe egy függvényalkalmazást, amely a Spectral linting motoron futtat egy API-definíciót.

  2. Konfiguráljon egy esemény-előfizetést egy Azure API-központban, amely elindítja a függvényalkalmazást.

  3. Az eseményt egy API-definíció hozzáadása vagy cseréje váltja ki az API-központban.

  4. Az esemény fogadásakor a függvényalkalmazás meghívja a Spectral linting motort.

  5. A linting motor ellenőrzi, hogy a definícióban meghatározott API-k megfelelnek-e a szervezet API-stíluskalauzának, és létrehoz egy jelentést.

  6. Az elemzési jelentés megtekintése az API-központban.

Korlátozások

  • A linting jelenleg csak JSON- vagy YAML-specifikációs fájlokat támogat, például OpenAPI- vagy AsyncAPI-specifikációs dokumentumokat.

  • Alapértelmezés szerint a linting motor a beépített spectral:oas szabálykészletet használja. A szabálykészlet kibővítéséhez vagy egyéni API-stílus útmutatók létrehozásához tekintse meg a Spectral-adattárat a GitHubon.

  • A lintinget meghívó függvényalkalmazás külön díjat számít fel, ön pedig felügyeli és karbantartja.

Előfeltételek

Az azd deployment használata függvényalkalmazáshoz és esemény-előfizetéshez

Az alábbi eljárások automatizált lépéseket biztosítanak a Azure fejlesztői parancssori felülethez (azd) a függvényalkalmazás és az esemény-előfizetés konfigurálásához, amely lehetővé teszi a lintinget és az elemzést az API-központban.

Megjegyzés

Ha inkább manual üzembe helyezéssel szeretné beállítani a motort és az erőforrásokat, tekintse meg az Azure API Center Analyzer GitHub adattárat, amely útmutatást nyújt a függvényalkalmazás üzembe helyezéséhez és az esemény-előfizetés konfigurálásához.

A minta futtatása az azd használatával

  1. Klónozza a minta Azure API Center Analyzer GitHub adattárat a helyi gépre.

  2. Indítsa el a Visual Studio Code-ot, és válassza a File>Mappa megnyitása (Ctrl+K, Ctrl+O). Keresse meg a APICenter-Analyzer klónozott adattár mappáját, és válassza a Mappa kijelölése lehetőséget.

  3. A(z) Visual Studio Code Activity Bar-ban válassza a Felfedező (Ctrl+Shift+E) elemet, hogy megtekinthesse az adattár mappastruktúráját.

    • Bontsa ki a resources/rulesets mappát, és figyelje meg a oas.yaml fájlt. Ez a fájl az aktuális API-stíluskalauzt tükrözi. Ezt a fájlt a szervezeti igényeknek megfelelően módosíthatja.

    • Bontsa ki a src/functions mappát, és figyelje meg a ApiAnalyzerFunction.ts fájlt. Ez a fájl a függvényalkalmazás függvénykódját tartalmazza. Ezt a fájlt úgy módosíthatja, hogy a függvény viselkedése megfeleljen az alkalmazás követelményeinek.

  4. Nyisson meg egy terminált Visual Studio Code-ban, és hitelesítse a Azure fejlesztői parancssori felülettel (azd):

    azd auth login

    Jótanács

    A következő parancsok futtatásával elkerülheti a fejlesztési környezetek hitelesítési problémáit:

    1. Új fejlesztési környezet létrehozása: azd env new
    2. A bérlőazonosító lekérése: az account show --query tenantId -o tsv (másolja a kimeneti azonosítót későbbre)
    3. Kijelentkezés: azd auth logout parancs
    4. Jelentkezzen be azd az értékével a tenantId 2. lépésből: azd auth login --tenant-id <tenant_ID>

    Sikeres hitelesítés után a parancs kimenete megmutatja Önnek: Bejelentkezve az Azure szolgáltatásba mint <your_user_alias>.

  5. Ezután jelentkezzen be az Azure portalra az Azure CLI használatával:

    az login

    A rendszer kéri, hogy adja meg a hitelesítő adatait a Azure való bejelentkezéshez.

    A böngészőablak megerősíti a sikeres bejelentkezést. Zárja be az ablakot, és térjen vissza ehhez az eljáráshoz.

  6. Futtassa a következő parancsot a linting infrastruktúra üzembe helyezéséhez a Azure-előfizetésben.

    Ehhez a parancshoz a következő információkra van szüksége. A legtöbb ilyen érték a «Overview» oldalon érhető el az API központ erőforrásához az Azure portálon.

    • Előfizetés neve és azonosítója
    • API-központ neve
    • Az API-központ erőforráscsoportjának neve
    • A függvényalkalmazás üzembehelyezési régiója (eltérhet az API-központ régiójától)
    azd up

  7. Az utasításokat követve adja meg a szükséges üzembe helyezési információkat és beállításokat. További információ: A minta futtatásához használja a Azure fejlesztői parancssori felületet (azd).

    Az üzembe helyezés előrehaladtával a kimenet a befejezett kiépítési tevékenységeket jeleníti meg:

    Megjegyzés

    A függvényalkalmazás létrehozása és az Azure-ra történő telepítése több percig is eltarthat.

    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)

    A kimenet tartalmaz egy hivatkozást, amely az Azure portálon követi a telepítési folyamatot.

  8. A kiépítés befejezése után a folyamat üzembe helyezi az új függvényalkalmazást a Azure portal:

    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. Amikor az üzembe helyezés befejeződik, győződjön meg arról, hogy az új függvényalkalmazás jelen van és a függvény közzétéve lett.

    Ha a apicenter-analyer függvény nincs felsorolva, vagy a Status nem Enabled, tegye közzé a függvényt a Azure Functions Core Tools használatával.

  10. Konfiguráljon esemény-előfizetést a PowerShell vagy a Bash környezet használatával a Visual Studio Code-ban.

A Azure portal-ben közzétett függvény megerősítése

Ha az üzembe helyezés befejeződött, ellenőrizze, hogy az új függvényalkalmazás megtalálható-e a Azure portal, és a függvény közzé van-e téve.

  1. Jelentkezzen be a Azure portal, keresse meg a Funkciós alkalmazás szakaszt, és válassza ki az új függvényalkalmazást a listában.

  2. Az új függvényalkalmazás Áttekintés lapján ellenőrizze, hogy a függvényalkalmazás állapotafut-e.

  3. A Függvények szakaszban ellenőrizze, hogy a apicenter-analyer függvény szerepel-e a listában, és hogy az állapotengedélyezve van-e.

    A függvényalkalmazás képernyőképe az Azure portálon, amelyen az Futó állapot és az Engedélyezett függvény látható.

Apicenter-analyzer függvény közzététele Azure Functions Core Tools használatával

Ha az üzembe helyezési folyamat nem teszi közzé a apicenter-analyer függvényt a Azure portal függvényalkalmazásban, a következő parancsokat futtathatja egy Visual Studio Code-terminálban, és befejezheti a folyamatot.

  1. Futtassa a következő parancsot annak ellenőrzéséhez, hogy a függvény nincs közzétéve a függvényalkalmazásban:

    Megjegyzés

    Ez a parancs a függvényalkalmazás üzembe helyezési folyamata által létrehozott új erőforráscsoportot használja, nem pedig az API-központ erőforráscsoportját. Cserélje le a <function-app-name> és <new_resource_group_for_function_app> helyére a függvényalkalmazás nevét és a függvényalkalmazás erőforráscsoportjának nevét.

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

    A parancs kimenetének üresnek kell lennie.

  2. Az Explorerben bontsa ki a src/functions mappát, és nyissa meg a ApiAnalyzerFunction.ts fájlt. Ez a művelet megerősíti, hogy a környezet úgy van beállítva, hogy a megfelelő helyen keressen tartalmat.

  3. Győződjön meg arról, hogy a környezet tartalmazza az npm package manager és a csomópont futtatókörnyezetét, és szükség szerint telepítse az eszközöket:

    node --version
npm --version

  4. Szükség esetén telepítse a Azure Functions kódeszközöket a környezetbe:

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

  5. Futtassa a következő parancsot a függvénykód közzétételéhez az Azure portálon a függvényalkalmazásba. Cserélje le <function-app-name> a függvényalkalmazás nevére.

    func azure functionapp publish <function_app_name> --typescript

    A parancs a következő kimenetet jeleníti meg:

    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. Az Azure portálon győződjön meg arról, hogy a apicenter-analyzer függvény mostantól a függvényalkalmazásában közzé van téve és engedélyezve van.

Esemény-előfizetés konfigurálása

Miután a függvényt sikeresen közzétette a függvényalkalmazásban a Azure portal, létrehozhat egy esemény-előfizetést az API-központban, amely aktiválja a függvényalkalmazást egy API-definíciós fájl feltöltése vagy frissítésekor.

  1. Kérje le az API-központ erőforrás-azonosítóját. Helyettesítse <apic-name> az API-központ nevével, és <resource-group-name> az API-központ erőforráscsoportjának nevével.

    #! /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. Kérje le a függvény erőforrás-azonosítóját a függvényalkalmazásban. Ebben a példában a függvény neve apicenter-analyzer. <function-app-name> Helyettesítse be <resource-group-name> a függvényalkalmazás nevét és az erőforráscsoport nevét a függvényalkalmazáshoz.

    #! /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. Esemény-előfizetés létrehozása a az eventgrid event-subscription create paranccsal. A létrehozott előfizetés tartalmazza az API-definíciók hozzáadásához vagy frissítéséhez szükséges eseményeket.

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

    A parancs kimenete az esemény-előfizetés részleteit jeleníti meg. A részleteket az az eventgrid event-subscription show paranccsal is lekérheti:

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

    Megjegyzés

    Az esemény-előfizetés rövid idő alatt is propagálhat a függvényalkalmazásba.

  4. Keresse meg az API-központot a Azure portal, és erősítse meg az új esemény-előfizetést a Events>Event-előfizetések alatt.

Esemény aktiválása az API-központban

Az esemény-előfizetés teszteléséhez próbáljon meg feltölteni vagy frissíteni egy API-verzióhoz társított API-definíciós fájlt az API-központban. Például töltsön fel egy OpenAPI- vagy AsyncAPI-dokumentumot. Az esemény-előfizetés aktiválása után a függvényalkalmazás meghívja az API linting motort az API-definíció elemzéséhez.

Az esemény-előfizetés aktiválásának ellenőrzéséhez:

  1. Keresse meg az API-központot, és válassza az Események lehetőséget.

  2. Válassza az Esemény-előfizetések lapot, és válassza ki a függvényalkalmazás esemény-előfizetését.

  3. Tekintse át a metrikákat, és győződjön meg arról, hogy az esemény-előfizetés aktiválódott, és a linting sikeres meghívása megtörtént.

    Képernyőkép az esemény-előfizetés metrikáiról a portálon.

    Megjegyzés

    A metrikák megjelenése eltarthat néhány percig.

Miután a rendszer elemezte az API-definíciót, a linting motor létrehoz egy jelentést a konfigurált API-stílus útmutatója alapján.

API-elemzési jelentések megtekintése

Az API-definícióhoz tartozó elemzési jelentést a Azure portal tekintheti meg. Az API-definíció elemzése után a jelentés a konfigurált API-stílus útmutatója alapján felsorolja a hibákat, figyelmeztetéseket és információkat.

A portálon megtekintheti az API-központ összes API-definíciójának elemzési jelentéseit is.

Elemzési jelentés API-definícióhoz

Egy API-definíció elemzési jelentésének megtekintése az API-központban:

  1. A portálon keresse meg az API-központot, bontsa ki az Inventory elemet, és válassza az Eszközök lehetőséget.

  2. Az Eszközlistában válassza ki azt az API-t, amelyhez hozzáadott vagy frissített egy API-definíciót.

  3. Válassza a Verziók lehetőséget, majd bontsa ki az API megvizsgálandó sorát.

  4. A Definíció csoportban válassza ki a feltöltött vagy frissített definíció nevét.

  5. Válassza az Elemzés lapot.

    API-definíció elemzési lapjának képernyőképe az Azure portálon.

Megnyílik az API Analysis Report, amely a konfigurált API-stílus útmutatója alapján jeleníti meg az API definícióját és hibáit, figyelmeztetéseit és információit. Az alábbi képernyőkép egy API-elemzési jelentés példáját mutatja be.

Képernyőkép egy API-elemzési jelentésről a portálon.

API-elemzés összegzése

Az API-központban megtekintheti az összes API-definíció elemzési jelentéseinek összegzését.

  • A portálon keresse meg az API-központot, bontsa ki az Irányítás elemet, és válassza az API Analysis lehetőséget.

    Képernyőkép az API-elemzés összegzéséről a portálon.

  • Az egyes sorok jobb oldalán látható ikon megnyitja a definíció API Analysis Reportját .

Kapcsolódó tartalom

  • Last updated on