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á řetězcová hodnota, kterou zvolíte) a schéma správy verzí umožňuje klientům určit, kterou verzi rozhraní API chtějí použít.

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í verzí použijte cestu, řetězec dotazu nebo hlavičku.
• Použijte libovolnou řetězcovou hodnotu, kterou chcete identifikovat, což může být číslo, datum nebo název.
• Zobrazte verze rozhraní API seskupené na portálu pro vývojáře.
• Vezměte existující (neverzivované) rozhraní API a vytvořte novou verzi bez přerušení stávajících klientů.

Začněte s verzemi podle našeho návodu.

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í.

Správa verzí na základě cesty

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.

Může například odkazovat na stejné products rozhraní API, https://apis.contoso.com/products/v1 https://apis.contoso.com/products/v2 ale na verze v1 a v2 v uvedeném pořadí.

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

Správa verzí 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 zadat v1 nebo v2 v hodnotě této hlavičky.

Správa verzí založených 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}.

Může například odkazovat na stejné products rozhraní API, https://apis.contoso.com/products?api-version=v1 https://apis.contoso.com/products?api-version=v2 ale na verze v1 a v2 v uvedeném pořadí.

Poznámka:

Parametry dotazu nejsou ve vlastnosti specifikace OpenAPI povolené servers . 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í, Original vytvoří se automaticky verze a odpoví na výchozí adresu URL bez zadaného identifikátoru verze. Tato Original verze zajišťuje, že proces přidání verze neporušil všechny existující volající. Pokud vytvoříte nové rozhraní API s povolenými verzemi na začátku, Original verze se nevytvoří.

Jak jsou reprezentovány verze

Azure 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, který je pak 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 Manageru nebo rozhraní API Azure Resource Manageru.

Poznámka:

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

Migrace rozhraní API bez verzí na rozhraní API s verzí

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í.
• Stávající verze se udržuje a konfiguruje jako Original verze rozhraní API. Rozhraní API je propojené se sadou verzí, ale nevyžaduje zadání identifikátoru verze.
• Nová verze se vytvoří jako nové rozhraní API a je propojená se sadou verzí. Toto nové rozhraní API musí být přístupné pomocí schématu a identifikátoru správy verzí.

Verze a revize

Verze a revize jsou 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 s zásadními změnami, zatímco revize se dají použít pro menší a nefunkční změny rozhraní API.

Pokud zjistíte, že vaš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. Na webu Azure Portal klikněte na Možnost Vytvořit verzi z 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ě.

Podrobnosti rozhraní API také zobrazují seznam všech verzí tohoto rozhraní API. Verze Original se zobrazí bez identifikátoru verze.

Tip

Verze rozhraní API je potřeba přidat do produktu, aby se zobrazovaly na portálu pro vývojáře.