Een OpenAPI-specificatie importeren

VAN TOEPASSING OP: Alle API Management-lagen

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 quickstart voor Bash in 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. Raadpleeg Aanmelden bij Azure CLI voor aanvullende aanmeldingsopties.

    • Installeer de Azure CLI-extensie bij het eerste gebruik, wanneer u hierom wordt gevraagd. Raadpleeg Extensies gebruiken met Azure CLI voor 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.

Portal

1. Blader in Azure Portal naar uw API Management-exemplaar.

2. Selecteer API's+ API's> toevoegen in het linkermenu.

3. Selecteer OpenAPI onder Maken op basis van definitie.

   

4. 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.

5. Selecteer Maken.

Azure-CLI

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 .

Powershell

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:

1. Blader in Azure Portal naar uw API Management-exemplaar.
2. Selecteer in het linkermenu, onder API's, API's>< uw API>>Alle bewerkingen.
3. Selecteer op het tabblad Ontwerpen in Front-end openAPI-specificatieeditor (potloodpictogram). U kunt de specificatie openen in JSON- of YAML-indeling.
4. 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.

1. Selecteer de API die u in de vorige stap hebt gemaakt.

2. Selecteer het tabblad Testen.

3. 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.

4. Voer, afhankelijk van de bewerking, queryparameterwaarden, headerwaarden of aanvraagbody in. Selecteer Verzenden.

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

   Tip

   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 fouten in een API wilt opsporen, raadpleegt u zelfstudie: Fouten opsporen in uw API's met behulp van aanvraagtracering.

Andere API's toevoegen

U kunt een API opstellen van API's die beschikbaar worden gesteld door verschillende services, waaronder:

• Een OpenAPI-specificatie
• Een SOAP-API
• Een GraphQL-API
• Een web-app die wordt gehost in Azure-app Service
• Azure Function-app
• Azure Logic-apps
• Azure Service Fabric

Voeg een andere API toe aan uw bestaande API met behulp van de volgende stappen.

Notitie

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

1. Ga naar uw Azure API Management-exemplaar in de Azure-portal.

   

2. Selecteer API's op de pagina Overzicht of in het menu aan de linkerkant.

   

3. Selecteer het beletselsteken (... ) naast de API waaraan u een andere API wilt toevoegen.

4. Selecteer Importeren in de vervolgkeuzelijst.

   

5. Selecteer de service waaruit een API moet worden geïmporteerd.

   

Verwante onderwerpen

• Beperkingen bij het importeren van API's
• Een OpenAPI-specificatie importeren
• Een SOAP-API importeren
• Een SOAP-API importeren en deze converteren naar REST
• Een App Service-API importeren
• Een Container App-API importeren
• Een WebSocket-API importeren
• Een GraphQL-API importeren
• Een GraphQL-schema importeren en veldoplossers instellen
• Een Azure-functie-app importeren
• Een logische Azure-app importeren
• Een Service Fabric-service importeren
• Een Azure OpenAI-API importeren
• Een OData-API importeren
• SAP OData-metagegevens importeren
• Een gRPC-API importeren
• Een API bewerken

Volgende stappen

• Een product maken en publiceren
• Een gepubliceerde API transformeren en beveiligen