Verziószámozási műveletek megvalósítása

Cikk
06/27/2024

Egyéni összekötők Azure Logic Apps, Microsoft Power Automate, vagy Microsoft Power Apps specifikációs OpenAPI fájlt kell biztosítaniuk. Ez a OpenAPI specifikáció egyes belépési pontokat, más néven műveleteket határoz meg. Minden műveletnek egyedi operationId és egyedi urlPath kombinációja HttpVerb van.

{
    "/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"
        }
    }
}

Ezek a műveletek az idővel növekedhetnek és változhatnak a funkciók hozzáadásakor vagy bővítésekor. Bizonyos változások csupán additívak, és nem feltétlenül bontják fel az ügyfelek és a kiszolgálók közötti szerződést. Az új paraméterek hozzáadása, a további adatok visszaadása vagy a rugalmasabb bemenetek engedélyezése ebbe a kategóriába tartozik.

Számos módosítás azonban ténylegesen megszakíthatja a OpenAPI specifikációban leírt szerződést. A paraméterek eltávolítása, egyes bemenetek támogatásának megszüntetése, illetve a bemenet, a kimenet vagy a művelet jelentésének és viselkedésének módosítása a felbontást eredményező kategóriába tartozik.

Az API-k biztonságos fejlesztése érdekében fontos, hogy az ügyfelek értsék a követett mintát. Az API feladata a visszamenőleges kompatibilitás fenntartása, a szándékok közlése és a verziószámozási attribútumok leírása. Az ügyfél felelőssége, hogy megjelenítse vagy elrejtse az elavult, lejárt vagy az újabb verziókkal rendelkező műveleteket. Így a műveletek idővel anélkül növekedhetnek és fejlődhetnek, hogy indokolatlanul törékennyé tennék a rájuk támaszkodó alkalmazásokat.

API annotáció

OpenAPI nem támogatja az operatív verziószámozást. A cél eléréséhez a munka nagy része az x-ms-api-annotation objektumon keresztül történik, amely a globális hatókörre és a műveleti hatókörre is alkalmazható. A globális objektum olyan tulajdonságokat tartalmaz, amelyek az API egészére vonatkoznak:

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

Tulajdonság	Értékek	Default	Description
állapot	`"Preview"` `"Production"`	`"Preview"`	Az API egészének állapota – először előzetes verzióban, majd éles környezetben a használat és a stabilitás alapján

A működési hatókörben ez az objektum részletesebb tulajdonságokat tartalmaz. Az objektumon kívül további tulajdonságok is találhatók, amelyek érvényesek és részt vesznek a verziószámozás evolúciós folyamatában:

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

Tulajdonság	Értékek	Default	Ismertetés
elavult	`null` `false` `true`	`false`	Jelzi, hogy a művelet elavult-e
x-ms-visibility	`null` `""` `"Important"` `"Advanced"` `"Internal"`	`""`	A művelet kívánt láthatósága és jelentősége, ahol a `null` vagy a `""` Normál állapotot jelez
állapot	`"Preview"` `"Production"`	`"Production"`	A művelet állapota – ez eltérő lehet magától az API állapotától, de ha nincs megadva, a rendszer örökli a legfelső szintű API-állapotot
család	{gyakori műveletnév}	operationName	Egy név, amely a művelet minden változatára vonatkozik
javítás	numerikus (1,2,3…)	`1`	A megadott operatív család változata
lejárat	ISO8601 dátuma	(nincs)	Opcionális tipp az ügyfél számára a támogatás végének előrejelzésére

Az elavult beállítás akkor állítható be, true ha már nem kívánatos, hogy az ügyfelek használják ezt a műveletet. Ez a OpenAPI tulajdonság a Rögzített mezők specifikációban található.

A Láthatóság a művelet szándékolt relatív jelentőségének jelzője. Az "Important" láthatóság azt jelzi, hogy a műveletnek a lista tetején kell lennie, jól látható helyen. A normál láthatóság (amelyet null vagy üres karakterlánc "" jelez) az alapértelmezett, és azt jelenti, hogy a művelet megjelenik a listában, valószínűleg a Fontos műveletek után. Az "Advanced" (speciális) láthatóság azt jelzi, hogy a műveletnek a lista alján kell lennie, vagy elrejtve egy kibontható vezérlőelem mögé. Előfordulhat, hogy a speciális műveletek nehezebben használhatók, kevésbé népszerűek vagy szűkebben alkalmazhatók. A "Internal" láthatóság azt jelzi, hogy a műveletet nem szabad elérhetővé tenni a felhasználók számára, és csak belsőleg szabad használni. A belső műveletek programozott módon hasznosak és értékesek, de nem végfelhasználók számára készültek. A belső műveletek is meg vannak jelölve ilyenként, hogy elrejtsék őket bármilyen felhasználói felületről az elalasztási folyamat során anélkül, hogy ténylegesen eltávolítanák őket az API-ból, ami egyébként feltörési változást okozna.

Az Állapot az API vagy a művelet stabilitását jelzi. A "Preview" (előzetes verzió) azt jelzi, hogy a művelet vagy az API új, és még nem bizonyított a használatban. Az előzetes verzió azt jelzi, hogy az éles rendszereknek óvatosan kell eljárniuk a függőség feltételezésekor. Amint a művelet vagy az API jobban elterjedt, és bizonyosodott, hogy megfelel a megbízhatóság, a sikerességi arány és a méretezhetőség standardjainak, szándékosan "Production" (éles) állapotra frissíthető.

A következő metrikai követelmények általánosságban vonatkoznak a "Production" (éles) állapotot elérni kívánó műveletekre:

80%-os sikerességi arány három hét alatt
- a HTTP-válaszkódok százalékaként megadva a 2xx tartományban
99,9%-os megbízhatóság három héten keresztül
- a HTTP-válaszkódok százalékaként megadva nem az 5xx tartományban (az 502, 504 és 520 nem tartoznak bele ebbe a számításba)

A Család azon műveletek közötti kapcsolatot jelzi, amelyek fogalmilag egy művelethez tartoznak, de különböző változatok és esetleg kompatibilitástörő változások vannak közöttük. Több művelet is ugyanazzal a családnévvel fog rendelkezni, ha egymás változatainak kell tekinteni őket, és az egyedi változatszámuk alapján vannak sorba állítva.

A Változat művelet evolúciós sorrendjét jelzi a műveletek családján belül. A családon belül minden egyes művelet rendelkezik egy olyan változattal, amely a sorrendet jelző belső index része. Az üres változatot a rendszer az 1. változatként kezeli. Ha egy művelet újabb változatai érhetők el, az ügyfeleknek szembetűnőbben kell megjeleníteniük őket, és szándékosabban kell ajánlaniuk őket, de továbbra is lehetővé kell tenniük a még nem elavult, potenciálisan régebbi változatok kiválasztását.

Az Lejárat nem kötelező, és azt a lejárati dátumot jelzi, amikortól a művelet támogatása már nem biztosított. Ezt csak az elavult műveletekhez kell beállítani, és jelenleg nem jelenik meg egyik felületen sem.

Működési élettartam

A műveletek kiszámítható élettartammal rendelkeznek, ami példával jeleníthető meg.

Kezdőpont

Kezdetben a műveletek nem feltétlenül jeleznek semmit a változatokról. Ezeknél a műveleteknél az alapértelmezett beállítások vannak alkalmazva, ezért az 1. változatnak tekintendők az operationId értékkel egyező családnévben.

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

Ez megegyezik az alábbi explicitebb módú meghatározással:

{
    "/{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
            }
        }
    }
}

Műveletindítás

Az API-k fejlesztése a legtöbb esetben egy művelet hozzáadását jelenti. Például új metódusok és a meglévő metódusok új változatainak hozzáadását. Az új változat biztonságos kezdeményezéséhez a következőképpen módosíthatja a OpenAPI specifikációt:

{
    "/{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
            }
        }
    }
}

Fontos

Figyelje meg, hogy a GetItems V2 egyedi operationId értékkel rendelkezik, és kezdetben előzetes verzióban szerepel a listán. Azt is figyelje meg, hogy a GetItems v1 fejlett láthatósággal rendelkezik, ezért nem kiemelten jelenik meg.

Művelet elavulása

Néha a meglévő V1 belépési pontok határozatlan ideig maradnak, ha továbbra is értéket nyújtanak, és nincs kényszerítő ok a megszüntetésükre. Számos V2 belépési pont azonban szándékosan felülírja a V1 belépési pontot. Ennek biztonságos végrehajtásához minden forgalomnak a névleges nulla értéket kell elérnie az eredeti műveletben. Ha a telemetria megerősíti ezt, a következő módosítás hajtható végre:

{
    "/{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
            }
        }
    }
}

Fontos

Figyelje meg, hogy a GetItems V1-et már elavultként jelöli meg a rendszer. Ez az elavult műveletek utolsó állapotváltása. A GetItems V2 mostantól teljesen mértékben átvette a GetItems V1 helyét.

Miért kell ezzel foglalkozni?

Számos oka lehet az operatív verziószámozáshoz való ragaszkodásnak. Az első az, hogy ezzel biztosítható, hogy az Azure Logic Appshez és a Power Automate-hez hasonló ügyfelek továbbra is hibátlanul működjenek, amikor a felhasználók összekötői műveleteket integrálnak az adatfolyamokba. A műveleteket a fenti módszer használatával kell ellátni verziószámmal a következő esetekben:

Egy művelet új változatának hozzáadásakor
Egy meglévő művelet paramétereket ad hozzá vagy távolít el
Egy meglévő művelet jelentősen megváltoztatja a bemenetet vagy a kimenetet

Szigorú értelemben véve

Előfordulhatnak olyan esetek, amikor verziószámozás— nélkül is megúszhatja, de legyen óvatos, és végezzen sok tesztelést annak biztosítása érdekében, hogy ne hagyja figyelmen kívül azokat a peremhálózati eseteket, ahol a felhasználók váratlanul megszakadhatnak. Íme az óvatos rövid lista arról, hogy mikor úszhatja meg nélküle:

A rendszer hozzáad egy új műveletet.

Ez nem szakítaná meg kifejezetten a meglévő ügyfeleket.
Egy új, opcionális paraméter hozzáadása egy meglévő művelethez.

Ez nem szakítaná meg a meglévő hívásokat, de alaposan meg kell fontolni.
Egy meglévő művelet viselkedésének minimális változása.

A változás jellegétől és felhasználók használati módjától függően előfordulhat, hogy ez nem szakítja meg a meglévő hívókat. Ez a legbizonytalanabb, mivel a bemeneti elfogadás, a kimenet előállítása, időzítése vagy feldolgozása közötti jelentős különbség oly módon befolyásolhatja a művelet viselkedését, amely megnehezítheti a változás kockázatának meghatározását.

Ajánlott mindig elővigyázatosnak maradni és a nem triviális API-módosítások elvégzésekor minden esetben új verziót készíteni.

Visszajelzés küldése

Nagyra értékeljük az összekötőplatform problémáival kapcsolatos visszajelzéseket és az új funkciókkal kapcsolatos ötleteket. Ha visszajelzést szeretne küldeni, lépjen a Problémák küldése vagy segítség kérése az összekötőkkel kapcsolatban részre, és válassza ki a visszajelzés típusát.

Megosztás a következőn keresztül: