OpenAPI-specifikáció importálása

Minden API-kezelési szintre érvényes

Ez a cikk bemutatja, hogyan importálhat openAPI-specifikációs háttér API-t az Azure API Managementbe különböző eszközökkel. A cikk azt is bemutatja, hogyan tesztelheti az API-t az API Managementben. Az OpenAPI-verzió támogatásával kapcsolatos információkért tekintse meg az API importálási korlátozásait és az ismert problémákat.

Ebben a cikkben az alábbiakkal ismerkedhet meg:

• OpenAPI-specifikáció importálása az Azure Portal, az Azure CLI vagy az Azure PowerShell használatával
• Az API tesztelése az Azure Portalon

Előfeltételek

• API Management-példány. Ha még nincs ilyenje, végezze el az alábbi rövid útmutatót: Azure API Management-példány létrehozása.

• Azure CLI (Az Azure parancssori felülete)

  • Használja a Bash-környezetet az Azure Cloud Shellben. További információ: Az Azure Cloud Shell használatának első lépései.

    

  • 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: Hitelesítés az Azure-ba az Azure CLI használatával.

    • 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 és kezelése 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.

• Azure PowerShell

  • Ha az Azure PowerShell helyi használatát választja:
    • Telepítse az Az PowerShell-modul legújabb verzióját.
    • Csatlakozzon az Azure-fiókjához a Connect-AzAccount parancsmag használatával.
  • Ha az Azure Cloud Shell használata mellett dönt:
    • További információkért tekintse meg az Azure Cloud Shell áttekintését.

Háttér API importálása

Ebben a példában importálja a nyílt forráskódú Petstore APIOpenAPI-specifikációját. A választott OpenAPI-specifikációt helyettesítheti.

Portál

1. Az Azure Portalon keresse meg az API Management-példányt.

2. A bal oldali menüben válassza az API-k>+ API hozzáadása lehetőséget.

3. A Létrehozás definícióból alatt válassza az OpenAPI lehetőséget.

   

4. Adja meg az API-beállításokat. Az értékeket a létrehozás során állíthatja be, vagy később konfigurálhatja őket a Beállítások lapon. A beállításokat az első API-oktatóanyag importálása és közzététele ismerteti.

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

Azure CLI

Az alábbi példa az az apim api import parancs használatával importál egy OpenAPI-specifikációt a megadott URL-címről egy apim-hello-world nevű API Management-példányba. Ha URL-cím helyett specifikáció elérési útján szeretne importálni, használja a paramétert --specification-path .

# API Management service-specific details
APIMServiceName="apim-hello-world"
ResourceGroupName="myResourceGroup"

# API-specific details
APIId="swagger-petstore"
APIPath="store"
SpecificationFormat="OpenAPI"
SpecificationURL="https://petstore3.swagger.io/api/v3/openapi.json"

# Import API
az apim api import --path $APIPath --resource-group $ResourceGroupName \
    --service-name $APIMServiceName --api-id $APIId \
    --specification-format $SpecificationFormat --specification-url $SpecificationURL

Az API importálása után az az apim api update paranccsal frissítheti a beállításokat.

PowerShell

Az alábbi példa az Import-AzApiManagementApi Azure PowerShell-parancsmaggal importál egy OpenAPI-specifikációt a megadott URL-címről egy apim-hello-world nevű API Management-példányba. Ha URL-cím helyett specifikáció elérési útján szeretne importálni, használja a paramétert -SpecificationPath .

# API Management service-specific details
$apimServiceName = "apim-hello-world"
$resourceGroupName = "myResourceGroup"

# API-specific details
$apiId = "swagger-petstore"
$apiPath = "store"
$specificationFormat = "OpenAPI"
$specificationUrl = "https://petstore3.swagger.io/api/v3/openapi.json"

# Get context of the API Management instance. 
$context = New-AzApiManagementContext -ResourceGroupName $resourceGroupName -ServiceName $apimServiceName

# Import API
Import-AzApiManagementApi -Context $context -ApiId $apiId -SpecificationFormat $specificationFormat -SpecificationUrl $specificationUrl -Path $apiPath

Az API importálása után a Set-AzApiManagementApi parancsmaggal frissítheti a beállításokat.

OpenAPI-specifikáció megtekintése és szerkesztése

Az Azure Portalon az OpenAPI specifikációszerkesztőjével megtekintheti, érvényesítheti vagy szerkesztheti az importált API specifikációját.

Az OpenAPI specifikációszerkesztőjének használata:

1. Az Azure Portalon keresse meg az API Management-példányt.
2. A bal oldali menüBEN, az API-k alatt válassza az
3. A Tervezés lap Frontend területén válassza az OpenAPI Specifikációszerkesztőt (ceruza ikon). A specifikáció JSON vagy YAML formátumban is megnyitható.
4. Szükség szerint tekintse át vagy szerkessze a specifikációt. Mentse a módosításokat.

Ellenőrzés OpenAPI-specifikációs sémával

Az API Management érvényesítési szabályzatait úgy konfigurálhatja, hogy a kéréseket és válaszokat vagy azok elemeit az OpenAPI-specifikáció sémája alapján érvényesítse. Használhatja például a tartalomérvényesítési szabályzatot egy kérés vagy válasz törzs méretének vagy tartalmának ellenőrzéséhez.

Az új API tesztelése a portálon

A műveleteket közvetlenül az Azure Portalról hívhatja meg, így kényelmesen megtekintheti és tesztelheti az API műveleteit.

1. Válassza ki az előző lépésben létrehozott API-t.

2. Kattintson a Teszt fülre.

3. Válasszon ki egy művelet.

   Az oldalon megjelennek a lekérdezési paraméterek és a fejlécek mezői.

   Megjegyzés:

   A tesztkonzolon az API Management automatikusan feltölt egy Ocp-Apim-Subscription-Key fejlécet, és konfigurálja a beépített teljes hozzáférésű előfizetés előfizetési kulcsát. Ez a kulcs lehetővé teszi az API Management-példány összes API-jának elérését. Az Ocp-Apim-Subscription-Key fejlécet igény szerint a HTTP-kérés melletti "szem" ikonra kattintva jelenítheti meg.

4. A művelettől függően adja meg a lekérdezési paraméter értékeit, a fejlécértékeket vagy a kérelem törzsét. Válassza az Küldés lehetőséget.

   Ha a teszt sikeres, a háttérrendszer egy sikeres HTTP-válaszkóddal és néhány adattal válaszol.

   Jótanács

   Alapértelmezés szerint a tesztkonzol kérést küld az API Management CORS-proxyjának, amely továbbítja a kérést az API Management-példánynak, majd továbbítja azt a háttérrendszernek. Ez a proxy a 13.91.254.72 nyilvános IP-címet használja, és csak nyilvános végpontokat tud elérni.

   Ha közvetlenül a böngészőből szeretne kérést küldeni az API Management szolgáltatásnak, válassza a CORS-proxy megkerülése lehetőséget. Ezt a lehetőséget akkor használja, ha a tesztkonzolt szeretné használni, és az API Management-átjáró hálózati elkülönítésű, vagy nem engedélyezi a CORS-proxyból érkező forgalmat.

Az API-k hibakereséséhez tekintse meg az oktatóanyagot: Api-k hibakeresése kéréskövetés használatával.

Egyéb API-k hozzáfűzése

Az API-kat különböző szolgáltatások által közzétett API-kból állíthatja össze, többek között a következőket:

• OpenAPI-specifikáció
• A SOAP alkalmazásprogramozási felület
• A GraphQL programozási interfész (API)
• Az Azure App Service-ben üzemeltetett webalkalmazás
• Azure Functions
• Azure Logic Apps
• Azure Service Fabric

Megjegyzés:

Api importálásakor a műveletek hozzá lesznek fűzve az aktuális API-hoz.

API hozzáfűzése egy meglévő API-hoz:

1. Nyissa meg az Azure API Management-példányt az Azure Portalon:

   

2. Válassza az API-kat az Áttekintés lapon, vagy válassza az API-kat> az oldalsáv menüjében.

   

3. Jelölje ki a három pontot (...) azon API mellett, amelyhez hozzá szeretne fűzni egy másik API-t.

4. Válassza az Importálás lehetőséget a helyi menüből:

   

5. Válasszon egy szolgáltatást, amelyből importálni fogja az API-t.

Kapcsolódó tartalom

• API-importálási korlátozások
• OpenAPI-specifikáció importálása
• SOAP API importálása
• Egy SOAP API importálása és REST konvertálása
• App Service API importálása
• Tárolóalkalmazás API importálása
• WebSocket API importálása
• GraphQL API-k importálása
• GraphQL-sémák importálása és mezőfeloldók beállítása
• Függvényalkalmazás API importálása
• Logikai alkalmazás API importálása
• Service Fabric-szolgáltatás importálása
• Microsoft Foundry API importálása
• Azure OpenAI API importálása
• LLM API importálása
• OData API importálása
• REST API exportálása MCP-kiszolgálóként
• Meglévő MCP-kiszolgáló hozzáférhetővé tétele
• A2A-ügynök API importálása
• SAP OData-metaadatok importálása
• GRPC API importálása
• API szerkesztése