Zelfstudie: Meerdere versies van uw API publiceren

Van toepassing op: Alle API Management-lagen

Er zijn situaties waarin het niet praktisch is voor alle API-gebruikers om dezelfde versie te gebruiken. Wanneer consumenten klaar zijn om te upgraden naar een nieuwere versie, geven ze de voorkeur aan een eenvoudige en begrijpelijke benadering. Zoals in deze zelfstudie is gedemonstreerd, biedt Azure API Management ondersteuning voor het beschikbaar maken van meerdere API-versies om aan deze behoefte te voldoen.

Voor achtergrondinformatie, zie Versies en Revisies.

Aanbeveling

API-teams kunnen deze functie gebruiken in werkruimten. Werkruimten bieden geïsoleerde beheerderstoegang tot API's en hun eigen API-runtimeomgevingen.

In deze zelfstudie leert u het volgende:

• Een nieuwe versie toevoegen aan een bestaande API
• Een versieschema kiezen
• Voeg de versie toe aan een product
• De versie weergeven in de ontwikkelaarsportal

Vereiste voorwaarden

• Meer informatie over Azure API Management-terminologie.
• Voltooi de Quickstart Een Azure API Management-exemplaar aanmaken.
• Voltooi de zelfstudie Importeren en publiceer uw eerste API.

Een nieuwe versie toevoegen

1. Blader in Azure Portal naar uw API Management-exemplaar.
2. Selecteer API's in het linkermenu in de sectie API's.
3. Zoek Swagger Petstore - OpenAPI 3.0 in de API-lijst. Selecteer het beletselteken (...) naast Swagger Petstore - OpenAPI 3.0 en selecteer vervolgens Versie toevoegen. In de volgende sectie voegt u waarden toe aan het resulterende venster.

Aanbeveling

U kunt ook versies inschakelen wanneer u een nieuwe API maakt. Selecteer Versie van deze API? in het scherm API toevoegen.

Kies een versiebeheerschema

In API Management kiest u hoe bellers de API-versie opgeven door een versiebeheerschema te selecteren: Pad, Header of Querytekenreeks. In het volgende voorbeeld wordt Pad gebruikt als versiebeheerschema.

Voer in het venster Maak een nieuwe API als een versie de waarden uit de volgende tabel in. Selecteer vervolgens Maken om uw versie te maken.

Configuratie	Waarde	Beschrijving
Versie-identificatie	v1	Schema-specifieke aanduiding van de versie. Voor Pad, het achtervoegsel voor het URL-pad van de API.
Schema voor versiebeheer	Pad	De manier waarop oproepers de API-versie opgeeft. Als u header of query-string selecteert, voer dan een andere waarde in: de naam van de header- of querystringparameter. Er wordt een gebruiksvoorbeeld weergegeven.
Volledige API-versienaam	swagger-petstore-openapi-3-0-v1	Unieke naam in uw API Management-instantie. Omdat een versie eigenlijk een nieuwe API is die is gebaseerd op de revisie van een API, is deze waarde de naam van de nieuwe API.
PRODUCTEN	Onbeperkt (geleverd in sommige servicelagen)	Optioneel een of meer producten waaraan de API-versie gekoppeld is. Als u de API wilt publiceren, moet u deze koppelen aan een product. U kunt de versie later ook toevoegen aan een product.

Nadat u de versie hebt gemaakt, wordt deze weergegeven onder Swagger Petstore - OpenAPI 3.0 in de API-lijst. U ziet nu twee API's: Origineel en v1:

Notitie

Als u een versie toevoegt aan een niet-geversiede API, wordt er ook automatisch een oorspronkelijke versie gemaakt. Deze versie reageert op de standaard-URL. De oorspronkelijke versie zorgt ervoor dat aanroepen van bestaande bellers nog steeds werken nadat de versie is toegevoegd. Als u een nieuwe API maakt met versies die aan het begin zijn ingeschakeld, wordt er geen origineel gemaakt.

Een versie bewerken

Nadat u de versie hebt toegevoegd, kunt u deze bewerken en configureren als een API die gescheiden is van het origineel. Wijzigingen in de ene versie hebben geen invloed op een andere versie (bijvoorbeeld als u API-bewerkingen toevoegt of verwijdert of de OpenAPI-specificatie bewerkt). Zie Een API bewerken voor meer informatie.

Voeg de versie toe aan een product

Voor bellers om de nieuwe versie te kunnen zien, moet deze worden toegevoegd aan een product. Als u de versie nog niet aan een product hebt toegevoegd, kunt u dit op elk gewenst moment doen.

De versie toevoegen aan een product:

1. Blader in Azure Portal naar uw API Management-exemplaar.
2. Selecteer Producten onder API's in het linkerdeelvenster.
3. Selecteer het product en selecteer vervolgens API's in het linkerdeelvenster.
4. Selecteer +toevoegen.
5. Selecteer de API.
6. Klik op Selecteren.

Versiesets gebruiken

Wanneer u meerdere versies maakt, maakt Azure Portal een versieset, die een set versies voor één logische API vertegenwoordigt. Als u de naam selecteert van een API met meerdere versies, wordt in de portal de versieset weergegeven. U kunt de naam en beschrijving van een versieset aanpassen.

U kunt rechtstreeks communiceren met versiesets met behulp van de 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.

Als u al uw versiesets wilt zien, voert u de opdracht az apim api versionset list uit:

az apim api versionset list --resource-group <resource-group-name> \
    --service-name <API-Management-service-name> --output table

Wanneer azure Portal een versieset voor u maakt, wordt er een alfanumerieke naam toegewezen, die wordt weergegeven in de kolom Naam van de lijst. Gebruik deze naam in andere Azure CLI-opdrachten.

Voer de opdracht az apim api versionset show uit om details over een versieset weer te geven:

az apim api versionset show --resource-group <resource-group-name> \
    --service-name <API-Management-service-name> --version-set-id <ID from the Name column>

Zie Versies in Azure API Management voor meer informatie over versiesets.

De versie weergeven in de ontwikkelaarsportal

Als u de ontwikkelaarsportal gebruikt, ziet u daar API-versies.

1. Selecteer de ontwikkelaarsportal boven aan het venster.
2. Selecteer API's en selecteer Swagger Petstore vervolgens.
3. U ziet een vervolgkeuzelijst met meerdere versies naast de API-naam.
4. Selecteer v1.
5. U ziet de Verzoek-URL van de eerste bewerking in de lijst. Het laat zien dat het API URL-pad v1 bevat.

Volgende stap

Ga naar de volgende tutorial.

De stijl van de pagina's van de ontwikkelaarsportal aanpassen