Megosztás a következőn keresztül:

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

  • Cikk

Ez a cikk bemutatja, hogyan engedélyezheti az API-elemzést az Azure API Centerben egy linting motor és eseményindító manuális beállításával. 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.

Feljegyzés

Előzetes verzióban az Azure API Center automatikusan konfigurál egy alapértelmezett linting motort és függőségeket az API-elemzéshez. 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 a Spectral nyílt forráskód linting motor használatával elemzi az API-központ API-definícióit. Egy Azure Functions-alkalmazá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.

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

  1. Helyezzen üzembe egy Azure Functions-alkalmazást, amely a Spectral linting motort futtatja egy API-definíción.

  2. Konfiguráljon egy esemény-előfizetést egy Azure API-központban a függvényalkalmazás aktiválásához.

  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.

A linting motor és az esemény-előfizetés üzembe helyezésének lehetőségei

Ez a cikk két lehetőséget biztosít a linting motor és az esemény-előfizetés API-központban való üzembe helyezésére:

  • Automatizált üzembe helyezés – A linting infrastruktúra egylépéses üzembe helyezéséhez használja az Azure fejlesztői parancssori felületét (azdCLI). Ez a beállítás egyszerűsített üzembe helyezési folyamat esetén ajánlott.

  • Manuális üzembe helyezés – Kövesse a részletes útmutatást az Azure Functions-alkalmazás üzembe helyezéséhez és az esemény-előfizetés konfigurálásához. Ez a beállítás akkor ajánlott, ha manuálisan szeretné üzembe helyezni és kezelni az erőforrásokat.

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íluskalauzok létrehozásához tekintse meg a Spectral GitHub adattárat.
  • A lintinget meghívó Azure-függvényalkalmazás külön díjat számít fel, ön pedig felügyeli és karbantartja azt.

Előfeltételek

  • Egy API-központ az Azure-előfizetésben. Ha még nem hozott létre egyet, olvassa el az API-központ létrehozása című rövid útmutatót.

  • Az előfizetésben regisztrált Event Grid-erőforrás-szolgáltató. Ha regisztrálnia kell az Event Grid-erőforrás-szolgáltatót, olvassa el az Előfizetés az Azure Event Grid-partner által közzétett eseményekre című témakört.

  • Azure CLI esetén:

    Feljegyzés

    az apic parancsokhoz az apic-extension Azure CLI-bővítmény szükséges. Ha még nem használt az apic parancsokat, a bővítmény dinamikusan telepíthető az első az apic parancs futtatásakor, vagy manuálisan is telepítheti a bővítményt. További információ az Azure CLI-bővítményekről.

    A legújabb módosításokról és frissítésekről a kibocsátási megjegyzésekben olvashat.apic-extension Bizonyos funkciókhoz szükség lehet a bővítmény előzetes verziójára vagy adott verziójára.

    Feljegyzés

    A cikkben szereplő Azure CLI-parancsok PowerShellben vagy bash-rendszerhéjban futtathatók. A különböző változószintaxis miatt szükség esetén a két rendszerhéjhoz külön parancs példákat biztosítunk.

azd Az Azure Functions-alkalmazás- és esemény-előfizetés üzembe helyezése

Ez a szakasz az Azure Developer CLI használatával automatizált lépéseket biztosít az Azure Functions alkalmazás és esemény-előfizetés konfigurálásához, amelyek lehetővé teszik a lintinget és az elemzést az API-központban. Az erőforrásokat manuálisan is konfigurálhatja.

A beállítás egyéb előfeltételei

A minta futtatása azd

  1. Klónozza a GitHub-adattárat , és nyissa meg a Visual Studio Code-ban.

  2. Módosítsa a könyvtárat az APICenter-Analyzer adattár mappájába.

  3. resources/rulesets A mappában található egy oas.yaml fájl. Ez a fájl az aktuális API-stíluskalauzt tükrözi, és a szervezeti igények és követelmények alapján módosítható.

  4. Hitelesítés az Azure Developer CLI-vel és az Azure CLI-vel a következő parancsokkal:

    azd auth login

az login

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

    azd up

  6. Az utasításokat követve adja meg a szükséges üzembehelyezési információkat és beállításokat, például a környezet nevét és az API-központ nevét. További részletekért lásd : A minta futtatása az Azure Developer CLI (azd) használatával.

    Feljegyzés

    Az üzembe helyezés eltarthat néhány percig.

  7. Az üzembe helyezés befejezése után keresse meg az API-központot az Azure Portalon. A bal oldali menüben válassza az Eseményesemény-előfizetések> lehetőséget a létrehozott esemény-előfizetés megtekintéséhez.

Most már feltölthet egy API-definíciós fájlt az API-központba az esemény-előfizetés aktiválásához és a linting motor futtatásához.

Az Azure Functions alkalmazás- és esemény-előfizetés konfigurálásához szükséges manuális lépések

Ez a szakasz az Azure Functions alkalmazás és esemény-előfizetés konfigurálásának manuális üzembe helyezési lépéseit ismerteti, hogy lehetővé tegye a lintinget és az elemzést az API-központban. Az Azure Developer CLI-t is használhatja az automatikus üzembe helyezéshez.

A beállítás egyéb előfeltételei

1. lépés Az Azure Functions-alkalmazás üzembe helyezése

A linting függvényt API-definíciókon futtató Azure Functions-alkalmazás üzembe helyezése:

  1. Klónozza a GitHub-adattárat , és nyissa meg a Visual Studio Code-ban.

  2. resources/rulesets A mappában található egy oas.yaml fájl. Ez a fájl az aktuális API-stíluskalauzt tükrözi, és a szervezeti igények és követelmények alapján módosítható.

  3. A függvényalkalmazás helyi futtatásával tesztelheti azt. További részletekért tekintse meg a README fájlt az adattárban.

  4. A függvényalkalmazás üzembe helyezése az Azure-ban. A lépésekért tekintse meg a rövid útmutatót: Függvény létrehozása az Azure-ban TypeScript használatával a Visual Studio Code használatával.

    Feljegyzés

    A függvényalkalmazás üzembe helyezése eltarthat néhány percig.

  5. Jelentkezzen be az Azure Portalra, és nyissa meg a függvényalkalmazást.

  6. Az Áttekintés lapon ellenőrizze a következő részleteket:

    • Ellenőrizze, hogy a függvényalkalmazás állapota fut-e.
    • A Functions területen ellenőrizze, hogy az apicenter-analyzer függvény állapota engedélyezve van-e.

    Képernyőkép a függvényalkalmazásról a portálon.

2. lépés Felügyelt identitás konfigurálása a függvényalkalmazásban

Ha engedélyezni szeretné a függvényalkalmazás számára az API-központ elérését, konfiguráljon egy felügyelt identitást a függvényalkalmazáshoz. Az alábbi lépések bemutatják, hogyan engedélyezheti és konfigurálhatja a rendszer által hozzárendelt felügyelt identitást a függvényalkalmazáshoz az Azure Portal vagy az Azure CLI használatával.

  1. Az Azure Portalon keresse meg a függvényalkalmazást, és válassza az Identitás lehetőséget a Beállítások szakaszban.
  2. A Rendszerhez rendelt lapon állítsa be az állapotot Be értékre, majd válassza a Mentés lehetőséget.

Most, hogy a felügyelt identitás engedélyezve van, rendelje hozzá az Azure API Center Compliance Manager szerepkört az API-központ eléréséhez.

  1. Az Azure Portalon lépjen az API-központba, és válassza a Hozzáférés-vezérlés (IAM) lehetőséget.
  2. Válassza a + Szerepkör-hozzárendelés hozzáadása > lehetőséget.
  3. Válassza ki a Feladatfüggvény-szerepköröket , majd válassza az Azure API Center Compliance Managert. Válassza a Tovább lehetőséget.
  4. A Tagok lapon a Hozzáférés hozzárendelése területen válassza a Felügyelt identitás > + Tagok kijelölése lehetőséget.
  5. A Felügyelt identitások kiválasztása lapon keresse meg és válassza ki a függvényalkalmazás felügyelt identitását. Kattintson a Kijelölés, majd a Tovább gombra.
  6. Tekintse át a szerepkör-hozzárendelést, és válassza a Véleményezés + hozzárendelés lehetőséget.

3. lépés Esemény-előfizetés konfigurálása az API-központban

Most hozzon létre egy esemény-előfizetést az API-központban, amely elindítja a függvényalkalmazást egy API-definíciós fájl feltöltése vagy frissítésekor. Az alábbi lépések bemutatják, hogyan hozhatja létre az esemény-előfizetést az Azure Portal vagy az Azure CLI használatával.

  1. Az Azure Portalon lépjen az API-központba, és válassza az Események lehetőséget.

  2. Az Első lépések lapon válassza az Azure-függvényt.

  3. Az Esemény-előfizetés létrehozása lapon tegye a következőket:

    1. Adja meg az esemény-előfizetés leíró nevét, és válassza az Event Grid-séma lehetőséget.

    2. A Témakör részletei területen adja meg a választott rendszertémakör nevét .

    3. Az Eseménytípusok területen válassza ki a következő eseményeket:

      • API-definíció hozzáadva
      • Az API-definíció frissítve

    4. A Végpont részletei területen válassza az Azure-függvény > végpont konfigurálása lehetőséget.

    5. Az Azure-függvény kiválasztása lapon válassza ki a függvényalkalmazást és a konfigurált apicenter-linter függvényt. Kattintson a Kijelölés megerősítése gombra.

    6. Válassza a Létrehozás lehetőséget.

      Képernyőkép az esemény-előfizetés portálon való létrehozásáról.

  4. Válassza az Esemény-előfizetések lapot, és válassza a Frissítés lehetőséget. Győződjön meg arról, hogy az esemény-előfizetés kiépítési állapota sikeres.

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

Feljegyzés

Előfordulhat, hogy az esemény-előfizetés propagálása rövid ideig tart a függvényalkalmazásban.

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 API-k, API-verziók és API-definíciók API-központhoz való hozzáadásának részletes lépéseit a következő oktatóanyagban találja : API-k regisztrálása az API-központban.
  • Ha API-t szeretne létrehozni egy API-definíciós fájl Azure CLI-vel való feltöltésével, olvassa el az API regisztrálása specifikációs fájlból című témakört.

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

  1. Lépjen az API-központra, és válassza a bal oldali menü Események elemét .

  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 annak ellenőrzéséhez, hogy az esemény-előfizetés aktiválódott-e, és hogy a linting sikeres volt-e.

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

    Feljegyzés

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

Az API-definíció elemzése után 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ó elemzési jelentését az Azure Portalon 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-verziót az API-központban, ahol hozzáadott vagy frissített egy API-definíciót.
  2. A bal oldali menü Részletek területén válassza a Definíciók lehetőséget.
  3. Válassza ki a feltöltött vagy frissített API-definíciót.
  4. Válassza az Elemzés lapot. Képernyőkép az API-definíció Elemzés lapjáról a 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özpont összes API-definíciójának elemzési jelentéseinek összegzése:

  1. A portálon keresse meg az API-központot.

  2. A bal oldali menü Irányítás területén válassza az API-elemzés lehetőséget. Megjelenik az összegzés.

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

Kapcsolódó tartalom

További információ az Event Gridről: