Versies in Azure API Management

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 via een versie-id (dit is een tekenreekswaarde die u kiest) en met een versiebeheerschema kunnen clients bepalen welke versie van een API ze willen gebruiken. In dit artikel wordt beschreven hoe u versies gebruikt in API Management.

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 willekeurige tekenreekswaarde om uw versie te identificeren. Dit kan een getal, een datum of een naam zijn.
• Geef uw API-versies weer die zijn gegroepeerd in de ontwikkelaarsportal.
• Maak een nieuwe versie van een bestaande (niet-geversiede) API zonder dat dit van invloed is op bestaande clients.

Ga aan de slag met versies door een handleiding te voltooien.

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.

De indeling van een API-aanvraag-URL wanneer u versiebeheer op basis van een pad gebruikt, 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 Api-Version, en clients kunnen v1 of v2 specificeren 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 wanneer u versiebeheer op basis van queryreeksen gebruikt, 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.

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 eventuele bestaande bellers niet worden beïnvloed door het proces voor het toevoegen van een versie. Als u vanaf het begin een nieuwe API maakt met ingeschakelde versies, wordt er geen Original versie gemaakt.

Hoe versies worden weergegeven

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 en is 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.

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 er hoeft geen versie-id te worden opgegeven.
• De nieuwe versie wordt gemaakt als een nieuwe API en is gekoppeld aan de versieset. Er moet een versiebeheerschema en -id worden gebruikt voor toegang tot de nieuwe API.

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 die ingrijpende wijzigingen bevatten, en kunnen revisies worden gebruikt voor kleine en niet-ingrijpende 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. Selecteer in Azure Portal Versie maken in deze revisie in het contextmenu (...) op het tabblad Revisies .

ontwikkelaarsportal

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

In de details van een API ziet u ook een lijst met alle versies van de API. Er Original wordt een versie weergegeven zonder versie-id: