Az API fejlesztése verziókövetéssel

  • Cikk

Egyéni összekötők a Azure Logic Apps, Microsoft Power Automate vagy Microsoft Power Apps meg kell adnia egy OpenAPI specifikációs fájlt. Ez OpenAPI a specifikáció a műveleteknek nevezett egyes belépési pontokat határozza meg. Minden műveletnek egyedi és egyedi operationId és 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 változá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 rendelkezik belső támogatással az operatív verziószámozáshoz. 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 az ügyfelek számára már nem kívánatos a művelet használata. Ez a tulajdonság a OpenAPI 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 karakterlánc jelez vagy üres karakterlánc "" jelez) az alapértelmezett érték, é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 a 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 elavulá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 javasolniuk őket, de továbbra is engedélyezniük kell a potenciálisan régebbi, még nem elavult 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 felülvizsgálat biztonságos kezdeményezéséhez a következőképpen kell módosítania 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-es 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. Sok 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 megúszhatja, de ennek során óvatosnak kell lennie, és rengeteg tesztet kell végeznie annak biztosítása érdekében, hogy ne hagyja figyelmen kívül azokat a peremeseteket, amikor a felhasználók váratlanul megszakadhatnak. Íme az óvatos rövid lista arról, hogy mikor lehet megúszni 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 az összes közül, mivel a bemenet elfogadásában, a kimenet generálásában, az időzítésben vagy a feldolgozásban mutatkozó jelentős különbség olyan 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.