Implementace operace verzování

Článek
06/23/2023

Vlastní konektory pro Azure Logic Apps, Microsoft Power Automate nebo Microsoft Power Apps musí poskytovat soubor specifikace OpenAPI. Tato specifikace OpenAPI definuje jednotlivé vstupní body označované jako operace. Každá operace má jedinečnou hodnotu operationId a jedinečnou kombinaci hodnot urlPath a HttpVerb.

{
    "/items": {
        "get": {
            "summary": "Get rows",
            "description": "This operation gets a list of items.",
            "operationId": "GetItems"
        },
        "post": {
            "summary": "Insert row",
            "description": "This operation inserts an item.",
            "operationId": "PostItem"
        }
    }
}

Tyto operace se v průběhu času můžou rozšiřovat a měnit přidáváním nebo rozšiřováním funkcí. Některé změny jsou pouze doplňující a nemusí narušit existující kontrakt mezi klienty a servery. Do této kategorie patří například přidání nových parametrů, vracení většího množství dat nebo povolení flexibilnějších vstupů.

Řada změn však může ve skutečnosti narušit kontrakt popsaný ve specifikaci OpenAPI. Do kategorie změn způsobujících chybu patří odebrání parametrů, ukončení podpory určitých vstupů nebo změna smyslu a chování vstupu, výstupu nebo samotné operace.

Pokud chcete bezpečně rozvíjet rozhraní API, je důležité řídit se vzorem, kterým se můžou řídit i klienti. Rozhraní API zodpovídá za udržování zpětné kompatibility, komunikaci záměru a popis atributů správy verzí. Klient zodpovídá za zobrazení nebo skrytí zastaralých operací, operací, jejichž platnost vypršela, nebo operací, pro které můžou být k dispozici novější verze. Tímto způsobem se operace můžou v průběhu času zvětšovat a vyvíjet, aniž by to způsobilo přílišné oslabení aplikací, které se na ně spoléhají.

Objekt Annotation rozhraní API

OpenAPI nenabízí integrovanou podporu provozní správy verzí. Velká část práce k dosažení našeho cíle se provádí prostřednictvím objektu x-ms-api-annotation, který se používá v globálním rozsahu i v rozsahu operace. Globální objekt obsahuje vlastnosti, které platí pro rozhraní API jako celek:

{
    "x-ms-api-annotation": {
        "status": "Preview"
    }
}

Vlastnost	Hodnoty	Výchozí	Popis
status	`"Preview"` `"Production"`	`"Preview"`	Stav rozhraní API jako celku — začíná na hodnotě Preview a v závislosti na využití a stabilitě přechází na hodnotu Production.

V rozsahu operace tento objekt obsahuje podrobnější vlastnosti. Pro vývojový proces správy verzí platí a podílí se na něm i další vlastnosti mimo tento objekt:

{
    "deprecated": true,
    "x-ms-api-annotation": {
        "status": "Production",
        "family": "MyOperation",
        "revision": 2
    }
}

Vlastnost	Hodnoty	Výchozí	Popis
deprecated	`null` `false` `true`	`false`	Určuje, jestli je operace zastaralá.
x-ms-visibility	`null` `""` `"Important"` `"Advanced"` `"Internal"`	`""`	Zamýšlená viditelnost a význačnost této operace, kde hodnota `null` nebo `""` značí normální stav
stav	`"Preview"` `"Production"`	`"Production"`	Stav operace — tento stav se může lišit od stavu samotného rozhraní API, ale pokud není zadaný, zdědí se ze stavu rozhraní API nevyšší úrovně.
family	{běžný název operace}	operationName	Název, který se použije pro všechny revize této operace
revision	číselná hodnota (1, 2, 3...)	`1`	Revize zadané řady operací
expires	Datum ISO8601	(žádné)	Volitelné informace o plánovaném konci podpory pro klienta

Jakmile přestane být žádoucí, aby klienti používali tuto operaci, je možné nastavit vlastnost deprecated na hodnotu true. Tato vlastnost existuje ve specifikaci pevných polí OpenAPI.

Vlastnost visibility je indikátorem plánované relativní význačnosti operace. Důležitá ("Important") viditelnost značí, že by se operace měla nacházet na předním místě seznamu a zobrazovat se přednostně. Výchozí viditelnost je normální (označovaná hodnotou null nebo prázdným řetězcem ""), která znamená, že se operace objeví v seznamu, a to pravděpodobně až po důležitých operacích. Rozšířená ("Advanced") viditelnost značí, že se operace může nacházet ve spodní části seznamu nebo že zpočátku dokonce může být skrytá za ovládacím prvkem pro rozbalení. Rozšířené operace můžou být obtížněji použitelné, méně oblíbené nebo můžou mít užší použití. Interní viditelnost ("Internal") značí, že by operace neměla být přístupná uživatelům a měla by se používat pouze interně. Interní operace jsou užitečné a cenné v rámci programu, ale nejsou určené pro koncové uživatele. Jako interní je možné operace označit také za účelem jejich skrytí ve všech typech uživatelského rozhraní v průběhu vyřazování z provozu, aniž by došlo k jejich skutečnému odebrání z rozhraní API, což by jinak způsobilo zásadní změnu.

Vlastnost status značí stabilitu rozhraní API nebo operace. Hodnota "Preview" značí, že jsou operace nebo rozhraní API nové a potenciálně neověřené. Pro produkční systémy je hodnota Preview indikátorem, že by při přijímání závislosti měly postupovat opatrně. Jakmile se operace nebo rozhraní API více rozšíří a prokáží, že splňují standardy spolehlivosti, úspěšnosti a škálovatelnosti, může se jejich stav záměrně upgradovat na hodnotu "Production".

Pro operace, které chtějí získat stav "Production", obecně platí následující požadavky na metriky:

80% úspěšnost po dobu tří týdnů
- Definuje se jako procento kódů odpovědí HTTP v rozsahu 2xx.
99,9% spolehlivost po dobu tří týdnů
- Definuje se jako procento kódů odpovědí HTTP mimo rozsah 5xx (kódy odpovědí 502, 504 a 520 se nepočítají).

Vlastnost family označuje vztah mezi operacemi, které jsou koncepčně stejné, ale jsou to různé revize, mezi kterými potenciálně můžou být změny způsobující chyby. Více operací, které se mají považovat za revize, sdílí stejný název řady následovaný jedinečným číslem revize.

Vlastnost revision označuje pořadí operace v rámci řady operací. Každá operace v rámci řady má hodnotu revision, což je celočíselný index určující pořadí. Revize s prázdnou hodnotou revision se považuje za revizi č. 1. Pokud jsou k dispozici novější revize operace, klienti by je měli zobrazovat přednostně a záměrně je doporučovat, ale stále by měli umožňovat výběr starších revizí, které ještě nejsou zastaralé.

Vlastnost expires je volitelná a označuje potenciální termín konce životnosti, kdy skončí záruka podpory operace. Tato vlastnost by se měla nastavovat pouze pro zastaralé operace a v současné době se v žádném rozhraní neprojevuje.

Doba života operace

Operace mají předvídatelnou dobu života, kterou je možné znázornit na příkladu.

Výchozí bod

Operace zpočátku nemusí nutně uvádět jakékoli informace o revizích. U takových operací se použijí výchozí hodnoty, a proto se považují za revizi č. 1 v rámci řady, jejíž název odpovídá hodnotě operationId.

{
    "/{list}/items": {
        "get": {
            "summary": "Get rows",
            "description": "This operation gets a list of items.",
            "operationId": "GetItems"
        }
    }
}

Tato definice odpovídá následující explicitnější definici:

{
    "/{list}/items": {
        "get": {
            "summary": "Get rows",
            "description": "This operation gets a list of items.",
            "operationId": "GetItems",
            "deprecated": false,
            "x-ms-api-annotation": {
                "status": "Production",
                "family": "GetItems",
                "revision": 1
            }
        }
    }
}

Inicializace operace

Rozvoj rozhraní API většinou spočívá v přidání operace. Například nových metod nebo nových revizí stávajících metod. Pokud chcete bezpečně inicializovat novou revizi, upravte specifikaci OpenAPI následujícím způsobem:

{
    "/{list}/items": {
        "get": {
            "summary": "Get rows (V1 - downplayed)",
            "description": "This operation gets a list of items.",
            "operationId": "GetItems",
            "deprecated": false,
            "x-ms-visibility": "advanced",
            "x-ms-api-annotation": {
                "status": "Production",
                "family": "GetItems",
                "revision": 1
            }
        }
    }
    "/v2/{list}/items": {
        "get": {
            "summary": "Get rows (V2 - new hotness)",
            "description": "This operation gets a list of items.",
            "operationId": "GetItems_V2",
            "deprecated": false,
            "x-ms-api-annotation": {
                "status": "Preview",
                "family": "GetItems",
                "revision": 2
            }
        }
    }
}

Důležité

Všimněte si, že operace GetItems V2 má jedinečnou hodnotu operationId a zpočátku je u ní uvedený stav Preview. Všimněte si také, že u operace GetItems V1 je teď uvedená rozšířená viditelnost, takže se nebude zobrazovat přednostně.

Vyřazení operace

Vstupní body V1 někdy můžou existovat po neomezenou dobu, pokud jsou stále užitečné a není žádný závažný důvod k jejich vyřazení. Řada vstupních bodů V2 však vstupní bod V1 záměrně nahrazuje. Aby to bylo možné bezpečně provést, do původní operace musí přestat proudit jakýkoli provoz. Jakmile to telemetrie potvrdí, je možné provést následující změnu:

{
    "/{list}/items": {
        "get": {
            "summary": "Get rows (deprecated)",
            "description": "This operation gets a list of items.",
            "operationId": "GetItems",
            "deprecated": true,
            "x-ms-api-annotation": {
                "status": "Production",
                "family": "GetItems",
                "revision": 1
            }
        }
    }
    "/v2/{list}/items": {
        "get": {
            "summary": "Get rows",
            "description": "This operation gets a list of items.",
            "operationId": "GetItems_V2",
            "deprecated": false,
            "x-ms-api-annotation": {
                "status": "Production",
                "family": "GetItems",
                "revision": 2
            }
        }
    }
}

Důležité

Všimněte si, že operace GetItems V1 je teď označená jako zastaralá. Toto je poslední změna při vyřazování operací z provozu. Operace GetItems V2 teď zcela nahradila operaci GetItems V1.

K čemu to je?

Existuje řada důvodů, proč dodržovat provozní správu verzí. Primárním účelem je zajistit, aby klienti jako Azure Logic Apps a Power Automate dál fungovali správně poté, co uživatelé do svých toků dat integrují operace konektorů. Operace by se měly označit verzí pomocí výše uvedené metody vždy, když dojde k následujícímu:

Přidání nové revize operace
Přidání nebo odebrání parametrů ve stávající operaci
Výrazná změna vstupu nebo výstupu stávající operace

V kostce

V některých případech se můžete bez správy verzí obejít — měli byste přitom však být opatrní a provést celou řadu testů, abyste se ujistili, že jste nepřehlédli okrajové případy, kdy u uživatelů může dojít k neočekávaným chybám. Tady je krátký seznam případů, kdy se bez správy verzí můžete obejít:

Přidání nové operace.

Tím nedojde k chybám u stávajících klientů.
Přidání nového volitelného parametru do stávající operace.

Tím nedojde k chybám u stávajících volání, ale je potřeba to pečlivě zvážit.
Mírná změna chování stávající operace.

V závislosti na povaze změny a na tom, co uživatelé potřebují, tím nemusí dojít k chybám u stávajících volajících. Tento případ je nejnebezpečnější, protože výrazný rozdíl v příjmu vstupů, generování výstupů, časování nebo zpracování může ovlivnit chování operace nejrůznějšími způsoby a proto je velmi obtížné určit rizika, která s sebou změna nese.

Doporučujeme vždy postupovat nadmíru opatrně a při každé netriviální změně rozhraní API iterovat revizi.

Poskytnutí názorů

Velmi si vážíme vašich názorů na problémy s naší platformou konektorů nebo nových nápadů na funkce. Chcete-li poskytnout zpětnou vazbu, přejděte do části Odeslat problémy nebo získat pomoc s konektory a vyberte typ zpětné vazby.

Sdílet prostřednictvím