Versies in Azure API Management

  • Artikel

VAN TOEPASSING OP: Alle API Management-lagen

Met versies kunt u groepen gerelateerde API's presenteren aan uw ontwikkelaars. U kunt versies gebruiken om wijzigingen die fouten veroorzaken in uw API veilig af te handelen. Clients kunnen ervoor kiezen om uw nieuwe API-versie te gebruiken wanneer ze klaar zijn, terwijl bestaande clients een oudere versie blijven gebruiken. Versies worden onderscheiden door middel van een versie-id (een willekeurige tekenreekswaarde die u kiest) en met een versiebeheerschema kunnen clients bepalen welke versie van een API ze willen gebruiken.

Voor de meeste doeleinden kan elke API-versie worden beschouwd als een eigen onafhankelijke API. Twee verschillende API-versies kunnen verschillende sets bewerkingen en verschillende beleidsregels hebben.

Met versies kunt u het volgende doen:

  • Meerdere versies van uw API tegelijk publiceren.
  • Gebruik een pad, querytekenreeks of header om onderscheid te maken tussen versies.
  • Gebruik een tekenreekswaarde die u wilt identificeren voor uw versie. Dit kan een getal, een datum of een naam zijn.
  • Geef uw API-versies weer die zijn gegroepeerd in de ontwikkelaarsportal.
  • Neem een bestaande API (niet-versiebeheerde) en maak een nieuwe versie ervan zonder dat bestaande clients worden onderbroken.

Ga aan de slag met versies door onze procedure te volgen.

Versiebeheerschema's

Verschillende API-ontwikkelaars hebben verschillende vereisten voor versiebeheer. Azure API Management schrijft geen enkele benadering van versiebeheer voor, maar biedt in plaats daarvan verschillende opties.

Versiebeheer op basis van pad

Wanneer het padversiebeheerschema wordt gebruikt, moet de versie-id worden opgenomen in het URL-pad voor eventuele API-aanvragen.

En kan bijvoorbeeld https://apis.contoso.com/products/v1https://apis.contoso.com/products/v2 verwijzen naar dezelfde products API, maar naar versies v1 en v2 respectievelijk.

De indeling van een API-aanvraag-URL bij het gebruik van versiebeheer op basis van een pad is: https://{yourDomain}/{apiName}/{versionIdentifier}/{operationId}.

Versiebeheer op basis van headers

Wanneer het versiebeheerschema voor headers wordt gebruikt, moet de versie-id worden opgenomen in een HTTP-aanvraagheader voor API-aanvragen. U kunt de naam van de HTTP-aanvraagheader opgeven.

U kunt bijvoorbeeld een aangepaste header maken met de naam Api-Versionen clients kunnen de waarde van deze header opgeven v1 of v2 in de waarde van deze header.

Versiebeheer op basis van queryreeksen

Wanneer het versiebeheerschema voor queryreeksen wordt gebruikt, moet de versie-id worden opgenomen in een querytekenreeksparameter voor API-aanvragen. U kunt de naam van de querytekenreeksparameter opgeven.

De indeling van een API-aanvraag-URL bij het gebruik van versiebeheer op basis van queryreeksen is: https://{yourDomain}/{apiName}/{operationId}?{queryStringParameterName}={versionIdentifier}.

En kan bijvoorbeeld https://apis.contoso.com/products?api-version=v1https://apis.contoso.com/products?api-version=v2 verwijzen naar dezelfde products API, maar naar versies v1 en v2 respectievelijk.

Notitie

Queryparameters zijn niet toegestaan in de servers eigenschap van een OpenAPI-specificatie. Als u een OpenAPI-specificatie exporteert vanuit een API-versie, wordt er geen querytekenreeks weergegeven in de server-URL.

Oorspronkelijke versies

Als u een versie toevoegt aan een niet-geversiede API, wordt er automatisch een Original versie gemaakt en wordt er een antwoord uitgevoerd op de standaard-URL, zonder dat er een versie-id is opgegeven. De Original versie zorgt ervoor dat bestaande bellers niet worden verbroken door het proces voor het toevoegen van een versie. Als u een nieuwe API maakt met versies die aan het begin zijn ingeschakeld, Original wordt er geen versie gemaakt.

Hoe versies worden weergegeven

Azure API Management onderhoudt een resource met de naam een versieset, die een set versies voor één logische API vertegenwoordigt. Een versieset bevat de weergavenaam van de versie-API en het versiebeheerschema dat wordt gebruikt voor het doorsturen van aanvragen naar opgegeven versies.

Elke versie van een API wordt onderhouden als een eigen API-resource, die vervolgens wordt gekoppeld aan een versieset. Een versieset kan API's bevatten met verschillende bewerkingen of beleidsregels. Mogelijk kunt u belangrijke wijzigingen aanbrengen tussen versies in een set.

In Azure Portal worden versiesets voor u gemaakt. U kunt de naam en beschrijving voor een versieset wijzigen in Azure Portal.

Een versieset wordt automatisch verwijderd wanneer de definitieve versie wordt verwijderd.

U kunt versiesets rechtstreeks weergeven en beheren met behulp van Azure CLI, Azure PowerShell, Resource Manager-sjablonen of de Azure Resource Manager-API.

Notitie

Alle versies in een versieset hebben hetzelfde versiebeheerschema, op basis van het versiebeheerschema dat wordt gebruikt wanneer u voor het eerst een versie aan een API toevoegt.

Een niet-geversiede API migreren naar een geversiede API

Wanneer u Azure Portal gebruikt om versiebeheer in te schakelen voor een bestaande API, worden de volgende wijzigingen aangebracht in uw API Management-resources:

  • Er wordt een nieuwe versieset gemaakt.
  • De bestaande versie wordt onderhouden en geconfigureerd als de Original API-versie. De API is gekoppeld aan de versieset, maar vereist geen versie-id die moet worden opgegeven.
  • De nieuwe versie wordt gemaakt als een nieuwe API en is gekoppeld aan de versieset. Deze nieuwe API moet worden geopend met behulp van het versiebeheerschema en de id.

Versies en revisies

Versies en revisies zijn verschillende functies. Elke versie kan meerdere revisies hebben, net als een niet-geversiede API. U kunt revisies gebruiken zonder versies te gebruiken of andersom. Normaal gesproken worden versies gebruikt om API-versies te scheiden met belangrijke wijzigingen, terwijl revisies kunnen worden gebruikt voor kleine en niet-belangrijke wijzigingen in een API.

Als u merkt dat uw revisie wijzigingen bevat die fouten veroorzaken of als u de revisie formeel wilt omzetten in een bèta-/testversie, kunt u een versie maken op basis van een revisie. Klik in Azure Portal op 'Versie maken op basis van revisie' in het contextmenu revisie op het tabblad Revisies.

ontwikkelaarsportal

In de ontwikkelaarsportal wordt elke versie van een API afzonderlijk weergegeven.

API Management-ontwikkelaarsportal met een lijst met api's met versiebeheer

De details van een API bevatten ook een lijst met alle versies van die API. Er Original wordt een versie weergegeven zonder versie-id.

API Management-ontwikkelaarsportal met de details van een API en een lijst met versies voor die API

Tip

API-versies moeten worden toegevoegd aan een product voordat ze zichtbaar zijn in de ontwikkelaarsportal.