JavaScript 機能の管理

JavaScript 機能管理ライブラリでは、機能フラグに基づいてアプリケーション機能を開発および公開する方法が提供されます。 新しい機能が開発されると、多くのアプリケーションでは、その機能を有効にすべきタイミングや、有効にすべきタイミングなど、特別な要件が発生します。 このライブラリでは、これらの関係を定義する方法が提供され、これらの機能を公開できるようにするために、一般的な JavaScript コード パターンに統合されています。

機能フラグでは、JavaScript アプリケーションで機能を動的にオンまたはオフにする方法が提供されます。 開発者は、条件付きステートメントのように簡単なユース ケースで機能フラグを使用できます。

JavaScript 機能管理ライブラリを使用するメリットを次に示します。

• 機能管理のための一般的な規則
• 参入障壁の低さ
  • JSON オブジェクトとマップ ベースの機能フラグ ソースの両方をサポート
  • Node.js環境とブラウザー環境の両方での使用をサポート
• Azure App Configuration を使用した機能フラグの有効期間管理
  • 構成値はリアルタイムで変更される可能性があります
• シンプルなシナリオから複雑なシナリオまで対応
  • 宣言型構成ファイルを通じた機能のオン/オフの切り替え
  • サーバーへの呼び出しに基づいて機能の状態を動的に評価

JavaScript 機能管理ライブラリはオープン ソースです。 詳細については、GitHub リポジトリを参照してください。

Note

機能管理ライブラリを Azure App Configuration と共に使用することをお勧めします。 Azure App Configuration には、アプリケーション設定と機能フラグを一元的に管理するためのソリューションが用意されています。 詳細については、このセクションを参照してください。

機能フラグ

機能フラグは、名前と、機能をオンにするための機能フィルターの一覧の 2 つで構成されます。

機能フィルター

機能フィルターは、機能を有効にする必要があるシナリオを定義します。 機能がオンかオフか評価される場合に、機能フィルターの一覧は、いずれかのフィルターがその機能を有効にする必要があると決定するまで走査されます。 この時点で、その機能は有効であるとみなされ、機能フィルターの走査は停止します。 どの機能フィルターも機能を有効にすることを示していない場合は、無効とみなされます。

例として、Microsoft Edge ブラウザーの機能フィルターを設計できます。 この機能フィルターは、HTTP 要求が Microsoft Edge から派生したものである限り、そのフィルターに接続されているすべての機能をアクティブにします。

機能フラグの構成

JavaScript では、開発者は通常、構成を表す主要なデータ構造としてオブジェクトまたはマップを使用します。 JavaScript 機能管理ライブラリでは、両方の構成方法がサポートされ、開発者はニーズに最適なオプションを柔軟に選択できます。 FeatureManager は、組み込みの ConfigurationObjectFeatureFlagProvider と 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);

オブジェクトは、JSON ファイルから解析することもできます。

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

Azure App Configuration の機能フラグを使用する

機能フラグはアプリケーションにハード コーディングするのではなく、アプリケーションの外部で保持し、別々に管理することをお勧めします。 そうすることで、フラグの状態をいつでも変更して、アプリケーションにその変更をすぐに反映させることができます。 Azure App Configuration サービスには、すべての機能フラグを管理できる専用のポータル UI が用意されています。 「チュートリアル」を参照してください。

また、Azure App Configuration サービスは、その JavaScript クライアント ライブラリ @azure/app-configuration-provider を介して直接、お使いのアプリケーションに機能フラグを配信します。 次の例は、ライブラリの使用方法を示しています。

App Configuration JavaScript プロバイダーは、Map オブジェクトに機能フラグを提供します。 この場合、組み込みの ConfigurationMapFeatureFlagProvider は機能フラグを読み込むのに役立ちます。

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

Note

Azure App Configuration で機能管理ライブラリを使用する方法の詳細については、「クイック スタート」を参照してください。

機能フラグの宣言

次の例は、JSON ファイルで機能フラグを設定するために使用される形式を示しています。

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

feature_management セクションが機能フラグ設定を読み込むための慣例によって使用されます。 feature_flags セクションは、ライブラリに読み込まれる機能フラグの一覧です。 上記のセクションでは、3 つの異なる機能が見られます。 機能は、conditions の内部の client_filters プロパティを使用して機能フィルターを定義します。 FeatureT の機能フィルターでは、フィルターが定義されずに enabled が true になっているので、常に FeatureT が true を返すことがわかります。 FeatureU は FeatureT と同じですが、enabled では false になり、機能が常に false を返します。 FeatureV は、Microsoft.TimeWindow という名前の機能フィルターを指定します。 FeatureV は構成可能な機能フィルターの例です。 フィルターに parameters プロパティがある例で確認できます。 parameters プロパティは、フィルターの構成に使用されます。 この場合、機能がアクティブになる開始時間と終了時間が構成されます。

feature_management セクションの詳細なスキーマはこちらで見つけることができます。

詳細設定: 機能フラグ名でのコロン ':' の使用は禁止されています。

要件タイプ

機能フラグの requirement_type プロパティは、フィルターが機能の状態を評価する場合に Any または All ロジックを使用する必要があるかどうかを決定するために使用されます。 requirement_type を指定しない場合の既定値は Any です。

• Any は、1 つのフィルターだけが true と評価されると、その機能が有効になることを意味します。
• All は、機能を有効にするために、すべてのフィルターが true と評価される必要があることを意味します。

All の requirement_type は走査を変更します。 まず、フィルターがない場合、この機能は無効になります。 次に、フィルターのいずれかがその機能を無効にする必要があると判断するまで、機能フィルターが走査されます。 どのフィルターも機能を無効にすることを示していない場合は、有効とみなされます。

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

上記の例では、FeatureW は All の requirement_type を指定します。つまり、その機能を有効にするには、すべてのフィルターが true と評価される必要があります。 この場合、指定された時間枠に 50% のユーザーに対してこの機能が有効になります。

従量課金プラン

機能管理の基本フォームは、機能フラグが有効かどうかを確認し、その結果に基づいてアクションを実行することです。 機能フラグの状態の確認は、FeatureManager の isEnabled メソッドを使用して行われます。

マップ構成の使用

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
}

機能フィルターの実装

機能フィルターを作成すると、定義した条件に基づいて機能を有効にする方法を得られます。 機能フィルターを実装するには、IFeatureFilter インターフェイスを実装する必要があります。 IFeatureFilter には、name プロパティと evaluate という名前のメソッドがあります。 name を構成で使用して、機能フラグ内の機能フィルターを参照する必要があります。 機能が機能フィルターに対して有効であることを指定すると、evaluate メソッドが呼び出されます。 evaluate が true を返す場合は、機能が有効になっていることを意味します。

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

次のスニペットは、名前が MyCriteriaのカスタマイズされた機能フィルターを実装する方法を示しています。

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

FeatureManagerの作成時にカスタム フィルターを登録する必要があります。

const featureManager = new FeatureManager(ffProvider, {customFilters: [new MyCriteriaFilter()]});

パラメーター化機能フィルター

一部の機能フィルターでは、機能をオンにするかどうかを決定するためのパラメーターが必要です。 たとえば、ブラウザー機能フィルターでは、特定のブラウザー セットの機能を有効にすることができます。 Edge およびChrome ブラウザーでは機能を有効にできますが、Firefox ではできません。 これを行うために、パラメーターを予測する機能フィルターを設計できます。 これらのパラメーターは機能構成で指定され、IFeatureFilter.Evaluate の IFeatureFilterEvaluationContext パラメーターを介してコードにアクセスできるようになります。

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

IFeatureFilterEvaluationContext には parameters という名前のプロパティがあります。 これらのパラメーターは、機能フィルターが機能を有効にする必要があるか評価する方法を決定するために使用できる生の構成を表します。 ブラウザー機能フィルターをもう一度例として使用するために、フィルターは機能用に指定される許可されたブラウザーのセットを抽出し、要求がそれらのブラウザーのどれかから送信されているか確認するために parameters を使用できます。

機能評価にアプリケーション コンテキストを使用する

機能フィルターでは、機能フラグを評価するためにランタイム アプリケーション コンテキストが必要になる場合があります。 isEnabled を呼び出すときに、コンテキストをパラメーターとして渡すことができます。

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

機能フィルターは isEnabled が呼び出されたときに渡されるコンテキストを活用できます。 アプリケーション コンテキストは、IFeatureFilter.Evaluate の 2 番目のパラメーターとして渡されます。

組み込み機能フィルター

FeatureManagement パッケージには、TimeWindowFilter と TargetingFilter の 2 つの機能フィルターがあります。

組み込み機能フィルターにはそれぞれ独自のパラメーターがあります。 こちらは、機能フィルターの一覧と例です。

Microsoft.TimeWindow

このフィルターは、時間枠に基づいて機能を有効にする機能を提供します。 End のみ指定された場合、その時間までその機能はオンとみなされます。 Start のみ指定された場合、その時点以降のすべての時点で機能はオンとみなされます。

"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

このフィルターは、対象ユーザーに対して機能を有効にする機能を提供します。 対象設定の詳細については、以下の「対象設定」セクションで説明します。 フィルター パラメーターには、ユーザー、グループ、除外ユーザー/グループ、およびその機能にアクセスできるユーザーベースの既定の割合を記述する Audience オブジェクトが含まれます。 Groups セクションに一覧表示されている各グループ オブジェクトは、グループのメンバーの何パーセントがアクセスできるかも指定する必要があります。 ユーザーがExclusion セクションで指定されている場合、そのユーザーが直接指定されている場合、またはそのユーザーが除外されているグループに属している場合に、機能は無効になります。 それ以外の場合、Users セクションでユーザーが直接指定された場合、またはユーザーがいずれかのグループ ロールアウトの割合に含まれる場合、またはユーザーが既定ロールアウトの割合に含まれる場合、そのユーザーの機能が有効になります。

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

ターゲティング

対象設定は、開発者が新しい機能をユーザー ベースに段階的にロールアウトできるようにする機能管理戦略です。 この戦略は、対象ユーザーと呼ばれる一連のユーザーを対象設定するという概念に基づいて構築されています。 対象ユーザーは、特定のユーザー、グループ、除外されたユーザー/グループ、およびユーザー ベース全体の指定された割合で構成されます。 対象ユーザーに含まれるグループは、メンバーの合計数に対する割合にさらに分けることができます。

次の手順は、新しい「ベータ」機能の段階的なロールアウトの例を示しています。

1. 個人ユーザーのジェフとアリシアには、ベータ版へのアクセスが付与されています。
2. 別のユーザーであるマークは、オプトイン要求をして、含まれました。
3. 「Ring1」ユーザーと呼ばれるグループの 20% がベータ版に含まれています。
4. ベータ版に含まれる "Ring1" ユーザーの数は、最大 100% 増加します。
5. ユーザー ベースの 5% がベータ版に含まれています。
6. ロールアウト率は最大 100% まで増加し、機能は完全にロールアウトされます。

機能をロールアウトするこの戦略では、これに含まれる Microsoft.Targeting 機能フィルターを通してライブラリに組み込まれています。

ターゲット コンテキストを使用したユーザーのターゲット設定

対象設定フィルターは、機能をオンにする必要があるか評価するために、ターゲット設定コンテキストに依存します。 この対象設定コンテキストには、現時点でどのユーザーが評価されているか、どのグループに属しているかなどの情報が含まれています。 ターゲット コンテキストは、isEnabled が呼び出されたときに直接渡す必要があります。

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

対象設定の除外

対象ユーザーを定義する場合、ユーザーやグループを対象ユーザーから除外できます。 除外は、ある機能をユーザー グループにロールアウトする場合に、一部のユーザーまたはグループをロールアウトから除外する必要がある場合に役立ちます。 除外は、対象ユーザー Exclusion プロパティにユーザーとグループの一覧を追加することで定義されます。

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

上記の例では、Jeff と Alicia という名前のユーザーに対してこの機能が有効になっています。 また、Ring0 という名前のグループのユーザーに対しても有効です。 ただし、ユーザーの名前が Mark である場合、そのユーザーがグループ Ring0 に属しているかに関係なく、機能は無効になります。 除外は対象設定フィルターの残りの部分よりも優先されます。

バリアント

アプリケーションに新しい機能が追加される場合、その機能に複数の異なる設計オプションがある場合があります。 設計を決定するための一般的な解決策は、一種の A/B テストです。これは、ユーザー ベースの異なるセグメントに機能の異なるバージョンを提供し、ユーザー操作に基づいてバージョンを選択するものです。 このライブラリでは、機能のさまざまな構成をバリアントで表現することで、この機能が有効になります。

バリアントは、機能フラグを単なるオン/オフのフラグ以上のものにします。 バリアントは機能フラグの値を表し、文字列、数値、ブール値、あるいは構成オブジェクトである場合もあります。 バリアントを宣言する機能フラグは、それぞれのバリアントをどのような状況で使用する必要があるかを定義する必要があります。この詳細については、「バリアントの割り当て」セクションで扱っています。

ターゲット コンテキストを使用してバリアントを取得する

各機能について、FeatureManager の 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

バリアント機能フラグの宣言

通常の機能フラグと比較して、バリアント機能フラグには variants と allocation の 2 つの追加プロパティがあります。 variants プロパティは、この機能に対して定義されたバリアントを含む配列です。 allocation プロパティは、これらのバリアントを機能に割り当てる方法を定義します。 通常の機能フラグを宣言するのと同様に、バリアント機能フラグも JSON ファイルで設定できます。 こちらにバリアント機能フラグの例を示します。

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

バリアントの定義

各バリアントには名前と構成の 2 つのプロパティがあります。 名前は特定のバリアントを指すのに使われ、構成はそのバリアントの値です。 この構成は configuration_value プロパティを使用して設定できます。 configuration_value は、文字列、数値、論理値、構成オブジェクトのいずれかに設定できるインライン構成です。 configuration_value が指定されていない場合は、返されたバリアントの configuration プロパティは undefined になります。

variants プロパティの下で、各機能に対して利用可能なすべてのバリアントのリストが定義されます。

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

バリアントの割り当て

機能のバリアントを割り当てるプロセスは、機能の allocation プロパティによって決定されます。

"allocation": { 
    "default_when_enabled": "Small", 
    "default_when_disabled": "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"
    } 
]

機能の allocation 設定には次のプロパティがあります。

プロパティ	説明
default_when_disabled	機能が無効とされている間にバリアントが要求された場合に使用するバリアントを指定します。
default_when_enabled	機能が有効であるとみなされ、他のバリアントがユーザーに割り当てられていない場合に、バリアントが要求されたときに使用するバリアントを指定します。
user	バリアントと、そのバリアントを割り当てるユーザーの一覧を指定します。
group	バリアントとグループの一覧を指定します。 バリアントは、ユーザーが少なくとも 1 つのグループに属している場合に割り当てられます。
percentile	バリアントと、そのバリアントを割り当てるためにユーザーの計算されたパーセンテージの範囲を指定します。
seed	percentile に対して計算されたパーセンテージの基になる値。 同じ seed 値が使用されている場合、特定のユーザーに対して計算されたパーセンテージはすべての機能で同じになります。 seed が指定されていない場合は、機能名に基づく既定のシードが作成されます。

機能が有効になっていない場合は、機能マネージャーは default_when_disabled とマークされたバリアントを現在のユーザー (この場合は Small) に割り当てます。

この機能が有効になっている場合は、機能マネージャーは user、group、percentile の割り当てを順番に確認してバリアントを割り当てます。 この具体的な例では、評価されるユーザーが Marsha という名前で、Ring1 というグループに属する場合、またはユーザーが偶然 0 パーセンタイルと 10 パーセンタイルの間に存在する場合、指定されたバリアントがユーザーに割り当てられます。 この場合、割り当てられたユーザーはすべて Big バリアントを返します。 これらの割り当てがどれも一致しない場合、default_when_enabled のバリアントが割り当てられ、Small になります。

割り当てのロジックは Microsoft.Targeting 機能フィルターと似ていますが、パラメーターには、ターゲット設定に存在するが割り当てに存在しないものや、その逆があります。 対象設定と割り当ての結果は関係ありません。

バリアントを使用する有効な状態のオーバーライド

機能フラグの有効な状態をオーバーライドするためにバリアントを使用できます。 オーバーライドにより、バリアントが機能フラグの評価を拡張する機会が付与されます。 バリアントのあるフラグに対して is_enabled を呼び出すと、機能マネージャーは、現在のユーザーに割り当てられているバリアントが結果をオーバーライドするように構成されているかどうかを調べます。 オーバーライドは、省略可能なバリアント プロパティ status_override を使用して行われます。 既定では、このプロパティは None に設定されており、バリアントはフラグが有効か無効であるかに影響しないことを意味します。 status_override を Enabled に設定すると、バリアントが選択されたときにフラグをオーバーライドして有効にすることができます。 status_override を Disabled に設定すると逆の機能が提供され、バリアントが選択されたときにフラグが無効になります。 enabled 状態が false の機能はオーバーライドできません。

バイナリのバリアントで機能フラグを使用する場合、status_override プロパティが役立ちます。 これにより、アプリケーションで is_enabled のような API を使い続けながら、パーセンタイル割り当てやシードなどのバリアントに付属する新しい機能の恩恵を受けることができます。

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

上記の例では、機能が常に有効になっています。 現在のユーザーが計算されたパーセンタイルの 10 から 20 の範囲にある場合、On バリアントが返されます。 それ以外の場合は、Off バリアントが返され、status_override は Disabled と等しいため、その機能は無効とみなされます。

テレメトリ

機能フラグの変更がデプロイされると、多くの場合、アプリケーションへの影響の分析が重要です。 たとえば、可能性のある質問は次のとおりです。

• 私のフラグは期待どおりに有効または無効になっていますか?
• 対象ユーザーは、期待どおりに特定の機能にアクセスできていますか?
• どのバリアントが特定のユーザーに表示されていますか?

この種の質問には、機能フラグ評価イベントの生成と分析を通じて回答できます。

テレメトリの有効化

既定では、機能フラグにはテレメトリがありません。 指定された機能フラグに対してテレメトリを発行するには、フラグはテレメトリ生成のために有効であることを宣言する "必要があります"。

JSON で定義された機能フラグの場合は、telemetry プロパティを使用して有効化が行われます。

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

上記のスニペットでは、テレメトリを有効にする MyFeatureFlag という名前の機能フラグを定義しています。 telemetry オブジェクトの enabled プロパティは、true に設定されます。 フラグのテレメトリを発行するには、enabled プロパティの値を true にする必要があります。

機能フラグの telemetry セクションには次のプロパティがあります。

プロパティ	説明
enabled	機能フラグに対してテレメトリを発行するかどうかを指定します。
metadata	機能フラグに関するカスタム メタデータを評価イベントに添付するために使用できる、辞書としてモデル化されたキーと値のペアのコレクション

カスタム テレメトリの発行

FeatureManager を作成するときに、onFeatureEvaluated コールバック関数を登録できます。 このコールバックは、機能フラグが評価され、そのフラグに対してテレメトリが有効になっているたびに呼び出されます。 コールバック関数は、機能評価の結果をパラメーターとして受け取ります。

次の例では、カスタム コールバック関数を実装して、機能評価結果から抽出された情報を含むテレメトリを送信し、機能マネージャーに登録する方法を示します。

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 の統合

JavaScript 機能管理ライブラリには、Application Insights SDK と統合する拡張機能パッケージが用意されています。

Application Insights には、Web と Node.js のシナリオ用のさまざまな SDK が用意されています。 アプリケーションに適した拡張機能パッケージを選択してください。

Browser

アプリケーションがブラウザーで実行されている場合は、"@microsoft/feature-management-applicationinsights-browser" パッケージをインストールします。 次の例は、組み込みの Application Insights Telemetry パブリッシャーを作成し、機能マネージャーに登録する方法を示しています。

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

Node.js

アプリケーションが Node.js で実行されている場合は、"@microsoft/feature-management-applicationinsights-node" パッケージをインストールします。 次の例は、組み込みの Application Insights Telemetry パブリッシャーを作成し、機能マネージャーに登録する方法を示しています。

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

テレメトリ パブリッシャーは、テレメトリで有効になっている機能フラグが評価されると、FeatureEvaluation カスタム イベントを Application Insights に送信します。 カスタム イベントは、FeatureEvaluationEvent スキーマに従います。

次のステップ

アプリケーションで機能フラグを使用する方法については、次のクイックスタートに進んでください。

Python

機能フィルターの使用方法について学ぶには、次のチュートリアルに進んでください。

機能フィルターを使用して条件付き機能を有効にする

機能をスケジュールに従って有効にする

対象ユーザーに対して機能をロールアウトする