Importera en OpenAPI-specifikation

GÄLLER FÖR: Alla API Management-nivåer

Den här artikeln visar hur du importerar en "OpenAPI-specifikation" serverdels-API till Azure API Management med hjälp av olika verktyg. Artikeln visar också hur du testar API:et i API Management.

I den här artikeln kan du se hur du:

• Importera en OpenAPI-specifikation med hjälp av Azure Portal, Azure CLI eller Azure PowerShell
• Testa API:et i Azure Portal

Kommentar

BEGRÄNSNINGAR för API-import dokumenteras i API-importbegränsningar och kända problem.

Förutsättningar

• En API Management-instans. Om du inte redan har en, slutför du följande snabbstart: Skapa en Azure API Management-instans.

• Azure CLI

  • Använd Bash-miljön i Azure Cloud Shell. Mer information finns i Snabbstart för Bash i Azure Cloud Shell.

    

  • Om du föredrar att köra CLI-referenskommandon lokalt installerar du Azure CLI. Om du kör i Windows eller macOS kan du köra Azure CLI i en Docker-container. Mer information finns i Så här kör du Azure CLI i en Docker-container.

    • Om du använder en lokal installation loggar du in på Azure CLI med hjälp av kommandot az login. Slutför autentiseringsprocessen genom att följa stegen som visas i terminalen. Andra inloggningsalternativ finns i Logga in med Azure CLI.

    • När du uppmanas att installera Azure CLI-tillägget vid första användningen. Mer information om tillägg finns i Använda tillägg med Azure CLI.

    • Kör az version om du vill hitta versionen och de beroende bibliotek som är installerade. Om du vill uppgradera till den senaste versionen kör du az upgrade.

• Azure PowerShell

  • Om du väljer att använda Azure PowerShell lokalt:
    • Installera den senaste versionen av Az PowerShell-modulen.
    • Anslut till ditt Azure-konto med hjälp av cmdleten Connect-AzAccount .
  • Om du väljer att använda Azure Cloud Shell:
    • Mer information finns i Översikt över Azure Cloud Shell .

Importera ett serverdels-API

I det här exemplet importerar du OpenAPI-specifikationen för öppen källkod Petstore API, men du kan ersätta en OpenAPI-specifikation som du väljer.

Portal

1. I Azure Portal navigerar du till din API Management-instans.

2. I den vänstra menyn väljer du API:er>+ Lägg till API.

3. Under Skapa från definition väljer du OpenAPI.

   

4. Ange API-inställningar. Du kan ange värdena när du skapar eller konfigurera dem senare genom att gå till fliken Inställningar . Inställningarna beskrivs i självstudien Importera och publicera ditt första API .

5. Välj Skapa.

Azure CLI

I följande exempel används kommandot az apim api import för att importera en OpenAPI-specifikation från den angivna URL:en till en API Management-instans med namnet apim-hello-world. Om du vill importera med hjälp av en sökväg till en specifikation i stället för en URL använder du parametern --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

När du har importerat API:et kan du vid behov uppdatera inställningarna med hjälp av kommandot az apim api update .

PowerShell

I följande exempel används Azure PowerShell-cmdleten Import-AzApiManagementApi för att importera en OpenAPI-specifikation från den angivna URL:en till en API Management-instans med namnet apim-hello-world. Om du vill importera med hjälp av en sökväg till en specifikation i stället för en URL använder du parametern -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

När du har importerat API:et kan du vid behov uppdatera inställningarna med hjälp av cmdleten Set-AzApiManagementApi .

Visa och redigera OpenAPI-specifikation

I portalen använder du OpenAPI-specifikationsredigeraren för att visa, verifiera eller redigera specifikationen för det API som du importerade.

Så här använder du OpenAPI-specifikationsredigeraren:

1. I Azure Portal navigerar du till din API Management-instans.
2. I den vänstra menyn, under API:er, väljer du API:er><dina API>>Alla åtgärder.
3. På fliken Design i Klientdelen väljer du OpenAPI Specification Editor (pennikon). Du kan öppna specifikationen i JSON- eller YAML-format.
4. Granska eller redigera specifikationen efter behov. Spara dina ändringar.

Verifiera mot ett OpenAPI-specifikationsschema

Du kan konfigurera API Management-valideringsprinciper för att verifiera begäranden och svar (eller element av dem) mot schemat i en OpenAPI-specifikation. Använd till exempel policyn för valideringsinnehåll för att verifiera storleken eller innehållet i en begäran eller svarstext.

Testa det nya API:et i portalen

Åtgärder kan anropas direkt från portalen, vilket är ett bekvämt sätt för administratörer att visa och testa åtgärderna i ett API.

1. Välj det API som du skapade i föregående steg.

2. Välj fliken Test.

3. Välj en åtgärd. Sidan visar fält för frågeparametrar och fält för sidhuvudena.

   Kommentar

   I testkonsolen fyller API Management automatiskt i huvudet Ocp-Apim-Subscription-Key och konfigurerar prenumerationsnyckeln för den inbyggda all-access-prenumerationen. Den här nyckeln ger åtkomst till varje API i API Management-instansen. Du kan också visa huvudet Ocp-Apim-Subscription-Key genom att välja "öga"-ikonen bredvid HTTP-begäran.

4. Beroende på åtgärden anger du frågeparametervärden, rubrikvärden eller en begärandetext. Välj Skicka.

   När testet lyckas svarar serverdelen med en lyckad HTTP-svarskod och vissa data.

   Dricks

   Som standard skickar testkonsolen en begäran till API Managements CORS-proxy, som vidarebefordrar begäran till API Management-instansen, som sedan vidarebefordrar den till serverdelen. Den här proxyn använder den offentliga IP-adressen 13.91.254.72 och kan bara nå offentliga slutpunkter. Om du vill skicka en begäran direkt från webbläsaren till API Management-tjänsten väljer du Kringgå CORS-proxy. Använd det här alternativet när du vill använda testkonsolen och DIN API Management-gateway är nätverksisolerad eller inte tillåter trafik från CORS-proxyn.

Information om hur du felsöker ett API finns i Självstudie: Felsöka dina API:er med hjälp av spårning av begäranden.

Lägg till andra API:er

Du kan skapa ett API för API:er som exponeras av olika tjänster, inklusive:

• En OpenAPI-specifikation
• ETT SOAP-API
• Ett GraphQL-API
• En webbapp som finns i Azure App Service
• Azure-funktionsapp
• Azure Logic Program-program
• Azure Service Fabric

Lägg till ett annat API i ditt befintliga API med hjälp av följande steg.

Kommentar

När du importerar ett annat API läggs åtgärderna i ditt aktuella API.

1. Gå till din Azure API Management-instans i Azure-portalen.

   

2. Välj API:er på sidan Översikt eller på menyn till vänster.

   

3. Klicka på ... intill det API som du vill lägga till ett annat API till.

4. Välj Import från den nedrullningsbara menyn.

   

5. Välj en tjänst som ett API ska importeras från.

   

Närliggande information

• Begränsningar för API-import
• Importera en OpenAPI-specifikation
• Importera ett SOAP-API
• Importera ett SOAP-API och konvertera till REST
• Importera ett App Service-API
• Importera ett API för containerapp
• Importera ett WebSocket-API
• Importera ett GraphQL-API
• Importera ett GraphQL-schema och konfigurera fältmatchare
• Importera en Azure-funktionsapp
• Importera en Azure-logikapp
• Importera en Service Fabric-tjänst
• Importera ett Azure OpenAI-API
• Importera ett OData-API
• Importera SAP OData-metadata
• Importera ett gRPC-API
• Redigera ett API

Nästa steg

• Skapa och publicera en produkt
• Omvandla och skydda ett publicerat API