Zelfstudie: Meerdere versies van uw API publiceren
VAN TOEPASSING OP: Alle API Management-lagen
Er zijn tijden wanneer het niet praktisch is dat alle aanroepers voor uw API dezelfde versie gebruiken. Wanneer aanroepers willen upgraden naar een nieuwere versie willen ze een gemakkelijk te begrijpen benadering. Zoals wordt weergegeven in deze zelfstudie, is het mogelijk om meerdere versies in Azure API Management te bieden.
Zie Versies en revisies voor achtergrond.
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
- Blader door de portal voor ontwikkelaars om de versie te zien
Vereisten
- Leer de terminologie van Azure API Management.
- Lees de volgende snelstartgids: Een Azure API Management-exemplaar maken.
- Voltooi tevens de volgende zelfstudie: Uw eerste API importeren en publiceren.
Een nieuwe versie toevoegen
- Blader in Azure Portal naar uw API Management-exemplaar.
- Selecteer API's.
- Selecteer Swagger Petstore in de API-lijst.
- Selecteer het contextmenu (...) naast Swagger Petstore.
- Selecteer Versie toevoegen.
Tip
Versies kunnen ook ingeschakeld worden wanneer u een nieuwe API maakt. Selecteer Versie van deze API? in het scherm API toevoegen.
Kies een versiebeheerschema
In Azure API Management kiest u hoe oproepende functies de API-versie opgeven door een schema voor versiebeheer te selecteren: pad, header of querytekenreeks. In het volgende voorbeeld wordt pad gebruikt als schema voor versiebeheer.
Voer de waarden in uit de volgende tabel. Selecteer vervolgens Maken om uw versie te maken.
| Instelling | Weergegeven als | Beschrijving |
|---|---|---|
| Versie-id | v1 | Schema-specifieke indicator van de versie. Voor Pad, het achtervoegsel voor het URL-pad van de API. |
| Schema voor versiebeheer | Pad | De manier waarop oproepende functie de API-versie opgeven. Als de header - of querytekenreeks is geselecteerd, voert u een andere waarde in: de naam van de header- of querytekenreeksparameter. Er wordt een gebruiksvoorbeeld weergegeven. |
| Volledige API-versienaam | swagger-petstore-v1 | Unieke naam in uw API Management-exemplaar. Omdat een versie een nieuwe API is, gebaseerd op de revisie van een API, is deze instelling de naam van de nieuwe API. |
| PRODUCTEN | Onbeperkt (geleverd in bepaalde 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 nu weergegeven onder Swagger Petstore in de API-lijst. U ziet nu twee API's: Origineel en v1.
Notitie
Als u een versie aan een niet-samengestelde API toevoegt, wordt automatisch ook een Origineel gemaakt. Deze versie reageert op de standaard-URL. Een Originele versie maken zorgt ervoor dat eventuele bestaande aanroepfuncties niet worden onderbroken door het proces van het toevoegen van een versie. Als u een nieuwe API met versies maakt die aan het begin zijn ingeschakeld, wordt geen Origineel gemaakt.
Een versie bewerken
Nadat u de versie hebt toegevoegd, kunt u deze nu bewerken en configureren als een API die gescheiden is van een origineel. Wijzigingen in de ene versie hebben geen invloed op een andere versie. Voeg bijvoorbeeld API-bewerkingen toe of verwijder deze of bewerk de OpenAPI-specificatie. Zie Een API bewerken voor meer informatie.
Voeg de versie toe aan een product
Als aanroepers de nieuwe versie willen zien, moet deze worden toegevoegd aan een product. Als u de versie nog niet aan een product hebt toegevoegd, dan kunt u deze op elk gewenst moment toevoegen aan een product.
Bijvoorbeeld om de versie toe te voegen aan het Onbeperkt product:
- Blader in Azure Portal naar uw API Management-exemplaar.
- Selecteer Producten>Onbeperkt>API's>+ Toevoegen.
- Selecteer Swagger Petstore, versie v1.
- Klik op Selecteren.
Versiesets gebruiken
Wanneer u meerdere versies maakt, maakt Azure Portal een versieset, die een set versies voor één logische API vertegenwoordigt. Selecteer de naam van een API met meerdere versies. In Azure Portal wordt de versieset weergegeven. U kunt de naam en beschrijving van een virtuele set aanpassen.
U kunt rechtstreeks communiceren met versiesets met behulp van de 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.
Als u al uw versiesets wilt zien, voert u de opdracht az apim api versionset list uit:
az apim api versionset list --resource-group apim-hello-world-resource-group \
--service-name apim-hello-world --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 apim-hello-world-resource-group \
--service-name apim-hello-world --version-set-id 00000000000000000000000
Zie Versies in Azure API Management voor meer informatie over versiesets.
Blader door de portal voor ontwikkelaars om de versie te zien
Als u het ontwikkelaarsportaal heeft uitgeprobeerd, kunt u daar API-versies terugvinden.
- Selecteer ontwikkelaarsportal in het menu bovenaan.
- Selecteer API's en selecteer vervolgens Swagger Petstore.
- U ziet een vervolgkeuzelijst met meerdere versies naast de naam van de API.
- Selecteer v1.
- U ziet de Verzoek-URL van de eerste bewerking in de lijst. Het laat zien dat het API URL-pad v1 bevat.
Volgende stappen
In deze zelfstudie heeft u het volgende geleerd:
- Een nieuwe versie toevoegen aan een bestaande API
- Een versieschema kiezen
- Voeg de versie toe aan een product
- Blader door de portal voor ontwikkelaars om de versie te zien
Ga door naar de volgende zelfstudie: