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.

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:

  • 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 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

  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

• Azure Developer CLI (azd)

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

• 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:

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.

   

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.

Portál

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.

Azure CLI

1. Engedélyezze a függvényalkalmazás rendszer által hozzárendelt identitását az az functionapp identity assign paranccsal. Cserélje le és <resource-group-name> írja be <function-app-name> a függvényalkalmazás nevét és az erőforráscsoport nevét. Az alábbi parancs a rendszer által hozzárendelt felügyelt identitás egyszerű azonosítóját tárolja a principalID változóban.

   #! /bin/bash
   principalID=$(az functionapp identity assign --name <function-app-name> \
       --resource-group <resource-group-name> --identities [system] \
       --query "principalId" --output tsv)
   

   # PowerShell syntax
   $principalID=$(az functionapp identity assign --name <function-app-name> `
       --resource-group <resource-group-name> --identities [system] `
       --query "principalId" --output tsv)
   

2. Kérje le az API-központ erőforrás-azonosítóját. Cserélje le <apic-name> az <resource-group-name> API-központ nevét és az erőforráscsoport nevét.

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

3. Rendelje hozzá a függvényalkalmazás felügyelt identitását az Azure API Center Compliance Manager szerepkörhöz az API-központban az az role assignment create paranccsal.

   #! /bin/bash
   az role assignment create \
       --role "Azure API Center Compliance Manager" \
       --assignee-object-id $principalID \
       --assignee-principal-type ServicePrincipal \
       --scope $apicID 
   

   # PowerShell syntax
   az role assignment create `
       --role "Azure API Center Compliance Manager" `
       --assignee-object-id $principalID `
       --assignee-principal-type ServicePrincipal `
       --scope $apicID 
   

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.

Portál

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.

      

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.

   

Azure CLI

1. Kérje le az API-központ erőforrás-azonosítóját. Cserélje le <apic-name> az <resource-group-name> API-központ nevét és az erőforráscsoport nevét.

   #! /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. Helyettesítse be <function-app-name> a <resource-group-name> függvényalkalmazás nevét és az erőforráscsoport nevét.

   #! /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. Hozzon létre egy esemény-előfizetést az 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. Például:

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

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.

   

   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.

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:

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.

   

Kapcsolódó tartalom

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

• Rendszertémakörök az Azure Event Gridben
• Event Grid leküldéses kézbesítés – fogalmak
• Event Grid-séma az Azure API Centerhez