A linting és az elemzés engedélyezése az API-szabályozáshoz az API-központban
Ez a cikk bemutatja, hogyan engedélyezheti a lintinget a szervezet API-központjában található API-definíciók elemzéséhez, hogy megfeleljen a szervezetek API-stílusszabályainak. A linting létrehoz egy elemzési jelentést, amelyet az API-központban érhet el. Az API-linting és az elemzés használatával észlelheti az API-definíciók gyakori hibáit és inkonzisztenciáit.
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 jelentés az API-megfelelőségről, 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.
Helyezzen üzembe egy Azure Functions-alkalmazást, amely a Spectral linting motort futtatja egy API-definíción.
Konfiguráljon egy esemény-előfizetést egy Azure API-központban a függvényalkalmazás aktiválásához.
Az eseményt egy API-definíció hozzáadása vagy cseréje váltja ki az API-központban.
Az esemény fogadásakor a függvényalkalmazás meghívja a Spectral linting motort.
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.
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 (
azd
CLI). 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:
Használja a Bash-környezetet az Azure Cloud Shellben. További információ: A Bash rövid útmutatója az Azure Cloud Shellben.
Ha inkább helyi cli-referenciaparancsokat szeretne futtatni, telepítse az Azure CLI-t. Ha Windows vagy macOS rendszert használ, fontolja meg az Azure CLI Docker-tárolóban való futtatását. További információ: Az Azure CLI futtatása Docker-tárolóban.
Ha helyi telepítést használ, jelentkezzen be az Azure CLI-be az az login parancs futtatásával. A hitelesítési folyamat befejezéséhez kövesse a terminálon megjelenő lépéseket. További bejelentkezési lehetőségekért lásd : Bejelentkezés az Azure CLI-vel.
Amikor a rendszer kéri, először telepítse az Azure CLI-bővítményt. További információ a bővítményekről: Bővítmények használata az Azure CLI-vel.
Futtassa az az version parancsot a telepített verzió és a függő kódtárak megkereséséhez. A legújabb verzióra az az upgrade paranccsal frissíthet.
Feljegyzés
az apic
parancsokhoz azapic-extension
Azure CLI-bővítmény szükséges. Ha még nem használtaz 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
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
Klónozza a GitHub-adattárat , és nyissa meg a Visual Studio Code-ban.
Módosítsa a könyvtárat az
APICenter-Analyzer
adattár mappájába.resources/rulesets
A mappában található egyoas.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ó.Hitelesítés az Azure Developer CLI-vel és az Azure CLI-vel a következő parancsokkal:
azd auth login az login
Futtassa a következő parancsot a linting infrastruktúra Azure-előfizetésben való üzembe helyezéséhez.
azd up
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.
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
- Visual Studio Code az Azure Functions 1.10.4-s vagy újabb verziójával.
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:
Klónozza a GitHub-adattárat , és nyissa meg a Visual Studio Code-ban.
resources/rulesets
A mappában található egyoas.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ó.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.
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.
Jelentkezzen be az Azure Portalra, és nyissa meg a függvényalkalmazást.
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.
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.
- 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.
- 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.
- Az Azure Portalon lépjen az API-központba, és válassza a Hozzáférés-vezérlés (IAM) lehetőséget.
- Válassza a + Szerepkör-hozzárendelés hozzáadása > lehetőséget.
- 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.
- 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.
- 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.
- 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.
Az Azure Portalon lépjen az API-központba, és válassza az Események lehetőséget.
Az Első lépések lapon válassza az Azure-függvényt.
Az Esemény-előfizetés létrehozása lapon tegye a következőket:
Adja meg az esemény-előfizetés leíró nevét, és válassza az Event Grid-séma lehetőséget.
A Témakör részletei területen adja meg a választott rendszertémakör nevét .
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
A Végpont részletei területen válassza az Azure-függvény > végpont konfigurálása lehetőséget.
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.
Válassza a Létrehozás lehetőséget.
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.
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:
Lépjen az API-központra, és válassza a bal oldali menü Események elemét .
Válassza az Esemény-előfizetések lapot, és válassza ki a függvényalkalmazás esemény-előfizetését.
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.
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:
- A portálon keresse meg az API-verziót az API-központban, ahol hozzáadott vagy frissített egy API-definíciót.
- A bal oldali menü Részletek területén válassza a Definíciók lehetőséget.
- Válassza ki a feltöltött vagy frissített API-definíciót.
- Válassza az Elemzés lapot.
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.
API-elemzés összegzése
Az API-központ összes API-definíciójának elemzési jelentéseinek összegzése:
A portálon keresse meg az API-központot.
A bal oldali menü Irányítás területén válassza az API-elemzés lehetőséget. Megjelenik az összegzés.
Kapcsolódó tartalom
További információ az Event Gridről: