JavaScript-functiebeheer

De JavaScript-bibliotheek voor functiebeheer biedt een manier om toepassingsfunctionaliteit te ontwikkelen en beschikbaar te maken op basis van functievlagmen. Zodra een nieuwe functie is ontwikkeld, hebben veel toepassingen speciale vereisten, zoals wanneer de functie moet worden ingeschakeld en onder welke omstandigheden. Deze bibliotheek biedt een manier om deze relaties te definiëren en kan ook worden geïntegreerd in algemene JavaScript-codepatronen om deze functies beschikbaar te maken.

Functievlagmen bieden een manier voor JavaScript-toepassingen om functies dynamisch in of uit te schakelen. Ontwikkelaars kunnen functievlagmen gebruiken in eenvoudige gebruiksvoorbeelden, zoals voorwaardelijke instructies.

Hier volgen enkele voordelen van het gebruik van de JavaScript-functiebeheerbibliotheek:

• Een algemene conventie voor functiebeheer
• Lage barrière om binnen te komen
  • Ondersteunt zowel JSON-objecten als op kaarten gebaseerde functievlagbronnen
  • Ondersteunt gebruik in zowel Node.js als browseromgevingen
• Levensduurbeheer van feature vlaggen met Azure App Configuration
  • Configuratiewaarden kunnen in realtime worden gewijzigd
• Eenvoudige tot complexe scenario's die worden behandeld
  • Functies in-/uitschakelen via een declaratief configuratiebestand
  • De status van de functie dynamisch evalueren op basis van aanroep naar server

De JavaScript-bibliotheek voor functiebeheer is open source. Ga naar de GitHub-opslagplaats voor meer informatie.

Functievlaggen

Functievlagmen bestaan uit twee delen, een naam en een lijst met functiefilters die worden gebruikt om de functie in te schakelen.

Functiefilters

Functiefilters definiëren een scenario voor wanneer een functie moet worden ingeschakeld. Wanneer een functie wordt geëvalueerd of deze is ingeschakeld of uitgeschakeld, wordt de lijst met functiefilters doorkruist totdat een van de filters besluit dat de functie moet worden ingeschakeld. Op dit moment wordt het functiekenmerk beschouwd als ingeschakeld en stopt het doorlopen van de functiefilters. Als er geen functiefilter aangeeft dat de functie moet worden ingeschakeld, wordt deze als uitgeschakeld beschouwd.

Een microsoft Edge-browserfunctiefilter kan bijvoorbeeld worden ontworpen. Met dit functiefilter worden alle functies geactiveerd die eraan zijn gekoppeld, zolang een HTTP-aanvraag afkomstig is van Microsoft Edge.

Configuratie van functievlag

In JavaScript gebruiken ontwikkelaars vaak objecten of kaarten als de primaire gegevensstructuren om configuraties weer te geven. De JavaScript-bibliotheek voor functiebeheer ondersteunt beide configuratiemethoden, zodat ontwikkelaars de flexibiliteit hebben om de optie te kiezen die het beste bij hun behoeften past. De FeatureManager functievlagmen van verschillende typen configuratie kunnen worden gelezen met behulp van de ingebouwde ConfigurationObjectFeatureFlagProvider en ConfigurationMapFeatureFlagProvider.

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);

const config = {
    "feature_management": {
        "feature_flags": [
            {
                "id": "FeatureT",
                "enabled": true
            },
            {
                "id": "FeatureX",
                "enabled": false
            }
        ]
    },
    "some other configuration": " some value"
}

import { ConfigurationObjectFeatureFlagProvider, FeatureManager } from "@microsoft/feature-management";
const featureProvider = new ConfigurationObjectFeatureFlagProvider(config);
const featureManager = new FeatureManager(featureProvider);

const config = JSON.parse(await fs.readFile("path/to/config.json"));
const featureProvider = new ConfigurationObjectFeatureFlagProvider(config);
const featureManager = new FeatureManager(featureProvider);

Functievlagmen gebruiken vanuit Azure-app-configuratie

In plaats van uw functievlagmen hard te coderen in uw toepassing, wordt u aangeraden functievlagmen buiten de toepassing te houden en deze afzonderlijk te beheren. Als u dit doet, kunt u de status van de vlaggen op elk gewenst moment wijzigen. Deze wijzigingen worden direct doorgevoerd in de toepassing. De Azure-app Configuration-service biedt een toegewezen portalgebruikersinterface voor het beheren van al uw functievlagmen. Zie de handleiding.

De Azure-app Configuration-service levert de functievlagken ook rechtstreeks aan uw toepassing via de JavaScript-clientbibliotheek @azure/app-configuration-provider. In het volgende voorbeeld ziet u hoe u de bibliotheek gebruikt.

De JavaScript-provider voor App Configuration biedt functievlagmen in een Map object. De ingebouwde ConfigurationMapFeatureFlagProvider helpt om feature flags in dit geval te laden.

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);

Azure App Configuration gebruiken om de status van de functievlag dynamisch te beheren

Azure App Configuration is niet alleen een oplossing voor het externaliseren van opslag en gecentraliseerd beheer van uw functievlagmen, maar ook om de functievlagmen dynamisch in of uit te schakelen.

Als u de dynamische vernieuwing voor functievlaggen wilt inschakelen, moet u de refresh eigenschap van featureFlagOptions configureren bij het laden van functievlaggen vanuit Azure App Configuration.

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);

U moet de refresh methode aanroepen om de meest recente functievlagstatus op te halen.

await appConfig.refresh(); // Refresh to get the latest feature flags
const isBetaEnabled = await featureManager.isEnabled("Beta");
console.log(`Beta is enabled: ${isBetaEnabled}`);

Declaratie van functievlaggen

In het volgende voorbeeld ziet u de indeling die wordt gebruikt voor het instellen van functievlagmen in een JSON-bestand.

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

De feature_management sectie wordt volgens de conventie gebruikt om instellingen voor functievlagken te laden. De feature_flags sectie is een lijst met de functievlagmen die in de bibliotheek worden geladen. In de bovenstaande sectie zien we drie verschillende functies. Functies definiëren hun functiefilters met behulp van de eigenschap client_filters, binnen conditions. In de functiefilters voor FeatureT zien we dat er enabled geen filters zijn gedefinieerd, wat resulteert in dat true altijd FeatureT retourneert. FeatureU is hetzelfde als FeatureT maar met enabled resulteert false in het altijd retourneren falsevan de functie. FeatureV hiermee geeft u een functiefilter met de naam Microsoft.TimeWindow. FeatureV is een voorbeeld van een configureerbaar functiefilter. In het voorbeeld zien we dat het filter een parameters eigenschap heeft. De parameters eigenschap wordt gebruikt om het filter te configureren. In dit geval worden de begin- en eindtijden voor de functie geconfigureerd om actief te zijn.

Het gedetailleerde schema van de feature_management sectie vindt u hier.

Geavanceerd: Het gebruik van dubbele punt ':' is verboden in functievlagnamen.

Vereiste type

De requirement_type eigenschap van een functievlag wordt gebruikt om te bepalen of de filters Any of All logica moeten gebruiken bij het evalueren van de status van een functie. Als requirement_type niet is opgegeven, is de standaardwaarde Any.

• Any betekent dat één filter moet evalueren tot waar voor de functie om ingeschakeld te worden.
• All betekent dat elk filter aan de voorwaarden moet voldoen om de functie kan worden ingeschakeld.

Een requirement_typeAll verandert de doorkruising. Als er geen filters zijn, is de functie eerst uitgeschakeld. Vervolgens worden de functiefilters doorkruist totdat een van de filters besluit dat de functie moet worden uitgeschakeld. Als er geen filter aangeeft dat de functie moet worden uitgeschakeld, wordt deze als ingeschakeld beschouwd.

{
    "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"
                            }
                        }
                    ]
                }
            },
        ]
    }
}

In het bovenstaande voorbeeld geeft u een FeatureW vanrequirement_type, All wat betekent dat alle filters waar moeten zijn om de functie in te schakelen. In dit geval is de functie ingeschakeld voor 50% van de gebruikers tijdens het opgegeven tijdvenster.

Verbruik

De basisvorm van functiebeheer is controleren of een functievlag is ingeschakeld en vervolgens acties uitvoert op basis van het resultaat. Het controleren van de status van een functievlag wordt uitgevoerd via FeatureManagerde isEnabled methode.

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
}

import { ConfigurationObjectFeatureFlagProvider, FeatureManager } from "@microsoft/feature-management";
const featureProvider = new ConfigurationObjectFeatureFlagProvider(config);
const featureManager = new FeatureManager(featureProvider);

const isBetaEnabled = await featureManager.isEnabled("Beta");
if (isBetaEnabled) {
    // Do something
}

Een functiefilter implementeren

Het maken van een functiefilter biedt een manier om functies in te schakelen op basis van criteria die u definieert. Als u een functiefilter wilt implementeren, moet de IFeatureFilter interface worden geïmplementeerd. IFeatureFilter heeft een name eigenschap en een methode met de naam evaluate. Deze name moet worden gebruikt in de configuratie om te verwijzen naar het functiefilter binnen een functievlag. Wanneer een functie aangeeft dat deze kan worden ingeschakeld voor een functiefilter, wordt de evaluate methode aangeroepen. Als evaluatetrue retourneert, betekent dit dat de functie moet worden ingeschakeld.

interface IFeatureFilter {
    name: string;
    evaluate(context: IFeatureFilterEvaluationContext, appContext?: unknown): boolean | Promise<boolean>;
}

Het volgende codefragment laat zien hoe u een aangepast functiefilter met de naam MyCriteriaimplementeert.

    class MyCriteriaFilter {
        name = "MyCriteria";
        evaluate(context, appContext) {
            if (satisfyCriteria()) {
                return true;
            }
            else {
                return false;
            }
        }
    }

Je moet het aangepaste filter registreren onder de eigenschap customFilters van het object FeatureManagerOptions dat aan de constructor FeatureManager is doorgegeven.

const featureManager = new FeatureManager(ffProvider, {
    customFilters: [
        new MyCriteriaFilter() // add custom feature filters under FeatureManagerOptions.customFilters
    ]
});

Geparameteriseerde functiefilters

Sommige functiefilters vereisen parameters om te bepalen of een functie moet worden ingeschakeld of niet. Een browserfunctiefilter kan bijvoorbeeld een functie inschakelen voor een bepaalde set browsers. Het kan gewenst zijn dat Edge- en Chrome-browsers een functie inschakelen, terwijl Firefox dat niet doet. Hiervoor kan een functiefilter worden ontworpen om parameters te verwachten. Deze parameters zouden worden opgegeven in de functieconfiguratie en in code toegankelijk zijn via de IFeatureFilterEvaluationContext parameter van IFeatureFilter.Evaluate.

interface IFeatureFilterEvaluationContext {
    featureName: string;
    parameters?: unknown;
}

IFeatureFilterEvaluationContext heeft een eigenschap met de naam parameters. Deze parameters vertegenwoordigen een onbewerkte configuratie die het functiefilter kan gebruiken om te bepalen hoe de functie moet worden ingeschakeld of niet. Als u het browserfunctiefilter opnieuw wilt gebruiken als voorbeeld, kan het filter een parameters set toegestane browsers extraheren die voor de functie worden opgegeven en vervolgens controleren of de aanvraag wordt verzonden vanuit een van deze browsers.

Toepassingscontext gebruiken voor functie-evaluatie

Een functiefilter heeft mogelijk runtimetoepassingscontext nodig om een functievlag te evalueren. U kunt de context doorgeven als parameter bij het aanroepen isEnabled.

featureManager.isEnabled("Beta", { userId : "Sam" })

Het functiefilter kan profiteren van de context die wordt doorgegeven wanneer isEnabled wordt aangeroepen. De toepassingscontext wordt doorgegeven als de tweede parameter van IFeatureFilter.Evaluate.

Ingebouwde functiefilters

Er zijn twee functiefilters die bij het FeatureManagement pakket worden geleverd: TimeWindowFilter en TargetingFilter. Alle ingebouwde functiefilters worden standaard toegevoegd bij het FeatureManagermaken.

Elk van de ingebouwde functiefilters heeft zijn eigen parameters. Hier volgt een lijst met functiefilters, samen met voorbeelden.

Microsoft.TimeWindow

Dit filter biedt de mogelijkheid om een functie in te schakelen op basis van een tijdvenster. Als alleen End wordt opgegeven, wordt de functie tot die tijd ingeschakeld. Als alleen Start wordt opgegeven, wordt de functie op alle punten na die tijd als ingeschakeld beschouwd.

"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

Dit filter biedt de mogelijkheid om een functie in te schakelen voor een doelgroep. Een uitgebreide uitleg van targeting wordt uitgelegd in de onderstaande sectie over targeting . De filterparameters bevatten een Audience object dat gebruikers, groepen, uitgesloten gebruikers/groepen en een standaardpercentage van de gebruikersbasis beschrijft die toegang tot de functie moet hebben. Elk groepsobject dat in de Groups sectie wordt vermeld, moet ook opgeven welk percentage van de leden van de groep toegang moet hebben. Als een gebruiker is opgegeven in de Exclusion sectie, rechtstreeks of als de gebruiker zich in een uitgesloten groep bevindt, is de functie uitgeschakeld. Als een gebruiker direct is opgegeven in het Users-gedeelte, of als de gebruiker zich in het inbegrepen percentage van een van de groep-rollouts bevindt, of als de gebruiker in het standaard-uitrolpercentage valt, wordt de functie bij die gebruiker ingeschakeld.

"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"
                    ]
                }
            }
        }
    }
]

Doelgroepenbenadering

Targeting is een functiebeheerstrategie waarmee ontwikkelaars geleidelijk nieuwe functies kunnen implementeren voor hun gebruikers. De strategie is gebaseerd op het concept van het richten van een set gebruikers die bekend staan als de doelgroep. Een doelgroep bestaat uit specifieke gebruikers, groepen, uitgesloten gebruikers/groepen en een aangewezen percentage van het gehele gebruikersbestand. De groepen die in de doelgroep zijn opgenomen, kunnen verder worden onderverdeeld in percentages van hun totale leden.

In de volgende stappen ziet u een voorbeeld van een progressieve implementatie voor een nieuwe bètafunctie:

1. Individuele gebruikers Jeff en Alicia krijgen toegang tot de bètaversie.
2. Een andere gebruiker, Mark, vraagt om zich aan te melden en wordt toegevoegd.
3. Twintig procent van een groep die bekend staat als Ring1-gebruikers, worden opgenomen in de bètaversie.
4. Het aantal ring1-gebruikers dat in de bètaversie is opgenomen, wordt tot 100 procent opgestoten.
5. Vijf procent van de gebruikersbasis is opgenomen in de bètaversie.
6. Het implementatiepercentage wordt verhoogd naar 100 procent en de functie wordt volledig uitgerold.

Deze strategie voor het implementeren van een functie is ingebouwd in de bibliotheek via het opgenomen microsoft.targeting-functiefilter .

Een gebruiker gericht benaderen met targetcontext

Het doelfilter is afhankelijk van een doelcontext om te evalueren of een functie moet worden ingeschakeld. Deze doelcontext bevat informatie zoals welke gebruiker momenteel wordt geëvalueerd en in welke groepen de gebruiker zich bevindt. De targetingcontext moet rechtstreeks worden doorgegeven wanneer isEnabled wordt aangeroepen.

featureManager.isEnabled("Beta", { userId: "Aiden", groups: ["Ring1"] })

Doelgerichte uitsluiting

Bij het definiëren van een doelgroep kunnen gebruikers en groepen worden uitgesloten van de doelgroep. Uitsluitingen zijn handig wanneer een functie wordt geïmplementeerd voor een groep gebruikers, maar een paar gebruikers of groepen moeten worden uitgesloten van de implementatie. Uitsluiting wordt gedefinieerd door een lijst met gebruikers en groepen toe te voegen aan de Exclusion eigenschap van de doelgroep.

"Audience": {
    "Users": [
        "Jeff",
        "Alicia"
    ],
    "Groups": [
        {
            "Name": "Ring0",
            "RolloutPercentage": 100
        }
    ],
    "DefaultRolloutPercentage": 0,
    "Exclusion": {
        "Users": [
            "Mark"
        ]
    }
}

In het bovenstaande voorbeeld is de functie ingeschakeld voor gebruikers met de naam Jeff en Alicia. Het is ook ingeschakeld voor gebruikers in de groep met de naam Ring0. Als de gebruiker echter de naam Markheeft, is de functie uitgeschakeld, ongeacht of deze zich in de groep bevinden Ring0 of niet. Uitsluitingen hebben voorrang op de rest van het doelfilter.

Targeting in een webtoepassing

Een voorbeeld van een webtoepassing die gebruikmaakt van het doelfunctiefilter is beschikbaar in dit voorbeeldproject .

In webtoepassingen, met name die met meerdere onderdelen of lagen, kan het doorgeven van doelcontext (userId en groups) aan elke functievlagcontrole omslachtig en herhalend worden. Dit scenario wordt 'omgevingsgerichte context' genoemd, waarbij de gebruikersidentiteitsgegevens al beschikbaar zijn in de toepassingscontext (zoals in sessiegegevens of verificatiecontext), maar toegankelijk moeten zijn voor evaluaties van functiebeheer in de hele toepassing.

ITargetingContextAccessor

De bibliotheek biedt een oplossing via het ITargetingContextAccessor patroon.

interface ITargetingContext {
    userId?: string;
    groups?: string[];
}

interface ITargetingContextAccessor {
    getTargetingContext: () => ITargetingContext | undefined;
}

In plaats van de doelcontext expliciet door te geven aan elke isEnabled of getVariant aanroep, kunt u een functie opgeven die weet hoe de doelgegevens van de huidige gebruiker moeten worden opgehaald uit de context van uw toepassing:

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");

Dit patroon is met name nuttig in webtoepassingen aan de serverzijde, waarbij gebruikerscontext mogelijk beschikbaar is in een aanvraagbereik of in clienttoepassingen waar de gebruikersidentiteit centraal wordt beheerd.

AsyncLocalStorage gebruiken voor aanvraagcontext

Een veelvoorkomende uitdaging bij het implementeren van het patroon voor toegang tot de doelcontext is het behouden van de verzoekcontext in een asynchrone oproepketen. In Node.js webtoepassingen zijn gebruikersidentiteitsgegevens doorgaans beschikbaar in het aanvraagobject, maar zijn ze niet toegankelijk zodra u asynchrone bewerkingen invoert.

Node.js biedt AsyncLocalStorage uit de async_hooks module aan om dit probleem op te lossen. Er wordt een opslag gecreëerd die gevast blijft tussen asynchrone bewerkingen binnen dezelfde logische 'context' - perfect voor het onderhouden van verzoekgegevens gedurende de hele levenscyclus van het verzoek.

U kunt als volgt een doelcontexttoegangsfunctie implementeren met behulp van AsyncLocalStorage in een express-toepassing:

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 = requestAccesor.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 || []
        };
    }
};

Varianten

Wanneer er nieuwe functies aan een toepassing worden toegevoegd, kan het gebeuren dat een functie meerdere verschillende voorgestelde ontwerpopties heeft. Een algemene oplossing voor het bepalen van een ontwerp is een vorm van A/B-tests, waarbij een andere versie van de functie moet worden verstrekt aan verschillende segmenten van de gebruikersbasis en een versie wordt gekozen op basis van gebruikersinteractie. In deze bibliotheek is deze functionaliteit ingeschakeld door verschillende configuraties van een functie met varianten weer te geven.

Met varianten kan een functievlag meer worden dan een eenvoudige aan/uit-vlag. Een variant vertegenwoordigt een waarde van een functievlag die een tekenreeks, een getal, een Booleaanse waarde of zelfs een configuratieobject kan zijn. Een functievlag die varianten declareert, moet definiëren onder welke omstandigheden elke variant moet worden gebruikt, wat uitgebreider wordt behandeld in de sectie Varianten toewijzen .

Een variant verkrijgen met gerichte context

Voor elke functie kan een variant worden opgehaald met behulp van de FeatureManagermethode.getVariant De varianttoewijzing is afhankelijk van de gebruiker die momenteel wordt geëvalueerd en die informatie wordt verkregen uit de doelcontext die u hebt doorgegeven. Als u een doelcontexttoegangsfunctie hebt geregistreerd bij de FeatureManager, wordt de doelcontext automatisch daaruit opgehaald. U kunt deze echter nog steeds overschrijven door de doelcontext handmatig door te geven bij het aanroepen 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

Declaratie van variantfunctievlag

In vergelijking met normale functievlagmen hebben variantfunctievlagmen nog twee eigenschappen: variants en allocation. De variants eigenschap is een matrix die de varianten bevat die voor deze functie zijn gedefinieerd. De allocation eigenschap definieert hoe deze varianten moeten worden toegewezen voor de functie. Net als bij het declareren van normale functievlagmen kunt u variantfunctievlagmen instellen in een JSON-bestand. Hier volgt een voorbeeld van een vlag voor een variantfunctie.

{
    "feature_management": {
        "feature_flags": [
            {
                "id": "MyVariantFeatureFlag",
                "enabled": true,
                "allocation": {
                    "default_when_enabled": "Small",
                    "group": [
                        {
                            "variant": "Big",
                            "groups": [
                                "Ring1"
                            ]
                        }
                    ]
                },
                "variants": [
                    { 
                        "name": "Big"
                    },  
                    { 
                        "name": "Small"
                    } 
                ]
            }
        ]
    }
}

Varianten definiëren

Elke variant heeft twee eigenschappen: een naam en een configuratie. De naam wordt gebruikt om te verwijzen naar een specifieke variant en de configuratie is de waarde van die variant. De configuratie kan worden ingesteld met behulp van configuration_value de eigenschap. configuration_value is een inlineconfiguratie die een tekenreeks, getal, Booleaanse waarde of configuratieobject kan zijn. Als configuration_value niet is opgegeven, is de eigenschap configuration van de geretourneerde variant undefined.

Er wordt een lijst met alle mogelijke varianten gedefinieerd voor elke functie onder de variants eigenschap.

{
    "feature_management": {
        "feature_flags": [
            {
                "id": "MyVariantFeatureFlag",
                "variants": [
                    { 
                        "name": "Big", 
                        "configuration_value": {
                            "Size": 500
                        }
                    },  
                    { 
                        "name": "Small", 
                        "configuration_value": {
                            "Size": 300
                        }
                    } 
                ]
            }
        ]
    }
}

Varianten toewijzen

Het proces voor het toewijzen van de varianten van een functie wordt bepaald door de allocation eigenschap van de functie.

"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"
    } 
]

De allocation instelling van een functie heeft de volgende eigenschappen:

Als de functie niet is ingeschakeld, wijst de functiebeheerder de variant toe die is gemarkeerd als default_when_disabled de huidige gebruiker, wat in dit geval het geval is Small .

Als de functie is ingeschakeld, controleert de functiebeheerder de user, group en percentile toewijzingen in die volgorde om een variant toe te wijzen. Als in dit specifieke voorbeeld de gebruiker die wordt geëvalueerd de naam Marshaheeft, in de groep met de naam Ring1of als de gebruiker tussen het 0 en 10e percentiel valt, wordt de opgegeven variant toegewezen aan de gebruiker. In dit geval retourneren alle toegewezen gebruikers de Big variant. Als geen van deze toewijzingen overeenkomt, krijgt de gebruiker de default_when_enabled variant toegewezen.Small

Toewijzingslogica is vergelijkbaar met het functiefilter Microsoft.Targeting , maar er zijn enkele parameters die aanwezig zijn in targeting die niet in toewijzing zijn en omgekeerd. De resultaten van targeting en toewijzing zijn niet gerelateerd.

Ingeschakelde status overschrijven met een variant

U kunt varianten gebruiken om de ingeschakelde status van een functievlag te overschrijven. Overschrijven biedt varianten de mogelijkheid om de evaluatie van een functievlag uit te breiden. Wanneer u een vlag met varianten aanroept is_enabled , controleert de functiebeheerder of de variant die is toegewezen aan de huidige gebruiker is geconfigureerd om het resultaat te overschrijven. Het overschrijven wordt uitgevoerd met behulp van de optionele varianteigenschap status_override. Deze eigenschap is standaard ingesteld op None, wat betekent dat de variant niet van invloed is op het feit of de vlag wordt beschouwd als ingeschakeld of uitgeschakeld. Door status_override in te stellen op Enabled, kan de variant, indien gekozen, een in te schakelen vlag overschrijven. Instellen van status_override op Disabled biedt de tegenovergestelde functionaliteit, waardoor de vlag wordt uitgeschakeld wanneer de variant wordt gekozen. Een eigenschap met een enabled status van false kan niet worden overschreven.

Als u een functievlag met binaire varianten gebruikt, kan de status_override eigenschap handig zijn. Hiermee kunt u API's blijven gebruiken, zoals is_enabled in uw toepassing, terwijl u profiteert van de nieuwe functies die worden geleverd met varianten, zoals percentieltoewijzing en seed.

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

In het bovenstaande voorbeeld is de functie altijd ingeschakeld. Als de huidige gebruiker zich in het berekende percentielbereik van 10 tot 20 bevindt, wordt de On variant geretourneerd. Anders wordt de Off variant geretourneerd en omdat status_override deze gelijk is aan Disabled, wordt de functie nu als uitgeschakeld beschouwd.

Telemetrie

Wanneer een wijziging van een functievlag wordt geïmplementeerd, is het vaak belangrijk om het effect ervan op een toepassing te analyseren. Hier volgen bijvoorbeeld enkele vragen die zich kunnen voordoen:

• Zijn mijn vlaggen ingeschakeld/uitgeschakeld zoals verwacht?
• Krijgen doelgebruikers toegang tot een bepaalde functie zoals verwacht?
• Welke variant ziet een bepaalde gebruiker?

Deze typen vragen kunnen worden beantwoord door middel van de verzending en analyse van evaluatiegebeurtenissen van functievlaggen.

Telemetrie inschakelen

Standaard worden er geen telemetriegegevens verzonden voor functievlagmen. Als u telemetrie voor een bepaalde functievlag wilt publiceren, moet de vlag aangeven dat deze is ingeschakeld voor telemetrie-emissie.

Voor functievlagmen die zijn gedefinieerd in json, wordt het inschakelen uitgevoerd met behulp van de telemetry eigenschap.

{
    "feature_management": {
        "feature_flags": [
            {
                "id": "MyFeatureFlag",
                "enabled": true,
                "telemetry": {
                    "enabled": true
                }
            }
        ]
    }
}

Het bovenstaande codefragment definieert een functievlag met de naam MyFeatureFlag die is ingeschakeld voor telemetrie. De telemetry eigenschap van het enabled object is ingesteld op true. De waarde van de enabled eigenschap moet zijn true om telemetriegegevens voor de vlag te publiceren.

De telemetry sectie van een functievlag heeft de volgende eigenschappen:

Publicatie van aangepaste telemetrie

U kunt een onFeatureEvaluated callback-functie registreren bij het maken FeatureManager. Deze callback wordt aangeroepen wanneer een functievlag wordt geëvalueerd en telemetrie voor die vlag is ingeschakeld. De callback-functie neemt het functie-evaluatieresultaat als de parameter.

In het volgende voorbeeld ziet u hoe u een aangepaste callback-functie implementeert om telemetrie te verzenden met de informatie die is geëxtraheerd uit het resultaat van de functie-evaluatie en deze te registreren bij de functiebeheerder.

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});

Application Insights-integratie

De JavaScript-bibliotheek voor functiebeheer biedt uitbreidingspakketten die kunnen worden geïntegreerd met Application Insights SDK's.

Application Insights biedt verschillende SDK's voor web - en Node.js-scenario's . Selecteer de juiste extensiepakketten voor uw toepassing.

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"});

const appInsights = require("applicationinsights");
appInsights.setup(process.env.APPINSIGHTS_CONNECTION_STRING).start();

const { FeatureManager, ConfigurationObjectFeatureFlagProvider } = require("@microsoft/feature-management");
const { createTelemetryPublisher, trackEvent } = require("@microsoft/feature-management-applicationinsights-node");

const publishTelemetry = createTelemetryPublisher(appInsights.defaultClient);
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.defaultClient, "<TARGETING_ID>", {name: "TestEvent",  properties: {"Tag": "Some Value"}});

De telemetrie-uitgever verzendt FeatureEvaluation aangepaste gebeurtenissen naar Application Insights wanneer een functievlag die is ingeschakeld met telemetrie wordt geëvalueerd. De aangepaste gebeurtenis volgt de FeatureEvaluationEvent schema.

Telemetrieprocessor richten

Als u hebt geïmplementeerd ITargetingContextAccessor, kunt u de ingebouwde Application Insights-telemetrieprocessor gebruiken om automatisch doel-id-gegevens aan alle telemetriegegevens toe te voegen door de createTargetingTelemetryProcessor functie aan te roepen.

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)
);

Dit zorgt ervoor dat elk telemetrie-item dat naar Application Insights wordt verzonden, de doel-id-informatie van de gebruiker (userId en groepen) bevat, zodat u het gebruik van functievlagken kunt correleren met specifieke gebruikers of groepen in uw analyse.

Als u de doeltelemetrieprocessor gebruikt in plaats van de trackEvent methode aan te roepen die wordt geleverd door het functiebeheerpakket, kunt u de trackEvent methode rechtstreeks aanroepen vanuit de Application Insights SDK. De informatie over de doel-id wordt automatisch gekoppeld aan de customDimensions telemetriegegevens van de aangepaste gebeurtenis.

// 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" });

Volgende stappen

Als u wilt weten hoe u functievlagmen in uw toepassingen gebruikt, gaat u verder met de volgende quickstarts.

Als u wilt weten hoe u functiefilters gebruikt, gaat u verder met de volgende zelfstudies.