مشاركة عبر

إدارة ميزات JavaScript

feature-management-npm-package

توفر مكتبة إدارة ميزات JavaScript طريقة لتطوير وظائف التطبيق وعرضها استنادا إلى علامات الميزات. بمجرد تطوير ميزة جديدة، يكون للعديد من التطبيقات متطلبات خاصة، مثل متى يجب تمكين الميزة وتحت أي شروط. توفر هذه المكتبة طريقة لتعريف هذه العلاقات، كما تتكامل مع أنماط التعليمات البرمجية JavaScript الشائعة لجعل الكشف عن هذه الميزات ممكنا.

توفر علامات الميزات طريقة لتطبيقات JavaScript لتشغيل الميزات أو إيقاف تشغيلها ديناميكيا. يمكن للمطورين استخدام علامات الميزات في حالات الاستخدام البسيطة مثل العبارات الشرطية.

فيما يلي بعض فوائد استخدام مكتبة إدارة ميزات JavaScript:

  • اصطلاح مشترك لإدارة الميزات
  • حاجز منخفض أمام الدخول
    • يدعم كل من كائنات JSON ومصادر علامة الميزة المستندة إلى الخريطة
    • يدعم الاستخدام في كل من بيئات Node.js والمستعرض
  • إدارة مدة بقاء علامة الميزة باستخدام Azure App Configuration
    • يمكن أن تتغير قيم التكوين في الوقت الفعلي
  • السيناريوهات البسيطة والمعقدة التي تمت تغطيتها
    • تبديل ميزات التشغيل/إيقاف التشغيل من خلال ملف التكوين التعريفي
    • تقييم حالة الميزة ديناميكيا استنادا إلى استدعاء الخادم

مكتبة إدارة ميزات JavaScript مصدر مفتوح. لمزيد من المعلومات، تفضل بزيارة مستودع GitHub.

إشعار

يوصى باستخدام مكتبة إدارة الميزات مع Azure App Configuration. يوفر Azure App Configuration حلا لإدارة إعدادات التطبيق وعلامات الميزات مركزيا. لمزيد من التفاصيل، يرجى الرجوع إلى هذا القسم.

علامات الميزة

تتكون علامات الميزات من جزأين، اسم وقائمة عوامل تصفية الميزات المستخدمة لتشغيل الميزة.

عوامل تصفية الميزات

تحدد عوامل تصفية الميزات سيناريو لمتى يجب تمكين ميزة. عند تقييم ميزة ما سواء كانت قيد التشغيل أو إيقاف التشغيل، يتم اجتياز قائمة عوامل تصفية الميزات الخاصة بها حتى تقرر إحدى عوامل التصفية أنه يجب تمكين الميزة. عند هذه النقطة، تعتبر الميزة ممكنة ويتوقف اجتيازها من خلال عوامل تصفية الميزة. إذا لم يشير أي عامل تصفية للميزة إلى أنه يجب تمكين الميزة، اعتبارها معطلة.

على سبيل المثال، يمكن تصميم عامل تصفية ميزة مستعرض 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);

استخدام علامات الميزات من Azure App Configuration

بدلاً من ترميز علامات الميزة في التطبيق الخاص بك، نوصي بالاحتفاظ بعلامات الميزات خارج التطبيق وإدارتها بشكل منفصل. يسمح لك القيام بذلك بتعديل حالات العلامة في أي وقت ويكون لهذه التغييرات تأثير في التطبيق على الفور. توفر خدمة تكوين Azure App واجهة مستخدم مخصصة لبوابة إلكترونية لإدارة كافة علامات الميزات. راجع البرنامج التعليمي.

توفر خدمة Azure App Configuration أيضا علامات الميزة إلى تطبيقك مباشرة من خلال مكتبة عميل JavaScript الخاصة بها @azure/app-configuration-provider. يوضح المثال التالي كيفية استخدام المكتبة.

يوفر موفر 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);

استخدام Azure App Configuration للتحكم ديناميكيا في حالة علامة الميزة

Azure App Configuration ليس فقط حلا لإضفاء الطابع الخارجي على التخزين والإدارة المركزية لعلامات الميزات الخاصة بك، ولكنه يسمح لك أيضا بتشغيل/إيقاف تشغيل علامات الميزات ديناميكيا.

لتمكين التحديث الديناميكي لعلامات الميزات، تحتاج إلى تكوين refresh خاصية featureFlagOptions عند تحميل علامات الميزة من 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);

تحتاج إلى استدعاء refresh الأسلوب للحصول على أحدث حالة علامة ميزة.

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

إشعار

لمزيد من المعلومات حول كيفية استخدام مكتبة إدارة الميزات مع 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 عبارة عن قائمة بعلامات الميزات التي يتم تحميلها في المكتبة. في القسم أعلاه، نرى ثلاث ميزات مختلفة. تحدد الميزات عوامل تصفية الميزات الخاصة بها باستخدام الخاصية client_filters ، داخل conditions. في عوامل تصفية الميزات ل 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 يعني أن عامل تصفية واحدا فقط يحتاج إلى التقييم إلى true حتى يتم تمكين الميزة.
  • All يعني أن كل عامل تصفية يحتاج إلى تقييم إلى صحيح لتمكين الميزة.

A requirement_type من All التغييرات التي يتم اجتيازها. أولا، إذا لم تكن هناك عوامل تصفية، يتم تعطيل الميزة. بعد ذلك، يتم اجتياز عوامل تصفية الميزة حتى تقرر إحدى عوامل التصفية أنه يجب تعطيل الميزة. إذا لم يشير أي عامل تصفية إلى أنه يجب تعطيل الميزة، اعتبارها ممكنة.

{
    "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 يحدد من requirement_typeAll، مما يعني أنه يجب تقييم جميع عوامل التصفية الخاصة به إلى 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
}

تنفيذ عامل تصفية ميزة

يوفر إنشاء عامل تصفية ميزات طريقة لتمكين الميزات استنادا إلى المعايير التي تحددها. لتنفيذ عامل تصفية ميزة، يجب تنفيذ الواجهة 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;
            }
        }
    }

تحتاج إلى تسجيل عامل التصفية المخصص ضمن customFilters خاصية الكائن الذي FeatureManagerOptions تم تمريره إلى الدالة FeatureManager الإنشائية.

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

عوامل تصفية الميزات ذات المعلمات

تتطلب بعض عوامل تصفية الميزات معلمات لتحديد ما إذا كان يجب تشغيل ميزة أم لا. على سبيل المثال، قد يقوم عامل تصفية ميزة المستعرض بتشغيل ميزة لمجموعة معينة من المستعرضات. قد يكون من المرغوب فيه أن تقوم مستعرضات Edge وChrome بتمكين ميزة، بينما لا يقوم Firefox بذلك. للقيام بذلك، يمكن تصميم عامل تصفية ميزة لتوقع المعلمات. سيتم تحديد هذه المعلمات في تكوين الميزة، وفي التعليمات البرمجية يمكن الوصول إليها عبر معلمة IFeatureFilterEvaluationContextIFeatureFilter.Evaluate.

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

IFeatureFilterEvaluationContext لديه خاصية تسمى parameters. تمثل هذه المعلمات تكوينا أوليا يمكن لعامل تصفية الميزة استخدامه لتحديد كيفية تقييم ما إذا كان يجب تمكين الميزة أم لا. لاستخدام عامل تصفية ميزة المستعرض كمثال مرة أخرى، يمكن استخدام parameters عامل التصفية لاستخراج مجموعة من المستعرضات المسموح بها التي سيتم تحديدها للميزة ثم التحقق مما إذا كان يتم إرسال الطلب من أحد هذه المستعرضات.

استخدام سياق التطبيق لتقييم الميزات

قد يحتاج عامل تصفية الميزة إلى سياق تطبيق وقت التشغيل لتقييم علامة ميزة. يمكنك تمرير في السياق كمعلمة عند استدعاء isEnabled.

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

يمكن لعامل تصفية الميزة الاستفادة من السياق الذي يتم تمريره عند isEnabled استدعاؤه. سيتم تمرير سياق التطبيق كمعلمة ثانية ل IFeatureFilter.Evaluate.

عوامل تصفية الميزات المضمنة

هناك عاملا تصفية ميزة تأتي مع الحزمة FeatureManagement : TimeWindowFilter و TargetingFilter. ستتم إضافة جميع عوامل تصفية الميزات المضمنة بشكل افتراضي عند إنشاء FeatureManager.

كل عامل من عوامل تصفية الميزات المضمنة له معلماته الخاصة. فيما يلي قائمة عوامل تصفية الميزات جنبا إلى جنب مع الأمثلة.

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

يمكن تكوين النافذة الزمنية للتكرار بشكل دوري. يمكن أن يكون هذا مفيدا للسيناريوهات التي قد يحتاج فيها المرء إلى تشغيل ميزة خلال فترة حركة مرور منخفضة أو عالية في يوم أو أيام معينة من الأسبوع. لتوسيع النافذة الزمنية الفردية إلى النوافذ الزمنية المتكررة، يجب تحديد قاعدة التكرار في المعلمة Recurrence .

إشعار

Start ويجب End أن يكون كلاهما محددا لتمكين Recurrence.

"client_filters": [
    {
        "name": "Microsoft.TimeWindow",
        "parameters": {
            "Start": "Fri, 22 Mar 2024 20:00:00 GMT",
            "End": "Sat, 23 Mar 2024 02:00:00 GMT",
            "Recurrence": {
                "Pattern": {
                    "Type": "Daily",
                    "Interval": 1
                },
                "Range": {
                    "Type": "NoEnd"
                }
            }
        }
    }
]

تتكون الإعدادات Recurrence من جزأين: Pattern (عدد المرات التي تتكرر فيها النافذة الزمنية) و Range (إلى متى يتكرر نمط التكرار).

نمط التكرار

هناك نوعان محتملان من أنماط التكرار: Daily و Weekly. على سبيل المثال ، يمكن أن تتكرر النافذة الزمنية "كل يوم" أو "كل ثلاثة أيام" أو "كل يوم اثنين" أو "كل يوم جمعة".

اعتمادا على النوع ، تكون حقول معينة مطلوبة Pattern أو اختيارية أو يتم تجاهلها.

  • Daily

    يتسبب نمط التكرار اليومي في تكرار النافذة الزمنية بناء على عدد الأيام بين كل تكرار.

    الخاصية الصلة ‏‏الوصف
    النوع مطلوبة يجب تعيينه إلى Daily.
    الفترة اختيارية يحدد عدد الأيام بين كل تكرار. القيمة الافتراضية هي 1.

  • Weekly

    يتسبب نمط التكرار الأسبوعي في تكرار النافذة الزمنية في نفس اليوم أو أيام الأسبوع ، بناء على عدد الأسابيع بين كل مجموعة من التكرارات.

    الخاصية الصلة ‏‏الوصف
    النوع مطلوبة يجب تعيينه إلى Weekly.
    أيام الأسبوع مطلوبة يحدد أيام الأسبوع التي يحدث فيها الحدث.
    الفترة اختيارية يحدد عدد الأسابيع بين كل مجموعة من التكرارات. القيمة الافتراضية هي 1.
    أول يوم من الأسبوع اختيارية يحدد اليوم الذي يعتبر اليوم الأول من الأسبوع. القيمة الافتراضية هي Sunday.

    يكرر المثال التالي النافذة الزمنية كل اثنين وثلاثاء

    "Pattern": {
    "Type": "Weekly",
    "Interval": 2,
    "DaysOfWeek": ["Monday", "Tuesday"]
}

إشعار

Start يجب أن يكون أول تكرار صالح يناسب نمط التكرار. بالإضافة إلى ذلك، لا يمكن أن تكون مدة النافذة الزمنية أطول من عدد مرات حدوثها. على سبيل المثال، من غير الصالح تكرار نافذة زمنية مدتها 25 ساعة كل يوم.

نطاق التكرار

