Verziók az Azure API Managementben

Minden API-kezelési szintre vonatkozik

A verziók lehetővé teszik a kapcsolódó API-k csoportjainak bemutatását a fejlesztők számára. A verziókkal biztonságosan kezelheti az API kompatibilitástörő változásait. Az ügyfelek dönthetnek úgy, hogy az új API-verziót használják, amikor készen állnak, míg a meglévő ügyfelek továbbra is egy régebbi verziót használnak. A verziók egy verzióazonosítóval vannak megkülönböztetve (amely bármely tetszőleges sztringérték), és a verziószámozási séma lehetővé teszi az ügyfelek számára, hogy azonosítsák az API melyik verzióját szeretnék használni. Ez a cikk a verziók API Managementben való használatát ismerteti.

A legtöbb cél esetében minden API-verzió saját független API-nak tekinthető. Két különböző API-verzió eltérő műveletkészlettel és különböző szabályzatokkal rendelkezhet.

A verziókkal a következőket teheti:

• Az API több verzióját is közzéteheti egyszerre.
• Használjon elérési utat, lekérdezési sztringet vagy fejlécet a verziók megkülönböztetéséhez.
• Használjon bármilyen karakterlánc értéket, amelyet a verzió azonosítására kíván használni. Lehet szám, dátum vagy név.
• Az API-verziók csoportosítva jelennek meg a fejlesztői portálon.
• Meglévő (nem verziószámozott) API új verziójának létrehozása meglévő ügyfelek befolyásolása nélkül.

Ismerkedjen meg a verziókkal egy útmutató végrehajtásával.

Verziószámozási sémák

A különböző API-fejlesztők eltérő követelményekkel rendelkeznek a verziószámozáshoz. Az Azure API Management nem ír elő egyetlen verziószámozási módszert, hanem több lehetőséget is kínál.

Útvonalalapú verziószámozás

Az elérési út verziószámozási sémájának használata esetén a verzióazonosítót minden API-kérés URL-elérési útjának tartalmaznia kell.

Például, https://apis.contoso.com/products/v1 és https://apis.contoso.com/products/v2 ugyanarra az products API-ra hivatkozhat, de a v1 és v2 verziókra.

Az ELÉRÉSIÚT-alapú verziószámozás használatakor az API-kérés URL-címe a https://{yourDomain}/{apiName}/{versionIdentifier}/{operationId}formátum.

Fejlécalapú verziószámozás

A fejléc verziószámozási sémájának használata esetén a verzióazonosítót egy HTTP-kérés fejlécében kell szerepeltetni minden API-kérés esetében. Megadhatja a HTTP-kérelem fejlécének nevét.

Létrehozhat például egy egyéni fejlécet, Api-Version, és az ügyfelek megadhatják a v1 vagy v2 értéket ebben a fejlécben.

Lekérdezési karakterlánc alapú verziószámozás

A lekérdezési sztring verziószámozási sémájának használatakor a verzióazonosítót minden API-kéréshez tartalmaznia kell egy lekérdezési sztringparaméterben. Megadhatja a lekérdezési sztring paraméter nevét.

A lekérdezési sztringalapú verziószámozás használatakor az API-kérés URL-címe a https://{yourDomain}/{apiName}/{operationId}?{queryStringParameterName}={versionIdentifier}formátum.

Például, https://apis.contoso.com/products?api-version=v1 és https://apis.contoso.com/products?api-version=v2 ugyanarra az products API-ra hivatkozhat, de a v1 és v2 verziókra.

Megjegyzés:

A lekérdezési paraméterek nem engedélyezettek az servers OpenAPI-specifikáció tulajdonságában. Ha openAPI-specifikációt exportál egy API-verzióból, a lekérdezési sztring nem jelenik meg a kiszolgáló URL-címében.

Eredeti verziók

Ha nem verziószámozott API-hoz ad hozzá verziót, a rendszer automatikusan létrehoz egy verziót Original , és az alapértelmezett URL-címen válaszol, a megadott verzióazonosító nélkül. A Original verzió biztosítja, hogy a meglévő hívókat ne befolyásolja a verzió hozzáadása. Ha létrehoz egy új API-t, ahol a verziók az elejétől engedélyezve vannak, Original verzió nem jön létre.

A verziók ábrázolásának menete

Az API Management egy verziókészletnek nevezett erőforrást tart fenn, amely egyetlen logikai API verziókészletét jelöli. A verziókészlet tartalmazza a verziószámozott API megjelenítendő nevét és a verziószámozási sémát, amellyel a kéréseket a megadott verziókra irányíthatja.

Az API minden verziója saját API-erőforrásként van fenntartva, és egy verziókészlethez van társítva. A verziókészletek különböző műveletekkel vagy szabályzatokkal rendelkező API-kat tartalmazhatnak. Előfordulhat, hogy jelentős módosításokat hajt végre egy készlet verziói között.

Az Azure Portal verziókészleteket hoz létre Önnek. Az Azure Portalon módosíthatja egy verzió nevét és leírását.

A végleges verzió törlésekor a rendszer automatikusan törli a verziókészletet.

A verziókészleteket közvetlenül az Azure CLI, az Azure PowerShell, a Resource Manager-sablonok vagy az Azure Resource Manager API használatával tekintheti meg és kezelheti.

Megjegyzés:

A verziókészlet minden verziója ugyanazzal a verziós sémával rendelkezik. Ez a verziószámozási sémán alapul, amelyet akkor használ, amikor először ad hozzá verziót egy API-hoz.

Nem verziószámozott API migrálása verziószámozott API-ba

Ha az Azure Portal használatával engedélyezi a verziószámozást egy meglévő API-n, a következő módosítások történnek az API Management-erőforrásokon:

• Létrejön egy új verziókészlet.
• A meglévő verzió megmarad, és API-verzióként Original van konfigurálva. Az API a verziókészlethez van csatolva, de a verzióazonosítót nem kell megadni.
• Az új verzió új API-ként jön létre, és a verziókészlethez van csatolva. Az új API eléréséhez verziószámozási sémát és azonosítót kell használni.

Verziók és változatok

A verziók és a felülvizsgálatok különböző jellemzők. Minden verzió több változatot is tartalmazhat, csakúgy, mint egy nem verziószámozott API-t. A változatokat verziók használata nélkül is használhatja, vagy fordítva. A verziók általában a kompatibilitástörő módosításokkal rendelkező API-verziók elkülönítésére szolgálnak, a változatok pedig az API kisebb és nem kompatibilitástörő módosításaihoz használhatók.

Ha úgy találja, hogy a változatban kompatibilitástörő változások történtek, vagy ha hivatalosan bétaverziós/tesztelési verzióvá szeretné alakítani a változatot, létrehozhat egy verziót egy változatból. Az Azure Portalon válassza a Változat létrehozása lehetőséget a változat helyi menüjében (...) a Változatok lapon.

Fejlesztői portál

A fejlesztői portál külön listázza az API egyes verzióit:

Az API részletei között az API összes verziójának listája is látható. Egy Original verzió verzióazonosító nélkül jelenik meg:

Jótanács

Api-verziókat kell hozzáadnia egy termékhez, hogy láthatóvá tegye őket a fejlesztői portálon.