Verze ve službě Azure API Management

PLATÍ PRO: Všechny úrovně služby API Management

Verze umožňují vývojářům prezentovat skupiny souvisejících rozhraní API. Verze můžete použít k bezpečnému zpracování zásadních změn v rozhraní API. Jakmile budou klienti připravení, můžou použít novou verzi rozhraní API, zatímco stávající klienti budou dál používat starší verzi. Verze se rozlišují prostřednictvím identifikátoru verze (což je libovolná hodnota řetězce, kterou zvolíte) a schéma správy verzí umožňuje klientům určit, kterou verzi rozhraní API chtějí použít. Tento článek popisuje, jak používat verze ve službě API Management.

Pro většinu účelů lze každou verzi rozhraní API považovat za vlastní nezávislé rozhraní API. Dvě různé verze rozhraní API můžou mít různé sady operací a různé zásady.

S verzemi můžete:

• Publikování více verzí rozhraní API najednou
• K rozlišení mezi verzemi použijte cestu, řetězec dotazu nebo hlavičku.
• Použijte libovolnou řetězcovou hodnotu pro identifikaci vaší verze. Může to být číslo, datum nebo název.
• Zobrazte verze rozhraní API seskupené na portálu pro vývojáře.
• Vytvořte novou verzi existujícího rozhraní API (bez verzí), aniž by to ovlivnilo stávající klienty.

Začněte s verzemi tím, že projdete ukázkou.

Schémata správy verzí

Různí vývojáři rozhraní API mají různé požadavky na správu verzí. Azure API Management nenadepisuje jediný přístup ke správě verzí, ale nabízí několik možností.

Verzování založené na cestě

Při použití schématu správy verzí cesty musí být identifikátor verze zahrnut do cesty URL pro všechny požadavky rozhraní API.

Například https://apis.contoso.com/products/v1 a https://apis.contoso.com/products/v2 mohou odkazovat na stejné products API, ale na verze v1 a v2.

Formát adresy URL požadavku rozhraní API při použití verzování založeného na cestě je https://{yourDomain}/{apiName}/{versionIdentifier}/{operationId}.

Verzování na základě hlaviček

Při použití schématu správy verzí hlaviček musí být identifikátor verze zahrnut do hlavičky požadavku HTTP pro všechny požadavky rozhraní API. Můžete zadat název hlavičky požadavku HTTP.

Můžete například vytvořit vlastní hlavičku s názvem Api-Versiona klienti mohou v hodnotě této hlavičky zadat v1 nebo v2.

Verzování založené na řetězcích dotazů

Při použití schématu správy verzí řetězce dotazu musí být identifikátor verze zahrnut do parametru řetězce dotazu pro všechny požadavky rozhraní API. Můžete zadat název parametru řetězce dotazu.

Formát adresy URL požadavku rozhraní API při použití správy verzí založených na řetězci dotazu je https://{yourDomain}/{apiName}/{operationId}?{queryStringParameterName}={versionIdentifier}.

Například https://apis.contoso.com/products?api-version=v1 a https://apis.contoso.com/products?api-version=v2 mohou odkazovat na stejné products API, ale na verze v1 a v2.

Poznámka:

Parametry dotazu nejsou povoleny ve vlastnosti servers specifikace OpenAPI. Pokud exportujete specifikaci OpenAPI z verze rozhraní API, řetězec dotazu se v adrese URL serveru nezobrazí.

Původní verze

Pokud přidáte verzi do rozhraní API bez verzí, vytvoří se automaticky Original verze a bude odpovídat na výchozí adresu URL bez zadaného identifikátoru verze. Tato Original verze zajišťuje, že proces přidání verze neovlivní všechny existující volající. Pokud vytvoříte nové rozhraní API od začátku s povolenými verzemi, verze Original se nevytvoří.

Jak se zobrazují verze

API Management udržuje prostředek označovaný jako sada verzí, který představuje sadu verzí pro jedno logické rozhraní API. Sada verzí obsahuje zobrazovaný název rozhraní API s verzí a schéma správy verzí, které se používá k směrování požadavků na zadané verze.

Každá verze rozhraní API se udržuje jako vlastní prostředek rozhraní API a je přidružená k sadě verzí. Sada verzí může obsahovat rozhraní API s různými operacemi nebo zásadami. Mezi verzemi v sadě můžete provádět významné změny.

Azure Portal pro vás vytvoří sady verzí. Název a popis sady verzí můžete změnit na webu Azure Portal.

Sada verzí se po odstranění konečné verze automaticky odstraní.

Sady verzí můžete zobrazit a spravovat přímo pomocí Azure CLI, Azure PowerShellu, šablon Resource Managerunebo rozhraní API Azure Resource Manageru.

Poznámka:

Všechny verze v sadě verzí mají stejné schéma správy verzí. Je založená na schématu správy verzí, které se používá při prvním přidání verze do rozhraní API.

Migrace neverzovaného rozhraní API na verzované rozhraní API

Když pomocí webu Azure Portal povolíte správu verzí ve stávajícím rozhraní API, provede se ve vašich prostředcích služby API Management následující změny:

• Vytvoří se nová sada verzí.
• Existující verze je udržována a nakonfigurována jako verze API Original. Rozhraní API je propojené se sadou verzí, ale identifikátor verze se nemusí zadávat.
• Nová verze se vytvoří jako nové rozhraní API a je propojená se sadou verzí. Pro přístup k novému rozhraní API se musí použít schéma a identifikátor správy verzí.

Verze a revize

Verze a revize představují odlišné funkce. Každá verze může mít více revizí, stejně jako rozhraní API bez verzí. Revize můžete používat bez použití verzí nebo naopak. Verze se obvykle používají k oddělení verzí rozhraní API, které mají zásadní změny, a revize se dají použít pro menší a nepřerušované změny rozhraní API.

Pokud zjistíte, že revize má zásadní změny, nebo pokud chcete formálně změnit revizi na beta/testovací verzi, můžete vytvořit verzi z revize. V Azure portálu vyberte Vytvořit verzi z této revize v místní nabídce revize (...) na kartě Revize.

Portál pro vývojáře

Portál pro vývojáře uvádí jednotlivé verze rozhraní API samostatně:

V podrobnostech rozhraní API můžete také zobrazit seznam všech verzí rozhraní API. Verze Original se zobrazí bez identifikátoru verze:

Návod

Abyste je mohli zobrazit na portálu pro vývojáře, musíte do produktu přidat verze rozhraní API.