هناك ثلاثة أنواع محتملة من نطاقات التكرار: NoEnd، EndDate و Numbered.

  • NoEnd

    يتسبب النطاق NoEnd في حدوث التكرار إلى أجل غير مسمى.

    الخاصية الصلة ‏‏الوصف
    النوع مطلوبة يجب تعيينه إلى NoEnd.

  • EndDate

    يتسبب النطاق EndDate في حدوث النافذة الزمنية في جميع الأيام التي تتناسب مع النمط القابل للتطبيق حتى تاريخ الانتهاء.

    الخاصية الصلة ‏‏الوصف
    النوع مطلوبة يجب تعيينه إلى EndDate.
    تاريخ الانتهاء مطلوبة يحدد التاريخ والوقت لإيقاف تطبيق النمط. طالما أن وقت بدء الحدوث الأخير يقع قبل تاريخ الانتهاء، يسمح لوقت انتهاء هذا الحدوث بالامتداد إلى ما بعده.

    سيكرر المثال التالي النافذة الزمنية كل يوم حتى يحدث آخر تكرار في 1 أبريل 2024.

    "Start": "Fri, 22 Mar 2024 18:00:00 GMT",
"End": "Fri, 22 Mar 2024 20:00:00 GMT",
"Recurrence":{
    "Pattern": {
        "Type": "Daily",
        "Interval": 1
    },
    "Range": {
        "Type": "EndDate",
        "EndDate": "Mon, 1 Apr 2024 20:00:00 GMT"
    }
}

  • Numbered

    يتسبب النطاق Numbered في حدوث النافذة الزمنية لعدد محدد من المرات (بناء على النمط).

    الخاصية الصلة ‏‏الوصف
    النوع مطلوبة يجب تعيينه إلى Numbered.
    NumberOfOccurrences مطلوبة يحدد عدد مرات التكرار.

    سيكرر المثال التالي النافذة الزمنية يومي الاثنين والثلاثاء حتى تكون هناك ثلاث حالات ، والتي تحدث على التوالي في 1 أبريل (الاثنين) و 2 أبريل (الثلاثاء) و 8 أبريل (الإثنين).

    "Start": "Mon, 1 Apr 2024 18:00:00 GMT",
"End": "Mon, 1 Apr 2024 20:00:00 GMT",
"Recurrence":{
    "Pattern": {
        "Type": "Weekly",
        "Interval": 1,
        "DaysOfWeek": ["Monday", "Tuesday"]
    },
    "Range": {
        "Type": "Numbered",
        "NumberOfOccurrences": 3
    }
}

لإنشاء قاعدة تكرار، يجب تحديد كلا Pattern من و Range. يمكن أن يعمل أي نوع نمط مع أي نوع نطاق.

متقدم: يتم تطبيق إزاحة المنطقة الزمنية للخاصية Start على إعدادات التكرار.

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. يتم منح المستخدمين الفرديين Jeff و Alicia حق الوصول إلى Beta.
  2. يطلب مستخدم آخر، Mark، الاشتراك ويتم تضمينه.
  3. يتم تضمين 20 بالمائة من مجموعة تعرف باسم مستخدمي "Ring1" في الإصدار التجريبي.
  4. عدد المستخدمين "Ring1" المضمنين في Beta يصل إلى 100 بالمائة.
  5. يتم تضمين خمسة بالمائة من قاعدة المستخدم في Beta.
  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 أم لا. تأخذ الاستثناءات الأولوية على بقية عامل تصفية الاستهداف.

الاستهداف في تطبيق ويب

يتوفر مثال لتطبيق ويب يستخدم عامل تصفية ميزة الاستهداف في مشروع المثال هذا.

في تطبيقات الويب، خاصة تلك التي تحتوي على مكونات أو طبقات متعددة، يمكن أن يصبح تمرير سياق الاستهداف (userId و groups) إلى كل فحص علامة ميزة مرهقا ومتكررا. يشار إلى هذا السيناريو باسم "سياق الاستهداف المحيط"، حيث تتوفر معلومات هوية المستخدم بالفعل في سياق التطبيق (كما هو الحال في بيانات الجلسة أو سياق المصادقة) ولكن يجب أن تكون متاحة لتقييمات إدارة الميزات في جميع أنحاء التطبيق.

ITargetingContextAccessor

توفر المكتبة حلا من ITargetingContextAccessor خلال النمط.

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

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

بدلا من تمرير سياق الاستهداف بشكل صريح مع كل isEnabled أو getVariant استدعاء، يمكنك توفير دالة تعرف كيفية استرداد معلومات استهداف المستخدم الحالي من سياق التطبيق الخاص بك:

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

هذا النمط مفيد بشكل خاص في تطبيقات الويب من جانب الخادم حيث قد يتوفر سياق المستخدم في نطاق الطلب أو في تطبيقات العميل حيث تتم إدارة هوية المستخدم مركزيا.

استخدام AsyncLocalStorage لسياق الطلب

أحد التحديات الشائعة عند تنفيذ نمط ملحق سياق الاستهداف هو الحفاظ على سياق الطلب عبر سلسلة استدعاء غير متزامنة. في Node.js تطبيقات الويب، تتوفر معلومات هوية المستخدم عادة في كائن الطلب، ولكن يصبح الوصول إليها غير قابل للوصول بمجرد إدخال عمليات غير متزامنة.

يوفر AsyncLocalStorage Node.js من async_hooks الوحدة لحل هذه المشكلة. يقوم بإنشاء مخزن يستمر عبر العمليات غير المتزامنة ضمن نفس "السياق" المنطقي - وهو مثالي للحفاظ على بيانات الطلب طوال دورة حياة الطلب بأكملها.

فيما يلي كيفية تنفيذ ملحق سياق الاستهداف باستخدام AsyncLocalStorage في تطبيق سريع:

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

المتغيرات

عند إضافة ميزات جديدة إلى أحد التطبيقات، قد يأتي وقت تحتوي فيه الميزة على العديد من خيارات التصميم المقترحة المختلفة. الحل الشائع لاتخاذ قرار بشأن التصميم هو شكل من أشكال اختبار A/B، والذي يتضمن توفير إصدار مختلف من الميزة لشرائح مختلفة من قاعدة المستخدم واختيار إصدار يستند إلى تفاعل المستخدم. في هذه المكتبة، يتم تمكين هذه الوظيفة من خلال تمثيل تكوينات مختلفة لميزة ذات متغيرات.

تمكن المتغيرات علامة الميزة من أن تصبح أكثر من علامة تشغيل/إيقاف تشغيل بسيطة. يمثل المتغير قيمة علامة ميزة يمكن أن تكون سلسلة أو رقما أو قيمة منطقية أو حتى عنصر تكوين. يجب أن تحدد علامة الميزة التي تعلن المتغيرات في ظل الظروف التي يجب استخدام كل متغير فيها، والتي تتم تغطيتها بمزيد من التفصيل في قسم تخصيص المتغيرات .

الحصول على متغير مع سياق الاستهداف

لكل ميزة، يمكن استرداد متغير باستخدام FeatureManagerأسلوب .getVariant يعتمد تعيين المتغير على المستخدم الذي يتم تقييمه حاليا، ويتم الحصول على هذه المعلومات من سياق الاستهداف الذي قمت بتمريره. إذا قمت بتسجيل ملحق سياق الاستهداف إلى 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. 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"
                    } 
                ]
            }
        ]
    }
}

تعريف المتغيرات

يحتوي كل متغير على خاصيتين: اسم وتكوين. يتم استخدام الاسم للإشارة إلى متغير معين، والتكوين هو قيمة هذا المتغير. يمكن تعيين التكوين باستخدام 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_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"
    } 
]

allocation يحتوي إعداد الميزة على الخصائص التالية:

الخاصية ‏‏الوصف
default_when_disabled تحديد المتغير الذي يجب استخدامه عند طلب متغير أثناء اعتبار الميزة معطلا.
default_when_enabled تحديد المتغير الذي يجب استخدامه عند طلب متغير أثناء اعتبار الميزة ممكنة ولم يتم تعيين أي متغير آخر للمستخدم.
user تحديد متغير وقائمة المستخدمين الذين يجب تعيين هذا المتغير لهم.
group تحديد متغير وقائمة مجموعات. يتم تعيين المتغير إذا كان المستخدم في مجموعة واحدة على الأقل.
percentile تحديد متغير ونطاق نسبة مئوية يجب أن تلائمه النسبة المئوية المحسوبة للمستخدم لذلك المتغير ليتم تعيينه.
seed تستند القيمة التي تستند إليها حسابات percentile النسبة المئوية. سيكون حساب النسبة المئوية لمستخدم معين هو نفسه عبر جميع الميزات إذا تم استخدام نفس seed القيمة. إذا لم يتم تحديد ، seed إنشاء قيمة أولية افتراضية استنادا إلى اسم الميزة.

إذا لم يتم تمكين الميزة، يقوم مدير الميزة بتعيين المتغير الذي تم وضع علامة عليه للمستخدم default_when_disabled الحالي، وهو Small في هذه الحالة.

إذا تم تمكين الميزة، يتحقق مدير الميزات من usergroupالتخصيصات و و 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 في التطبيق الخاص بك، كل ذلك مع الاستفادة من الميزات الجديدة التي تأتي مع المتغيرات، مثل تخصيص القيمة المئوية والبذاءة.

{
    "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 مجموعة من أزواج قيم المفاتيح، على غرار قاموس، والتي يمكن استخدامها لإرفاق بيانات تعريف مخصصة حول علامة الميزة لأحداث التقييم.

نشر بيانات تتبع الاستخدام المخصصة

يمكنك تسجيل دالة onFeatureEvaluated رد اتصال عند إنشاء FeatureManager. يتم استدعاء رد الاتصال هذا كلما تم تقييم علامة ميزة وتمكين بيانات تتبع الاستخدام لتلك العلامة. ستأخذ دالة رد الاتصال نتيجة تقييم الميزة كمعلمة.

يوضح المثال التالي كيفية تنفيذ دالة رد اتصال مخصصة لإرسال بيانات تتبع الاستخدام بالمعلومات المستخرجة من نتيجة تقييم الميزة وتسجيلها في مدير الميزات.

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

تكامل رؤى التطبيق

توفر مكتبة إدارة ميزات JavaScript حزم ملحقة تتكامل مع Application Insights SDKs.

تقدم Application Insights مجموعات SDK مختلفة للويب وسيناريوهات Node.js. الرجاء تحديد حزم الملحقات الصحيحة للتطبيق الخاص بك.

إذا كان التطبيق الخاص بك يعمل في المتصفح، فقم بتثبيت الحزمة "@microsoft/feature-management-applicationinsights-browser" . يوضح المثال التالي كيف يمكنك إنشاء ناشر بيانات تتبع استخدام Application Insights مضمن وتسجيله في مدير الميزات.

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

يرسل FeatureEvaluation ناشر بيانات تتبع الاستخدام أحداثا مخصصة إلى Application Insights عند تقييم علامة ميزة ممكنة باستخدام بيانات تتبع الاستخدام. يتبع الحدث المخصص مخطط FeatureEvaluationEvent .

استهداف معالج بيانات تتبع الاستخدام

إذا قمت بتنفيذ ITargetingContextAccessor، يمكنك استخدام معالج بيانات تتبع الاستخدام Application Insights المضمن لإرفاق معلومات معرف الاستهداف تلقائيا بجميع بيانات تتبع الاستخدام عن طريق استدعاء الدالة createTargetingTelemetryProcessor .

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

يضمن هذا أن كل عنصر بيانات تتبع الاستخدام يتم إرساله إلى Application Insights يتضمن معلومات معرف استهداف المستخدم (userId والمجموعات)، ما يسمح لك بربط استخدام علامة الميزة بمستخدمين أو مجموعات محددة في تحليلاتك.

إذا كنت تستخدم معالج بيانات تتبع الاستخدام المستهدف، بدلا من استدعاء trackEvent الأسلوب الذي توفره حزمة إدارة الميزات، يمكنك استدعاء trackEvent الأسلوب مباشرة من Application Insights SDK. سيتم إرفاق معلومات معرف الاستهداف تلقائيا ب بيانات تتبع الاستخدام المخصصة للحدث customDimensions.

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

الخطوات التالية

لمعرفة كيفية استخدام علامات الميزات في التطبيقات الخاصة بك، تابع إلى قوالب التشغيل السريع التالية.

بايثون

لمعرفة كيفية استخدام عوامل تصفية الميزات، تابع إلى البرامج التعليمية التالية.

تمكين الميزات الشرطية باستخدام عوامل تصفية الميزات

تمكين الميزات في جدول زمني

طرح الميزات للجماهير المستهدفة

  • Last updated on