Dela via

Versioner i Azure API Management

  • Artikel

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

Versioner gör att du kan presentera grupper med relaterade API:er för dina utvecklare. Du kan använda versioner för att hantera icke-bakåtkompatibla ändringar 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 särskiljs genom en versionsidentifierare (vilket är ett strängvärde som du väljer) och ett versionshanteringsschema gör att klienterna kan identifiera vilken version av ett API de vill använda.

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 valfritt strängvärde som du vill identifiera din version, vilket kan vara ett tal, ett datum eller ett namn.
  • Visa dina API-versioner grupperade tillsammans på utvecklarportalen.
  • Ta ett befintligt (icke-versionsbaserat) API och skapa en ny version av det utan att bryta befintliga klienter.

Kom igång med versioner genom att följa vår genomgång.

Versionsscheman

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 respektive 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 respektive v2 .

Kommentar

Frågeparametrar tillåts inte i egenskapen servers för en OpenAPI-specifikation. Om du exporterar en OpenAPI-specifikation från en API-version visas inte en frågesträng i server-URL:en.

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 ser till att alla befintliga anropare inte bryts av processen att lägga till en version. Om du skapar ett nytt API med versioner aktiverade i början Original skapas ingen version.

Hur versioner representeras

Azure 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:et 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, som sedan associeras 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-mallar eller Azure Resource Manager-API:et.

Kommentar

Alla versioner i en versionsuppsättning har samma versionsschema, baserat på versionsschemat som används när du först lägger till en version i ett 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 API-versionOriginal. API:et är länkat till versionsuppsättningen men kräver inte att en versionsidentifierare anges.
  • Den nya versionen skapas som ett nytt API och är länkad till versionsuppsättningen. Det nya API:et måste nås med versionsschemat och identifieraren.

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 med icke-bakåtkompatibla ändringar, medan revisioner kan användas för mindre och icke-icke-bakåtkompatibla ändringar i ett API.

Om du upptäcker att revisionen har icke-bakåtkompatibla ändringar, eller om du formellt vill omvandla revisionen till en beta-/testversion, kan du skapa en version från en revision. I Azure-portalen klickar du på "Skapa version från revision" på snabbmenyn revision på fliken Revisioner.

Utvecklarportalen

Utvecklarportalen visar varje version av ett API separat.

UTVECKLARportalen för API Management visar en lista över versions-API:er

Information om ett API visar också en lista över alla versioner av api:et. En Original version visas utan versionsidentifierare.

Utvecklarportalen för API Management visar information om ett API och en lista över versioner för api:et

Dricks

API-versioner måste läggas till i en produkt innan de visas på utvecklarportalen.