Een OpenAPI-specificatie importeren

2025-04-04

VAN TOEPASSING OP: Alle API Management-niveaus

In dit artikel wordt beschreven hoe u een back-end-API van OpenAPI-specificatie importeert in Azure API Management met behulp van verschillende hulpprogramma's. In het artikel wordt ook beschreven hoe u de API kunt testen in API Management.

In dit artikel leert u het volgende:

Een OpenAPI-specificatie importeren met behulp van Azure Portal, Azure CLI of Azure PowerShell
De API testen in Azure Portal

Notitie

API-importbeperkingen worden beschreven in API-importbeperkingen en bekende problemen.

Vereisten

Een API Management-exemplaar. Als u nog geen exemplaar hebt, voltooit u de volgende quickstart: Een Azure API Management-exemplaar maken.
Azure-CLI
- Gebruik de Bash-omgeving in Azure Cloud Shell. Zie Aan de slag met Azure Cloud Shell voor meer informatie.
- Installeer de Azure CLI, indien gewenst, om CLI-referentieopdrachten uit te voeren. Als u in Windows of macOS werkt, kunt u Azure CLI uitvoeren in een Docker-container. Zie De Azure CLI uitvoeren in een Docker-container voor meer informatie.
  - Als u een lokale installatie gebruikt, meldt u zich aan bij Azure CLI met behulp van de opdracht az login. Volg de stappen die worden weergegeven in de terminal, om het verificatieproces te voltooien. Zie Verifiëren bij Azure met behulp van Azure CLI voor andere aanmeldingsopties.
  - Installeer de Azure CLI-extensie bij het eerste gebruik, wanneer u hierom wordt gevraagd. Zie Extensies gebruiken en beheren met de Azure CLIvoor meer informatie over extensies.
  - Voer az version uit om de geïnstalleerde versie en afhankelijke bibliotheken te vinden. Voer az upgrade uit om te upgraden naar de nieuwste versie.
Azure PowerShell
- Als u ervoor kiest om Azure PowerShell lokaal te gebruiken:
  - Installeer de nieuwste versie van de Az PowerShell-module.
  - Maak verbinding met uw Azure-account met de cmdlet Connect-AzAccount.
- Als u ervoor kiest om Azure Cloud Shell te gebruiken:
  - Raadpleeg Overzicht van Azure Cloud Shell voor meer informatie.

Een back-end-API importeren

In dit voorbeeld importeert u de OpenAPI-specificatie voor de open source Petstore-API, maar u kunt een OpenAPI-specificatie van uw keuze vervangen.

Blader in Azure Portal naar uw API Management-exemplaar.
Selecteer in het linkermenu API's>+ API toevoegen.
Selecteer OpenAPI onder Maken op basis van definitie.
Voer API-instellingen in. U kunt de waarden instellen tijdens het maken of later configureren door naar het tabblad Instellingen te gaan. De instellingen worden uitgelegd in de zelfstudie Uw eerste API importeren en publiceren.
Kies Aanmaken.

In het volgende voorbeeld wordt de importopdracht az apim api gebruikt om een OpenAPI-specificatie te importeren van de opgegeven URL naar een API Management-exemplaar met de naam apim-hello-world. Als u wilt importeren met behulp van een pad naar een specificatie in plaats van een URL, gebruikt u de --specification-path parameter.

# 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

Nadat u de API hebt geïmporteerd, kunt u, indien nodig, de instellingen bijwerken met behulp van de opdracht az apim api update .

In het volgende voorbeeld wordt de Cmdlet Import-AzApiManagementApi Azure PowerShell gebruikt om een OpenAPI-specificatie te importeren van de opgegeven URL naar een API Management-exemplaar met de naam apim-hello-world. Als u wilt importeren met behulp van een pad naar een specificatie in plaats van een URL, gebruikt u de -SpecificationPath parameter.

# 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

Nadat u de API hebt geïmporteerd, kunt u, indien nodig, de instellingen bijwerken met behulp van de cmdlet Set-AzApiManagementApi .

OpenAPI-specificatie weergeven en bewerken

Gebruik in de portal de OpenAPI-specificatie-editor om de specificatie te bekijken, te valideren of te bewerken voor de API die u hebt geïmporteerd.

Ga als volgt te werk om de OpenAPI-specificatie-editor te gebruiken:

Blader in Azure Portal naar uw API Management-exemplaar.
Selecteer in het linkermenu, onder API's, API's><uw API>>Alle bewerkingen.
Selecteer op het tabblad Ontwerpen in Front-end openAPI-specificatieeditor (potloodpictogram). U kunt de specificatie openen in de JSON- of YAML-formaat.
Controleer of bewerk de specificatie indien nodig. Sla uw wijzigingen op.

Valideren op basis van een OpenAPI-specificatieschema

U kunt API Management-validatiebeleid configureren om aanvragen en antwoorden (of elementen ervan) te valideren op basis van het schema in een OpenAPI-specificatie. Gebruik bijvoorbeeld het beleid voor validatie-inhoud om de grootte of inhoud van een aanvraag- of antwoordtekst te valideren.

De nieuwe API testen in de portal

Bewerkingen kunnen rechtstreeks vanuit de portal worden aangeroepen, zodat beheerders de bewerkingen van een API kunnen bekijken en testen.

Selecteer de API die u in de vorige stap hebt gemaakt.
Selecteer het tabblad Testen.
Selecteer een bewerking. De pagina geeft velden weer voor queryparameters en velden voor de headers.

Notitie

In de testconsole vult API Management automatisch een Ocp-Apim-Subscription-Key-header in en configureert de abonnementssleutel van het ingebouwde abonnement voor alle toegang. Met deze sleutel hebt u toegang tot elke API in het API Management-exemplaar. U kunt desgewenst de header Ocp-Apim-Subscription-Key weergeven door het pictogram 'oog' naast de HTTP-aanvraag te selecteren.
Voer, afhankelijk van de bewerking, queryparameterwaarden, headerwaarden of aanvraagbody in. Klik op Verzenden.

Wanneer de test is geslaagd, reageert de back-end met een geslaagde HTTP-antwoordcode en enkele gegevens.

Aanbeveling

De testconsole verzendt standaard een aanvraag naar de CORS-proxy van API Management, die de aanvraag doorstuurt naar het API Management-exemplaar, dat deze vervolgens doorstuurt naar de back-end. Deze proxy gebruikt openbaar IP-adres 13.91.254.72 en kan alleen openbare eindpunten bereiken. Als u een aanvraag rechtstreeks vanuit de browser naar de API Management-service wilt verzenden, selecteert u CORS-proxy overslaan. Gebruik deze optie als u de testconsole wilt gebruiken en uw API Management-gateway netwerkisoleert of geen verkeer van de CORS-proxy toestaat.

Als u een API wilt debuggen, raadpleegt de handleiding: API's debuggen met behulp van aanvraagtracering.

Andere API's toevoegen

U kunt een API samenstellen uit API's die worden weergegeven door verschillende services, waaronder:

Een OpenAPI-specificatie
Een SOAP-API
Een GraphQL-API
Een web-app die wordt gehost in Azure App Service
Azure Functions (serverloze computerdiensten van Azure)
Azure Logic Apps
Azure Service Fabric

Notitie

Wanneer u een API importeert, worden de bewerkingen toegevoegd aan uw huidige API.

Een API toevoegen aan een bestaande API:

Ga naar uw Azure API Management-exemplaar in Azure Portal:
Selecteer API's op de Overzicht pagina of selecteer API's>API's in het menu aan de linkerkant.

Screenshot van de selectie van API's op de pagina 'Overzicht'.
Selecteer het beletselteken (#A0 ... #A1) naast de API waaraan u een andere API wilt toevoegen.
Selecteer Import uit het vervolgkeuzemenu.
Selecteer de service waaruit een API moet worden geïmporteerd.

Delen via