Versioner i Azure API Management

GÄLLER FÖR: Alla API Management-nivåer

Med versioner kan du presentera grupper med relaterade API:er för dina utvecklare. Du kan använda versioner för att hantera förändringar som bryter kompatibilitet i ditt API på ett säkert sätt. Klienter kan välja att använda din nya API-version när de är redo, medan befintliga klienter fortsätter att använda en äldre version. Versioner skiljer sig åt via en versionsidentifierare (vilket är valfritt strängvärde du väljer), och ett versionsschema gör att klienter kan identifiera vilken version av ett API de vill använda. Den här artikeln beskriver hur du använder versioner i API Management.

I de flesta fall kan varje API-version betraktas som ett eget oberoende API. Två olika API-versioner kan ha olika uppsättningar av åtgärder och olika principer.

Med versioner kan du:

• Publicera flera versioner av api:et samtidigt.
• Använd en sökväg, frågesträng eller rubrik för att skilja mellan olika versioner.
• Använd alla strängvärden som du vill identifiera din version. Det kan vara ett tal, ett datum eller ett namn.
• Visa dina API-versioner grupperade tillsammans på utvecklarportalen.
• Skapa en ny version av ett befintligt (icke-versionsbaserat) API utan att påverka befintliga klienter.

Kom igång med versioner genom att slutföra en genomgång.

Versionshanteringsscheman

Olika API-utvecklare har olika krav för versionshantering. Azure API Management föreskriver inte en enda metod för versionshantering, utan innehåller i stället flera alternativ.

Sökvägsbaserad versionshantering

När sökvägsversionsschemat används måste versionsidentifieraren inkluderas i URL-sökvägen för eventuella API-begäranden.

Till exempel https://apis.contoso.com/products/v1 och https://apis.contoso.com/products/v2 kan referera till samma products API men till versioner v1 och v2.

Formatet för en URL för API-begäran när du använder sökvägsbaserad versionshantering är https://{yourDomain}/{apiName}/{versionIdentifier}/{operationId}.

Rubrikbaserad versionshantering

När versionsschemat för sidhuvuden används måste versionsidentifieraren inkluderas i ett HTTP-begärandehuvud för alla API-begäranden. Du kan ange namnet på HTTP-begärandehuvudet.

Du kan till exempel skapa ett anpassat huvud med namnet Api-Version, och klienter kan ange v1 eller v2 i värdet för det här huvudet.

Fråga efter strängbaserad versionshantering

När versionsschemat för frågesträngar används måste versionsidentifieraren inkluderas i en frågesträngsparameter för eventuella API-begäranden. Du kan ange namnet på frågesträngsparametern.

Formatet för en URL för API-begäran när du använder frågesträngsbaserad versionshantering är https://{yourDomain}/{apiName}/{operationId}?{queryStringParameterName}={versionIdentifier}.

Till exempel https://apis.contoso.com/products?api-version=v1 och https://apis.contoso.com/products?api-version=v2 kan referera till samma products API men till versioner v1 och v2.

Originalversioner

Om du lägger till en version i ett icke-versions-API skapas en Original version automatiskt och svarar på standard-URL:en utan att någon versionsidentifierare har angetts. Versionen Original säkerställer att befintliga anropare inte påverkas av processen med att lägga till en version. Om du skapar ett nytt API med versioner aktiverade i början skapas inte en Original version.

Hur versioner representeras

API Management underhåller en resurs som kallas en versionsuppsättning, som representerar en uppsättning versioner för ett enda logiskt API. En versionsuppsättning innehåller visningsnamnet för det versionshanterade API och versionsschemat som används för att dirigera begäranden till angivna versioner.

Varje version av ett API underhålls som en egen API-resurs och är associerad med en versionsuppsättning. En versionsuppsättning kan innehålla API:er med olika åtgärder eller principer. Du kan göra betydande ändringar mellan versioner i en uppsättning.

Azure-portalen skapar versionsuppsättningar åt dig. Du kan ändra namn och beskrivning för en version som angetts i Azure-portalen.

En versionsuppsättning tas bort automatiskt när den slutliga versionen tas bort.

Du kan visa och hantera versionsuppsättningar direkt med hjälp av Azure CLI, Azure PowerShell, Resource Manager-mallareller Azure Resource Manager API.

Migrera ett icke-versions-API till ett versions-API

När du använder Azure-portalen för att aktivera versionshantering i ett befintligt API görs följande ändringar i dina API Management-resurser:

• En ny versionsuppsättning skapas.
• Den befintliga versionen underhålls och konfigureras som Original API-version. API:et är länkat till versionsuppsättningen, men en versionsidentifierare behöver inte anges.
• Den nya versionen skapas som ett nytt API och är länkad till versionsuppsättningen. Ett versionsschema och en identifierare måste användas för att få åtkomst till det nya API:et.

Versioner och revisioner

Versioner och revisioner är distinkta funktioner. Varje version kan ha flera revisioner, precis som ett icke-versions-API. Du kan använda revisioner utan att använda versioner eller tvärtom. Vanligtvis används versioner för att separera API-versioner som har större förändringar, medan revisioner kan användas för mindre och oförändrade ändringar i ett API.

Om du upptäcker att revisionen har ändringar som bryter kompatibilitet, eller om du på ett formellt sätt vill omvandla revisionen till en beta-/testversion, kan du skapa en version från en revision. I Azure-portalen väljer du Skapa version från den här revisionen på snabbmenyn för revision (...) på fliken Revisioner .

Utvecklarportalen

Utvecklarportalen visar varje version av ett API separat:

I informationen för ett API kan du också se en lista över alla versioner av API:et. En Original version visas utan versionsidentifierare: