Megjegyzés
Az oldalhoz való hozzáféréshez engedély szükséges. Megpróbálhat bejelentkezni vagy módosítani a címtárat.
Az oldalhoz való hozzáféréshez engedély szükséges. Megpróbálhatja módosítani a címtárat.
A JavaScript szolgáltatásfelügyeleti kódtára módot kínál az alkalmazásfunkciók funkciójelzők alapján történő fejlesztésére és elérhetővé ására. Egy új funkció fejlesztése után számos alkalmazás speciális követelményekkel rendelkezik, például mikor és milyen feltételek mellett kell engedélyezni a funkciót. Ez a kódtár lehetővé teszi ezeknek a kapcsolatoknak a meghatározását, és integrálható a gyakori JavaScript-kódmintákba, hogy lehetővé tegye ezeknek a funkcióknak a feltárást.
A funkciójelölők lehetővé teszik, hogy a JavaScript-alkalmazások dinamikusan kapcsolják be vagy ki a funkciókat. A fejlesztők funkciójelzőket használhatnak egyszerű használati esetekben, például feltételes utasításokban.
A JavaScript szolgáltatásfelügyeleti kódtár használatának néhány előnye:
- A funkciókezelés általános konvenciója
- Alacsony belépési korlát
- Támogatja a JSON-objektumokat és a térképalapú funkciójelző-forrásokat is
- Támogatja a használatot Node.js és böngészőkörnyezetekben is
- Funkciójelölő élettartam-kezelése Azure-alkalmazás konfigurációval
- A konfigurációs értékek valós időben változhatnak
- Egyszerű és összetett forgatókönyvek
- Szolgáltatások be- és kikapcsolása deklaratív konfigurációs fájlon keresztül
- A szolgáltatás állapotának dinamikus kiértékelése a kiszolgáló hívása alapján
A JavaScript szolgáltatásfelügyeleti kódtára nyílt forráskód. További információkért látogasson el a GitHub-adattárba.
Feljegyzés
Javasoljuk, hogy a szolgáltatásfelügyeleti kódtárat Azure-alkalmazás Konfigurációval együtt használja. Azure-alkalmazás Konfiguráció megoldást kínál az alkalmazásbeállítások és a funkciójelzők központi kezelésére. További részletekért tekintse meg ezt a szakaszt.
Funkciójelölők
A funkciójelzők két részből állnak, egy névből és a funkció bekapcsolásához használt funkciószűrők listájából.
Funkciószűrők
A funkciószűrők meghatároznak egy forgatókönyvet, amikor engedélyezni kell egy funkciót. Ha a rendszer kiértékel egy funkciót, hogy be- vagy kikapcsolt állapotban van-e, a szolgáltatásszűrők listája mindaddig bejáródik, amíg az egyik szűrő el nem dönti, hogy engedélyezni kell-e a funkciót. Ezen a ponton a funkció engedélyezettnek tekinthető, és a funkciószűrőkön való áthaladás megáll. Ha nincs funkciószűrő, amely azt jelzi, hogy engedélyezni kell a funkciót, akkor az le van tiltva.
Ilyen például egy Microsoft Edge böngészőfunkció-szűrő. Ez a funkciószűrő aktiválja a hozzá csatolt szolgáltatásokat, amíg a Microsoft Edge-ből http-kérés érkezik.
Funkciójelző konfigurációja
A JavaScriptben a fejlesztők általában objektumokat vagy térképeket használnak elsődleges adatstruktúrákként a konfigurációk megjelenítéséhez. A JavaScript szolgáltatásfelügyeleti kódtára mindkét konfigurációs módszert támogatja, így a fejlesztők rugalmasan választhatják ki az igényeiknek leginkább megfelelő lehetőséget. Az FeatureManager képes olvasni a funkciójelzőket különböző típusú konfigurációkból a beépített ConfigurationObjectFeatureFlagProvider és ConfigurationMapFeatureFlagProvider használatával.
const config = new Map([
["feature_management", {
"feature_flags": [
{
"id": "FeatureT",
"enabled": true
},
{
"id": "FeatureU",
"enabled": false
}
]
}],
["some other configuration", " some value"]
]);
import { ConfigurationMapFeatureFlagProvider, FeatureManager } from "@microsoft/feature-management";
const featureProvider = new ConfigurationMapFeatureFlagProvider(config);
const featureManager = new FeatureManager(featureProvider);
Funkciójelzők használata Azure-alkalmazás Konfigurációból
Ahelyett, hogy keményen kódolta a funkciójelzőket az alkalmazásba, javasoljuk, hogy tartsa meg a funkciójelzőket az alkalmazáson kívül, és külön kezelje őket. Ezzel bármikor módosíthatja a jelzőállapotokat, és azonnal érvénybe léptetheti a módosításokat az alkalmazásban. A Azure-alkalmazás Konfigurációs szolgáltatás egy dedikált portál felhasználói felületet biztosít az összes funkciójelző kezeléséhez. Tekintse meg az oktatóanyagot.
A Azure-alkalmazás Configuration szolgáltatás közvetlenül a JavaScript-ügyfélkódtár @azure/alkalmazáskonfiguráció-szolgáltatón keresztül továbbítja a funkciójelzőket az alkalmazásnak. Az alábbi példa a kódtár használatát mutatja be.
Az alkalmazáskonfiguráció JavaScript-szolgáltatója funkciójelzőket biztosít egy Map objektumban. A beépített ConfigurationMapFeatureFlagProvider segít betölteni a funkciójelzőket ebben az esetben.
import { DefaultAzureCredential } from "@azure/identity";
import { load } from "@azure/app-configuration-provider";
import { ConfigurationMapFeatureFlagProvider, FeatureManager } from "@microsoft/feature-management";
const appConfig = await load("YOUR_APP-CONFIG-ENDPOINT",
new DefaultAzureCredential(), // For more information: https://learn.microsoft.com/javascript/api/overview/azure/identity-readme
{ featureFlagOptions: { enabled: true } }); // load feature flags from Azure App Configuration service
const featureProvider = new ConfigurationMapFeatureFlagProvider(appConfig);
const featureManager = new FeatureManager(featureProvider);
A funkciójelző állapotának dinamikus vezérlése az Azure App Configuration használatával
Az Azure App Configuration nem csak a szolgáltatásjelzők tárolójának és központosított felügyeletének külsővé emelésére szolgál, hanem lehetővé teszi a funkciójelzők dinamikus be- és kikapcsolását is.
A funkciójelzők dinamikus frissítésének lehetővé tétele érdekében konfigurálnia kell a refresh tulajdonságot a featureFlagOptions betöltésekor az Azure App Configurationból.
const appConfig = await load("YOUR_APP-CONFIG-ENDPOINT", new DefaultAzureCredential(), {
featureFlagOptions: {
enabled: true,
refresh: {
enabled: true, // enable the dynamic refresh for feature flags
refreshIntervalInMs: 30_000
}
}
});
const featureProvider = new ConfigurationMapFeatureFlagProvider(appConfig);
const featureManager = new FeatureManager(featureProvider);
Meg kell hívnia a metódust a refresh legújabb funkciójelző állapotának lekéréséhez.
await appConfig.refresh(); // Refresh to get the latest feature flags
const isBetaEnabled = await featureManager.isEnabled("Beta");
console.log(`Beta is enabled: ${isBetaEnabled}`);
Feljegyzés
A szolgáltatásfelügyeleti kódtár Azure-alkalmazás Konfigurációval való használatáról a rövid útmutatóban talál további információt.
Funkciójelző deklarációja
Az alábbi példa a JSON-fájlok funkciójelzőinek beállításához használt formátumot mutatja be.
{
"feature_management": {
"feature_flags": [
{
"id": "FeatureT",
"enabled": true
},
{
"id": "FeatureU",
"enabled": false
},
{
"id": "FeatureV",
"enabled": true,
"conditions": {
"client_filters": [
{
"name": "Microsoft.TimeWindow",
"parameters": {
"Start": "Wed, 01 May 2019 13:59:59 GMT",
"End": "Mon, 01 Jul 2019 00:00:00 GMT"
}
}
]
}
}
]
}
}
A feature_management szakaszt konvenció használja a funkciójelző beállításainak betöltéséhez. A feature_flags szakasz a tárba betöltött funkciójelzők listája. A fenti szakaszban három különböző funkciót láthatunk. A funkciók a client_filters tulajdonság használatával határozzák meg a funkciószűrőket conditions-en belül. A funkciószűrőkben FeatureT látható, hogy mikor enabled nincsenek definiálva szűrők, az true mindig FeatureT eredményt ad vissza.
FeatureU ugyanaz, mint FeatureT, de a enabledfalse azt eredményezi, hogy a funkció mindig false-et ad vissza.
FeatureV egy funkciószűrőt nevez meg Microsoft.TimeWindow.
FeatureV egy konfigurálható funkciószűrő példája. A példában láthatjuk, hogy a szűrő rendelkezik tulajdonságával parameters . A parameters tulajdonság a szűrő konfigurálására szolgál. Ebben az esetben a szolgáltatás aktiválásának kezdő és befejező időpontjai konfigurálva vannak.
A szakasz részletes sémája feature_management itt található.
Speciális: A ":" kettőspont használata tiltott a funkciójelzők neveiben.
Követelmény típusa
A requirement_type funkciójelölő tulajdonsága határozza meg, hogy a szűrőknek használniuk Any kell-e vagy All logikát a funkció állapotának kiértékelésekor. Ha requirement_type nincs megadva, az alapértelmezett érték a következő Any.
-
Anyazt jelenti, hogy csak egy szűrőnek kell igaznak lennie ahhoz, hogy a funkció engedélyezve legyen. -
Allazt jelenti, hogy valamennyi szűrőnek igaznak kell lennie ahhoz, hogy a funkciót engedélyezzék.
A requirement_type megváltoztatja a All bejárást. Először is, ha nincsenek szűrők, a funkció le van tiltva. Ezután a jellemző szűrőit bejárják, amíg az egyik szűrő el nem dönti, hogy letiltja a jellemzőt. Ha nincs szűrő, amely azt jelzi, hogy a funkciót le kell tiltani, az engedélyezettnek minősül.
{
"feature_management": {
"feature_flags": [
{
"id": "FeatureW",
"enabled": true,
"conditions": {
"requirement_type": "All",
"client_filters": [
{
"name": "Microsoft.TimeWindow",
"parameters": {
"Start": "Wed, 01 May 2019 13:59:59 GMT",
"End": "Mon, 01 Jul 2019 00:00:00 GMT"
}
},
{
"name": "Percentage",
"parameters": {
"Value": "50"
}
}
]
}
},
]
}
}
A fenti példában a FeatureW meghatározza a requirement_typeAll értéket, ami azt jelenti, hogy az összes szűrőjének igaznak kell lennie ahhoz, hogy a funkció engedélyezve legyen. Ebben az esetben a funkció a felhasználók 50%-a számára engedélyezve van a megadott időkeretben.
Használat
A funkciókezelés alapszintű formája annak ellenőrzése, hogy engedélyezve van-e a funkciójelző, majd az eredmény alapján hajt végre műveleteket. A funkciójelző állapotának ellenőrzése a metóduson FeatureManager keresztül isEnabledtörténik.
import { ConfigurationMapFeatureFlagProvider, FeatureManager } from "@microsoft/feature-management";
const featureProvider = new ConfigurationMapFeatureFlagProvider(config);
const featureManager = new FeatureManager(featureProvider);
const isBetaEnabled = await featureManager.isEnabled("Beta");
if (isBetaEnabled) {
// Do something
}
Funkciószűrő implementálása
A szolgáltatásszűrők létrehozásával lehetővé válik a szolgáltatások engedélyezése az Ön által meghatározott feltételek alapján. A funkciószűrő implementálásához az IFeatureFilter interfészt végre kell hajtani. A IFeatureFilter rendelkezik a(z) name nevű tulajdonsággal és egy evaluate nevű metódussal. A name konfigurációban a funkciószűrőre kell hivatkozni egy funkciójelölőn belül. Ha egy szolgáltatás megadja, hogy engedélyezhető egy szolgáltatásszűrőhöz, a evaluate metódus meghívása történik. Ha evaluate visszaadja true, az azt jelenti, hogy a funkciót engedélyezni kell.
interface IFeatureFilter {
name: string;
evaluate(context: IFeatureFilterEvaluationContext, appContext?: unknown): boolean | Promise<boolean>;
}
Az alábbi kódrészlet bemutatja, hogyan implementálhat egy testre szabott, névvel MyCriteriaellátott funkciószűrőt.
class MyCriteriaFilter {
name = "MyCriteria";
evaluate(context, appContext) {
if (satisfyCriteria()) {
return true;
}
else {
return false;
}
}
}
Az egyéni szűrőt az customFilters konstruktorhoz átadott FeatureManagerOptions objektum FeatureManager tulajdonsága alatt kell regisztrálni.
const featureManager = new FeatureManager(ffProvider, {
customFilters: [
new MyCriteriaFilter() // add custom feature filters under FeatureManagerOptions.customFilters
]
});
Paraméteres funkciószűrők
Egyes funkciószűrőkhöz paraméterek szükségesek annak eldöntéséhez, hogy be kell-e kapcsolni egy funkciót. Előfordulhat például, hogy egy böngészőfunkció-szűrő bekapcsol egy funkciót bizonyos böngészőkben. Előfordulhat, hogy az Edge és a Chrome böngészők engedélyezik a funkciót, míg a Firefox nem. Ehhez egy funkciószűrőt úgy lehet megtervezni, hogy paramétereket várjon. Ezek a paraméterek a szolgáltatáskonfigurációban lesznek megadva, a kódban pedig a IFeatureFilterEvaluationContext paraméteren IFeatureFilter.Evaluatekeresztül érhetők el.
interface IFeatureFilterEvaluationContext {
featureName: string;
parameters?: unknown;
}
IFeatureFilterEvaluationContext nevű tulajdonsága parametersvan. Ezek a paraméterek egy nyers konfigurációt jelölnek, amellyel a szolgáltatásszűrő eldöntheti, hogyan kell értékelni, hogy engedélyezve legyen-e a szolgáltatás. Ha ismét példaként szeretné használni a böngészőfunkció-szűrőt, a szűrővel parameters kinyerheti a funkcióhoz megadott engedélyezett böngészők készletét, majd ellenőrizheti, hogy a kérést az adott böngészők egyikéből küldi-e el.
Alkalmazáskörnyezet használata funkcióértékeléshez
Előfordulhat, hogy egy szolgáltatásszűrőnek futtatókörnyezetre van szüksége egy funkciójelző kiértékeléséhez. Híváskor isEnabledparaméterként továbbíthatja a kontextust.
featureManager.isEnabled("Beta", { userId : "Sam" })
A funkciószűrő kihasználhatja a meghíváskor isEnabled átadott környezetet. Az alkalmazáskörnyezet második paraméterként lesz átadva a IFeatureFilter.Evaluate számára.
Beépített funkciószűrők
A csomaghoz két funkciószűrő tartozik FeatureManagement : TimeWindowFilter és TargetingFilter. Az összes beépített funkciószűrőt alapértelmezés szerint hozzáadja a FeatureManager konstrukciójakor.
Minden beépített funkciószűrő saját paraméterekkel rendelkezik. Íme a szolgáltatásszűrők listája a példákkal együtt.
Microsoft.TimeWindow
Ez a szűrő lehetővé teszi egy szolgáltatás időkereten alapuló engedélyezését. Ha csak End van megadva, a funkció addig be van kapcsolva. Ha csak Start meg van adva, a szolgáltatás az adott időpont után minden ponton figyelembe lesz véve.
"client_filters": [
{
"name": "Microsoft.TimeWindow",
"parameters": {
"Start": "Wed, 01 May 2019 13:59:59 GMT",
"End": "Mon, 01 Jul 2019 00:00:00 GMT"
}
}
]
Microsoft.Targeting
Ez a szűrő lehetővé teszi egy szolgáltatás engedélyezését a célközönség számára. A célzás részletes magyarázatát az alábbi célzási szakasz ismerteti. A szűrőparaméterek közé tartoznak a Audience felhasználókat, csoportokat, kizárt felhasználókat/csoportokat leíró objektumok, valamint a szolgáltatáshoz hozzáféréssel rendelkező felhasználói bázis alapértelmezett százalékos aránya. A szakaszban felsorolt csoportobjektumoknak Groups azt is meg kell adniuk, hogy a csoport tagjainak hány százaléka rendelkezzen hozzáféréssel. Ha egy felhasználó közvetlenül vagy kizárt csoportban van megadva a Exclusion szakaszban, a szolgáltatás le van tiltva. Ellenkező esetben, ha egy felhasználó közvetlenül a Users szakaszban van megadva, vagy ha a felhasználó a csoportbevezetések valamelyikének bevezetésre kerülő százalékba tartozik, vagy ha a felhasználó az alapértelmezett bevezetési százalékba esik, akkor a felhasználó számára engedélyezve lesz a funkció.
"client_filters": [
{
"name": "Microsoft.Targeting",
"parameters": {
"Audience": {
"Users": [
"Jeff",
"Alicia"
],
"Groups": [
{
"Name": "Ring0",
"RolloutPercentage": 100
},
{
"Name": "Ring1",
"RolloutPercentage": 50
}
],
"DefaultRolloutPercentage": 20,
"Exclusion": {
"Users": [
"Ross"
],
"Groups": [
"Ring2"
]
}
}
}
}
]
Célcsoportkezelés
A célzás egy funkciókezelési stratégia, amely lehetővé teszi a fejlesztők számára, hogy fokozatosan új funkciókat vezessenek be a felhasználói bázisukra. A stratégia a célközönségként ismert felhasználók egy csoportjának megcélzására épül. A célközönség meghatározott felhasználókból, csoportokból, kizárt felhasználókból/csoportokból és a teljes felhasználói bázis meghatározott százalékából áll. A közönségbe felvett csoportok további bontásban, a teljes tagok százalékos arányára bonthatók.
Az alábbi lépések egy új bétaverziós funkció fokozatos bevezetésére mutatnak be példát:
- Az egyes felhasználók Jeff és Alicia kapnak hozzáférést a bétaverzióhoz.
- Egy másik felhasználó, Mark, kéri, hogy jelentkezzen be, és szerepel benne.
- A "Ring1" nevű csoport felhasználóinak húsz százaléka szerepel a bétaverzióban.
- A bétaverzióban szereplő "Ring1" felhasználók száma akár 100 százalékra is csökken.
- A felhasználói bázis öt százaléka szerepel a bétaverzióban.
- A bevezetési százalék akár 100 százalék is lehet, és a funkció teljesen ki lett adva.
Ez a funkció üzembe helyezésének stratégiája a könyvtárba van beépítve az Microsoft.Targeting funkciószűrő segítségével.
Célzási környezettel rendelkező felhasználó megcélzása
A célzási szűrő egy célzási környezetre támaszkodik annak kiértékeléséhez, hogy be kell-e kapcsolni egy funkciót. Ez a célzási környezet olyan információkat tartalmaz, mint például a jelenleg kiértékelt felhasználó, és hogy a felhasználó milyen csoportokban van. A célkörnyezetet át kell adni közvetlenül, amikor isEnabled meghívásra kerül.
featureManager.isEnabled("Beta", { userId: "Aiden", groups: ["Ring1"] })
Kizárások megcélzása
Célközönség meghatározásakor a felhasználók és csoportok kizárhatók a célközönségből. A kizárások akkor hasznosak, ha egy szolgáltatás egy felhasználói csoport számára kerül bevezetésre, de néhány felhasználót vagy csoportot ki kell zárni a bevezetésből. A kizárást a felhasználók és csoportok listájának a célközönség tulajdonságához való hozzáadásával lehet definiálni Exclusion .
"Audience": {
"Users": [
"Jeff",
"Alicia"
],
"Groups": [
{
"Name": "Ring0",
"RolloutPercentage": 100
}
],
"DefaultRolloutPercentage": 0,
"Exclusion": {
"Users": [
"Mark"
]
}
}
A fenti példában a funkció engedélyezve van a Jeff és Alicia nevű felhasználók számára. A Ring0 nevű csoporthoz tartozó felhasználók számára is engedélyezve van. Ha azonban a felhasználó neve el van nevezve Mark, a szolgáltatás le van tiltva, függetlenül attól, hogy a csoportban Ring0 vannak-e, vagy sem. A kizárások elsőbbséget élveznek a célszűrő többi részével szemben.
Célzás webalkalmazásban
Ebben a példában a célzási funkciószűrőt használó webalkalmazás érhető el.
A webalkalmazásokban, különösen azok esetében, amelyek több összetevővel vagy réteggel rendelkeznek, nehézkessé és ismétlődővé válhat, ha a célkörnyezetet (userId és groups) minden funkciójelző-ellenőrzésnek átadja. Ezt a forgatókönyvet "környezeti célzási környezetnek" nevezzük, ahol a felhasználói identitás adatai már elérhetők az alkalmazáskörnyezetben (például munkamenet-adatok vagy hitelesítési környezetek esetében), de az alkalmazás teljes területén el kell érnie a szolgáltatásfelügyeleti értékeléseket.
ITargetingContextAccessor
A kódtár a mintán keresztül ITargetingContextAccessor nyújt megoldást.
interface ITargetingContext {
userId?: string;
groups?: string[];
}
interface ITargetingContextAccessor {
getTargetingContext: () => ITargetingContext | undefined;
}
Ahelyett, hogy explicit módon átadta a célkörnyezetet mindegyik isEnabled vagy getVariant hívás számára, megadhat egy függvényt, amely tudja, hogyan lehet lekérni az aktuális felhasználó célzási adatait az alkalmazás környezetéből:
import { FeatureManager, ConfigurationObjectFeatureFlagProvider } from "@microsoft/feature-management";
// Create a targeting context accessor that uses your application's auth system
const targetingContextAccessor = {
getTargetingContext: () => {
// In a web application, this might access request context or session data
// This is just an example - implement based on your application's architecture
return {
userId: getCurrentUserId(), // Your function to get current user
groups: getUserGroups() // Your function to get user groups
};
}
};
// Configure the feature manager with the accessor
const featureManager = new FeatureManager(featureProvider, {
targetingContextAccessor: targetingContextAccessor
});
// Now you can call isEnabled without explicitly providing targeting context
// The feature manager will use the accessor to get the current user context
const isBetaEnabled = await featureManager.isEnabled("Beta");
Ez a minta különösen hasznos a kiszolgálóoldali webalkalmazásokban, ahol a felhasználói környezet elérhető lehet egy kérelem hatókörében vagy olyan ügyfélalkalmazásokban, ahol a felhasználói identitás központilag van kezelve.
Az AsyncLocalStorage használata a kérelemkörnyezethez
A célkörnyezeti kiegészítő minta megvalósításakor gyakori kihívás a kérelemkörnyezet fenntartása az aszinkron hívásláncban. A Node.js webalkalmazásokban a felhasználói identitás adatai általában elérhetők a kérelemobjektumban, de az aszinkron műveletek megadása után elérhetetlenné válnak.
Node.js a modulból biztosítja AsyncLocalStorage a async_hooks probléma megoldását. Létrehoz egy tárolót, amely az aszinkron műveletek között ugyanazon a logikai "kontextuson" belül marad – tökéletes a kérelemadatok teljes kérelem-életciklusban való karbantartásához.
Az alábbiakban bemutatjuk, hogyan implementálhat egy célcsoport-kiegészítőt az AsyncLocalStorage használatával egy expressz alkalmazásban:
import { AsyncLocalStorage } from "async_hooks";
import express from "express";
const requestAccessor = new AsyncLocalStorage();
const app = express();
// Middleware to store request context
app.use((req, res, next) => {
// Store the request in AsyncLocalStorage for this request chain
requestAccessor.run(req, () => {
next();
});
});
// Create targeting context accessor that retrieves user data from the current request
const targetingContextAccessor = {
getTargetingContext: () => {
// Get the current request from AsyncLocalStorage
const request = requestContext.getStore();
if (!request) {
return undefined; // Return undefined if there's no current request
}
// Extract user data from request (from session, auth token, etc.)
return {
userId: request.user?.id,
groups: request.user?.groups || []
};
}
};
Változatok
Amikor új funkciókat adnak hozzá egy alkalmazáshoz, előfordulhat, hogy egy funkció több különböző javasolt tervezési lehetőséggel rendelkezik. A tervezéssel kapcsolatos döntés egyik gyakori megoldása az A/B tesztelés valamilyen formája, amely magában foglalja a funkció egy másik verziójának biztosítását a felhasználói bázis különböző szegmensei számára, és a felhasználói interakciók alapján kiválasztja a verziót. Ebben a kódtárban ez a funkció egy funkció különböző konfigurációinak variánsokkal való ábrázolásával engedélyezve van.
A változatok lehetővé teszik, hogy egy funkciójelző több legyen, mint egy egyszerű be- és kikapcsolási jelző. A variánsok egy funkciójelző értékét jelölik, amely lehet sztring, szám, logikai vagy akár konfigurációs objektum is. A változatokat deklaráló funkciójelzőnek meg kell határoznia, hogy milyen körülmények között kell használni az egyes változatokat, amelyről részletesebben a Kiosztási változatok szakaszban olvashat.
Változat lekérése célkörnyezettel
Minden funkcióhoz lekérhető egy variáns a FeatureManager"metódus" getVariant használatával. A variáns-hozzárendelés az éppen kiértékelt felhasználótól függ, és a rendszer az átadott célkörnyezetből szerzi be az adatokat. Ha regisztrált egy célkörnyezet-hozzáférőt a FeatureManager elemhez, a célkörnyezet automatikusan le lesz kérve róla. De továbbra is felülbírálhatja, ha manuálisan adja át a célkörnyezetet híváskor getVariant.
const variant = await featureManager.getVariant("MyVariantFeatureFlag", { userId: "Sam" });
const variantName = variant.name;
const variantConfiguration = variant.configuration;
// Do something with the resulting variant and its configuration
Variant-funkciójelző deklarációja
A normál funkciójelzőkhöz képest a változatfunkció-jelzők két további tulajdonsággal rendelkeznek: variants és allocation. A variants tulajdonság egy tömb, amely a funkcióhoz definiált változatokat tartalmazza. A allocation tulajdonság határozza meg, hogyan kell lefoglalni ezeket a változatokat a funkcióhoz. A normál funkciójelölők deklarálásával egy JSON-fájlban is beállíthat változatfunkció-jelzőket. Íme egy példa egy változat funkciójelzőre.
{
"feature_management": {
"feature_flags": [
{
"id": "MyVariantFeatureFlag",
"enabled": true,
"allocation": {
"default_when_enabled": "Small",
"group": [
{
"variant": "Big",
"groups": [
"Ring1"
]
}
]
},
"variants": [
{
"name": "Big"
},
{
"name": "Small"
}
]
}
]
}
}
Változatok definiálása
Mindegyik változat két tulajdonsággal rendelkezik: egy névvel és egy konfigurációval. A név egy adott változatra hivatkozik, a konfiguráció pedig az adott változat értéke. A konfiguráció configuration_value tulajdonság használatával állítható be.
configuration_value egy beágyazott konfiguráció, amely lehet sztring, szám, logikai vagy konfigurációs objektum. Ha configuration_value nincs megadva, a visszaadott változat tulajdonsága configuration .undefined
A tulajdonság minden egyes funkciójára vonatkozóan meg van határozva az variants összes lehetséges változat listája.
{
"feature_management": {
"feature_flags": [
{
"id": "MyVariantFeatureFlag",
"variants": [
{
"name": "Big",
"configuration_value": {
"Size": 500
}
},
{
"name": "Small",
"configuration_value": {
"Size": 300
}
}
]
}
]
}
}
Változatok kiosztása
A funkcióváltozatok kiosztásának folyamatát a allocation funkció tulajdonsága határozza meg.
"allocation": {
"default_when_disabled": "Small",
"default_when_enabled": "Small",
"user": [
{
"variant": "Big",
"users": [
"Marsha"
]
}
],
"group": [
{
"variant": "Big",
"groups": [
"Ring1"
]
}
],
"percentile": [
{
"variant": "Big",
"from": 0,
"to": 10
}
],
"seed": "13973240"
},
"variants": [
{
"name": "Big",
"configuration_value": "500px"
},
{
"name": "Small",
"configuration_value": "300px"
}
]
A allocation funkció beállítása a következő tulajdonságokkal rendelkezik:
| Tulajdonság | Leírás |
|---|---|
default_when_disabled |
Megadja, hogy melyik változatot kell használni, amikor egy változatot kérnek, miközben a funkció le van tiltva. |
default_when_enabled |
Megadja, hogy melyik változatot kell használni, amikor egy változatot kérnek, miközben a funkció engedélyezve van, és nem rendeltek hozzá más változatot a felhasználóhoz. |
user |
Egy változatot és azon felhasználók listáját adja meg, akikhez a változatot hozzá kell rendelni. |
group |
Egy variánst és egy csoportlistát határoz meg. A variáns akkor lesz hozzárendelve, ha a felhasználó legalább egy csoportban van. |
percentile |
Egy variánst és egy százalékos tartományt ad meg, amelyhez a felhasználó százalékos értékének igazodnia kell ahhoz, hogy a változat hozzárendelhető legyen. |
seed |
Az az érték, amelyre a percentile százalékos számítások alapulnak. Ha ugyanazt seed az értéket használja, az adott felhasználó százalékos kiszámítása minden szolgáltatásban azonos lesz. Ha nincs seed megadva, a rendszer létrehoz egy alapértelmezett magot a szolgáltatásnév alapján. |
Ha a funkció nincs engedélyezve, a funkciókezelő az aktuális felhasználónak rendeli hozzá a default_when_disabled jelű változatot, amely ebben az esetben a Small.
Ha a funkció engedélyezve van, a funkciókezelő ellenőrzi a user, groupés percentile a foglalásokat abban a sorrendben, hogy hozzárendeljen egy változatot. Ebben a konkrét példában, ha a kiértékelt felhasználó neve el van nevezve Marsha, a névvel ellátott Ring1csoportban, vagy a felhasználó a 0 és a 10. percentilis közé esik, akkor a megadott változat lesz hozzárendelve a felhasználóhoz. Ebben az esetben az összes hozzárendelt felhasználó visszaadja a Big változatot. Ha egyik kiosztás sem egyezik meg, a felhasználóhoz a default_when_enabled variánst fogják hozzárendelni, ami Small.
A kiosztási logika hasonló a Microsoft.Targeting szolgáltatásszűrőhöz, de vannak olyan paraméterek, amelyek nem szerepelnek a kiosztásban, és fordítva. A célzás és a kiosztás eredményei nem kapcsolódnak egymáshoz.
Engedélyezett állapot felülírása egy variánssal
A változatok használatával felülbírálhatja egy funkciójelző engedélyezett állapotát. A felülírás lehetőséget ad a variánsoknak egy funkciójelző kiértékelésének kiterjesztésére. Ha egy variánsokkal rendelkező jelölőt hív meg is_enabled, a funkciókezelő ellenőrzi, hogy az aktuális felhasználóhoz rendelt variáns felülírja-e az eredményt. A felülírás az opcionális változattulajdonság status_overridehasználatával történik. Alapértelmezés szerint ez a tulajdonság be van állítva None, ami azt jelenti, hogy a változat nem befolyásolja, hogy a jelző engedélyezve vagy letiltva van-e. A status_overrideEnabled-ra való beállítása lehetővé teszi a variánsnak, hogy a választáskor felülírjon egy jelölőt, amelyet engedélyezni kell. A status_overrideDisabled beállítása az ellenkező funkciót biztosítja, ezért letiltja a jelölőt, amikor a változat ki van választva. Egy enabled állapotú false funkció nem bírálható felül.
Ha bináris változatokkal rendelkező funkciójelzőt használ, a status_override tulajdonság hasznos lehet. Lehetővé teszi az API-k használatának folytatását, mint is_enabled az alkalmazásban, mindezt úgy, hogy kihasználja a variánsokkal járó új funkciókat, például a percentilis kiosztást és a magot.
{
"id": "MyVariantFeatureFlag",
"enabled": true,
"allocation": {
"percentile": [
{
"variant": "On",
"from": 10,
"to": 20
}
],
"default_when_enabled": "Off",
"seed": "Enhanced-Feature-Group"
},
"variants": [
{
"name": "On"
},
{
"name": "Off",
"status_override": "Disabled"
}
]
}
A fenti példában a funkció mindig engedélyezve van. Ha az aktuális felhasználó a számított percentilistartományban van 10 és 20 között, akkor a rendszer visszaadja a On variánst. Ellenkező esetben a rendszer visszaadja a Off variánst, és mivel status_override az egyenlő Disabled, a funkció le lesz tiltva.
Telemetria
Amikor üzembe helyez egy funkciójelző-módosítást, gyakran fontos elemezni az alkalmazásra gyakorolt hatását. Íme például néhány kérdés, amely felmerülhet:
- A jelölők úgy vannak engedélyezve/letiltva, ahogy várható volt?
- A megcélzott felhasználók a várt módon férnek hozzá egy adott funkcióhoz?
- Melyik változatot látja egy adott felhasználó?
Ezekre a kérdésekre a funkciójelzők kiértékelési eseményeinek kibocsátásával és elemzésével lehet válaszolni.
Telemetria engedélyezése
Alapértelmezés szerint a funkciójelzők nem bocsátanak ki telemetriát. Egy adott funkciójelző telemetriájának közzétételéhez a jelzőnek deklarálnia kell, hogy engedélyezve van a telemetria kibocsátására.
A jsonban definiált funkciójelzők esetében az engedélyezés a telemetry tulajdonság használatával történik.
{
"feature_management": {
"feature_flags": [
{
"id": "MyFeatureFlag",
"enabled": true,
"telemetry": {
"enabled": true
}
}
]
}
}
A fenti kódrészlet egy olyan funkciójelölőt MyFeatureFlag határoz meg, amely engedélyezve van a telemetriához. Az telemetry objektum tulajdonsága enabled a következőre truevan állítva: . A enabled tulajdonság értékének true kell lennie ahhoz, hogy közzé lehessen tenni a jelző telemetriáját.
A telemetry funkciójelölő szakasza a következő tulajdonságokkal rendelkezik:
| Tulajdonság | Leírás |
|---|---|
enabled |
Megadja, hogy közzé kell-e tenni a telemetriát a funkciójelölőhöz. |
metadata |
A kulcs-érték párok szótárként modellezett gyűjteménye, amely a funkciójelző egyéni metaadatainak a kiértékelési eseményekhez való csatolására használható. |
Egyedi telemetria közzététele
Visszahívási függvényt regisztrálhat, amikor onFeatureEvaluated-t hoz létre FeatureManager. Ezt a visszahívást akkor hívja meg a program, ha kiértékel egy funkciójelzőt, és a telemetria engedélyezve van az adott jelzőhöz. A visszahívási függvény a funkció kiértékelési eredményét fogja paraméterként venni.
Az alábbi példa bemutatja, hogyan implementálhat egy egyéni visszahívási függvényt, amellyel telemetriát küldhet a funkcióértékelési eredményből kinyert információkkal, és regisztrálhatja azt a funkciókezelőben.
const sendTelemetry = (evaluationResult) => {
const featureId = evaluationResult.feature.id;
const featureEnabled = evaluationResult.enabled;
const targetingId = evaluationResult.targetingId;
const variantName = evaluationResult.variant?.name;
const variantAssignmentReason = evaluationResult.variantAssignmentReason;
// custom code to send the telemetry
// ...
}
const featureManager = new FeatureManager(featureProvider, { onFeatureEvaluated : sendTelemtry});
Az Application Insights integrációja
A JavaScript szolgáltatásfelügyeleti kódtár olyan bővítménycsomagokat biztosít, amelyek integrálhatók az Application Insights SDK-kkal.
Az Application Insights különböző SDK-kat kínál webes és Node.js forgatókönyvekhez. Válassza ki az alkalmazáshoz megfelelő bővítménycsomagokat.
Ha az alkalmazás a böngészőben fut, telepítse a "@microsoft/feature-management-applicationinsights-browser" csomagot. Az alábbi példa bemutatja, hogyan hozhat létre egy beépített Application Insights telemetriai közzétevőt, és regisztrálhatja azt a funkciókezelőben.
import { ApplicationInsights } from "@microsoft/applicationinsights-web"
import { FeatureManager, ConfigurationObjectFeatureFlagProvider } from "@microsoft/feature-management";
import { createTelemetryPublisher, trackEvent } from "@microsoft/feature-management-applicationinsights-browser";
const appInsights = new ApplicationInsights({ config: {
connectionString: "<APPINSIGHTS_CONNECTION_STRING>"
}});
appInsights.loadAppInsights();
const publishTelemetry = createTelemetryPublisher(appInsights);
const provider = new ConfigurationObjectFeatureFlagProvider(jsonObject);
const featureManager = new FeatureManager(provider, {onFeatureEvaluated: publishTelemetry});
// FeatureEvaluation event will be emitted when a feature flag is evaluated
featureManager.getVariant("TestFeature", {userId : TARGETING_ID}).then((variant) => { /* do something*/ });
// Emit a custom event with targeting id attached.
trackEvent(appInsights, TARGETING_ID, {name: "TestEvent"}, {"Tag": "Some Value"});
A telemetriai közzétevő egyéni eseményeket küld FeatureEvaluation az Application Insightsnak a telemetriával engedélyezett funkciójelző kiértékelésekor. Az egyéni esemény a FeatureEvaluationEvent sémát követi.
Telemetriai processzor célzása
Ha implementálta ITargetingContextAccessor, a beépített Application Insights telemetriai processzorral automatikusan csatolhat célazonosító-adatokat az összes telemetriához a createTargetingTelemetryProcessor függvény meghívásával.
const appInsights = require("applicationinsights");
appInsights.setup(process.env.APPINSIGHTS_CONNECTION_STRING).start();
const { createTargetingTelemetryProcessor } = require("@microsoft/feature-management-applicationinsights-node");
appInsights.defaultClient.addTelemetryProcessor(
createTargetingTelemetryProcessor(targetingContextAccessor)
);
Ez biztosítja, hogy az Application Insightsnak küldött összes telemetriai elem tartalmazza a felhasználó célazonosító-adatait (userId és csoportok), lehetővé téve a funkciójelölők használatának korrelációját az elemzés adott felhasználóival vagy csoportjaival.
Ha a célzott telemetriai processzort használja, a trackEvent szolgáltatásfelügyeleti csomag által biztosított metódus meghívása helyett közvetlenül meghívhatja a trackEvent metódust az Application Insights SDK-ból. A célazonosító adatai automatikusan csatolva lesznek az egyéni eseménytelemetria customDimensionsadataihoz.
// Instead of calling trackEvent and passing the app insights client
// trackEvent(appInsights.defaultClient, "<TARGETING_ID>", {name: "TestEvent", properties: {"Tag": "Some Value"}});
// directly call trackEvent method provided by App Insights SDK
appInsights.defaultClient.trackEvent({ name: "TestEvent" });
Következő lépések
Ha meg szeretné tudni, hogyan használhatja a funkciójelzőket az alkalmazásokban, folytassa az alábbi rövid útmutatókkal.
A funkciószűrők használatának megismeréséhez folytassa az alábbi oktatóanyagokkal.