مشاركة عبر

إدارة ميزات Python

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

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

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

  • اصطلاح مشترك لإدارة الميزات

  • حاجز منخفض أمام الدخول

    • يدعم إعداد علامة ميزة JSON

  • إدارة مدة بقاء علامة الميزة

    • يمكن أن تتغير قيم التكوين في الوقت الفعلي؛ يمكن أن تكون علامات الميزة متناسقة عبر الطلب بأكمله

  • السيناريوهات البسيطة والمعقدة التي تمت تغطيتها

    • تبديل ميزات التشغيل/إيقاف التشغيل من خلال ملف التكوين التعريفي
    • تقييم حالة الميزة ديناميكيا استنادا إلى استدعاء الخادم

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

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

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

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

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

على سبيل المثال، يمكن تصميم عامل تصفية ميزة مستعرض Microsoft Edge. سيقوم عامل تصفية الميزة هذا بتنشيط أي ميزات مرفقة به، طالما أن طلب HTTP قادم من Microsoft Edge.

تكوين علامة الميزة

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

إعلان علامة الميزة

تدعم مكتبة إدارة الميزات json كمصدر علامة ميزة. فيما يلي مثال على التنسيق المستخدم لإعداد علامات الميزات في ملف 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 يتم استخدام قسم من مستند json بواسطة الاصطلاح لتحميل إعدادات علامة الميزة. المقطع feature_flags عبارة عن قائمة بعلامات الميزات التي يتم تحميلها في المكتبة. في القسم أعلاه، نرى ثلاث ميزات مختلفة. تحدد الميزات عوامل تصفية الميزات الخاصة بها باستخدام الخاصية client_filters ، داخل conditions. في عوامل تصفية الميزات ل FeatureT، نرى enabled أنه true مع عدم تحديد عوامل التصفية، ما FeatureT يؤدي إلى إرجاع true دائما . FeatureU هو نفس ولكن FeatureT مع enabled ينتج false عن الميزة دائما العودة false. FeatureV يحدد عامل تصفية ميزة يسمى Microsoft.TimeWindow. FeatureV هو مثال على عامل تصفية ميزة قابل للتكوين. يمكننا أن نرى في المثال أن عامل التصفية يحتوي على خاصية parameters . parameters يتم استخدام الخاصية لتكوين عامل التصفية. في هذه الحالة، يتم تكوين أوقات البدء والانتهاء للميزة لتكون نشطة.

يمكن العثور على المخطط التفصيلي للمقطع feature_management هنا.

خيارات متقدمة: يحظر استخدام النقطين ':' في أسماء علامات الميزة.

الإعلان عن التشغيل/إيقاف التشغيل

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

{
    "feature_management": {
        "feature_flags": [
            {
                "id": "FeatureT",
                "enabled": "true"
            },
            {
                "id": "FeatureX",
                "enabled": "false"
            }
        ]
    }
}

نوع المتطلب

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أسلوب .is_enabled

…
feature_manager = FeatureManager(feature_flags)
…
if feature_manager.is_enabled("FeatureX"):
    # Do something

feature_flags يمكن أن يكون FeatureManager المقدم إلى AzureAppConfigurationProvider إما قاموس علامات الميزات أو قاموسا.

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

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

توضح القصاصة البرمجية التالية كيفية إضافة عامل تصفية MyCustomFilterميزة مخصص .

feature_manager = FeatureManager(feature_flags, feature_filters=[MyCustomFilter()])

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

سمة الاسم المستعار للتصفية

عند تسجيل عامل تصفية ميزة لعلامة ميزة، يتم استخدام اسم عامل التصفية كاسم مستعار بشكل افتراضي.

يمكن تجاوز معرف عامل تصفية الميزة باستخدام @FeatureFilter.alias("MyFilter"). يمكن تزيين عامل تصفية ميزة بهذه السمة للإعلان عن الاسم الذي يجب استخدامه في التكوين للإشارة إلى عامل تصفية الميزة هذا ضمن علامة ميزة.

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

إذا تم تكوين ميزة ليتم تمكينها لعامل تصفية ميزة معين ولم يتم تسجيل عامل تصفية الميزة هذا، ValueError يتم رفع استثناء عند تقييم الميزة.

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

هناك عاملا تصفية ميزة تأتيان مع الحزمةFeatureManagement: TimeWindowFilterو.TargetingFilter

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

Microsoft.TimeWindow

يوفر عامل التصفية Microsoft.TimeWindow طريقة لتمكين ميزة استنادا إلى نافذة زمنية.

  • إذا حددت قيمة فقط End ، اعتبار الميزة قيد التشغيل حتى ذلك الوقت.
  • إذا حددت قيمة فقط Start ، اعتبار الميزة قيد التشغيل في جميع النقاط بعد ذلك الوقت.
{
    "id": "EnhancedPipeline",
    "enabled": true,
    "conditions": {
        "client_filters": [
            {
                "name": "Microsoft.TimeWindow",
                "parameters": {
                    "Start": "Sun, 01 Jun 2025 13:59:59 GMT",
                    "End": "Fri, 01 Aug 2025 00:00:00 GMT"
                }
            }
        ]
    }
}

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

إشعار

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

{
    "id": "EnhancedPipeline",
    "enabled": true,
    "conditions": {
        "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

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

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

  • Weekly

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

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

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

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

إشعار

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

نطاق التكرار

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

  • NoEnd

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

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

  • EndDate

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

    الخاصية Relevance ‏‏الوصف
    Type مطلوب نوع نطاق التكرار. يجب تعيينه إلى 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 في حدوث النافذة الزمنية لعدد محدد من المرات.

    الخاصية Relevance ‏‏الوصف
    Type مطلوب نوع نطاق التكرار. يجب تعيينه إلى 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 المضمن.

استهداف مستخدم

يمكن تحديد مستخدم مباشرة في is_enabled المكالمة أو TargetingContext يمكن استخدام لتحديد المستخدم والمجموعة الاختيارية.

# Directly specifying the user
result = is_enabled(feature_flags, "test_user")

# Using a TargetingContext
result = is_enabled(feature_flags, TargetingContext(user_id="test_user", groups=["Ring1"]))

استبعاد الاستهداف

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

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

في المثال أعلاه، يتم تمكين الميزة للمستخدمين المسمين Jeff و Alicia. كما تم تمكينه للمستخدمين في المجموعة المسماة Ring0. ومع ذلك، إذا تمت تسمية Markالمستخدم ، يتم تعطيل الميزة، بغض النظر عما إذا كان في المجموعة Ring0 أم لا. تأخذ الاستثناءات الأولوية على بقية عامل تصفية الاستهداف.

المتغيرات

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

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

class Variant:
    def __init__(self, name: str, configuration: Any):
        self._name = name
        self._configuration = configuration

    @property
    def name(self) -> str:
        """
        The name of the variant.
        :rtype: str
        """
        return self._name

    @property
    def configuration(self) -> Any:
        """
        The configuration of the variant.
        :rtype: Any
        """
        return self._configuration

الحصول على المتغيرات

لكل ميزة، يمكن استرداد متغير باستخدام FeatureManagerأسلوب .get_variant

…
variant = print(feature_manager.get_variant("TestVariants", TargetingContext(user_id="Adam"))

variantConfiguration = variant.configuration;

// Do something with the resulting variant and its configuration

يعتمد المتغير الذي تم إرجاعه على المستخدم الذي يتم تقييمه حاليا، ويتم الحصول على هذه المعلومات من مثيل .TargetingContext

إعلان علامة ميزة المتغير

بالمقارنة مع علامات الميزات العادية، تحتوي علامات الميزات المتغيرة على خاصيتين إضافيتين: 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 الذي تم إرجاعه هي None.

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

القياس عن بعد

عند نشر تغيير علامة ميزة، غالبا ما يكون من المهم تحليل تأثيره على أحد التطبيقات. على سبيل المثال، فيما يلي بعض الأسئلة التي قد تنشأ:

  • هل تم تمكين/تعطيل العلامات الخاصة بي كما هو متوقع؟
  • هل يمكن للمستخدمين المستهدفين الوصول إلى ميزة معينة كما هو متوقع؟
  • ما هو المتغير الذي يراه مستخدم معين؟

يمكن الإجابة عن هذه الأنواع من الأسئلة من خلال انبعاث وتحليل أحداث تقييم علامة الميزة. تتيح AzureMonitor هذه المكتبة اختياريا إنتاج تتبع تتبع عن بعد أثناء تقييم علامة الميزة عبر OpenTelemetry.

تمكين بيانات تتبع الاستخدام

بشكل افتراضي، لا يتم إصدار بيانات تتبع الاستخدام لعلامات الميزات. لنشر بيانات تتبع الاستخدام لعلامة ميزة معينة، يجب أن تعلن العلامة أنها ممكنة لانبعاث بيانات تتبع الاستخدام.

بالنسبة لعلامات الميزات المعرفة في json، يتم التمكين باستخدام الخاصية telemetry .

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

تعرف القصاصة البرمجية أعلاه علامة ميزة مسماة MyFeatureFlag تم تمكينها لبيانات تتبع الاستخدام. telemetry تم تعيين خاصية الكائن enabled إلى true. يجب أن تكون enabled قيمة الخاصية true لنشر بيانات تتبع الاستخدام للعلامة.

يحتوي telemetry قسم علامة الميزة على الخصائص التالية:

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

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

feature_manager = FeatureManager(feature_flags, on_feature_evaluated=publish_telemetry)

بيانات تتبع الاستخدام ل Application Insights

توفر مكتبة إدارة الميزات ناشر بيانات تتبع الاستخدام مضمنا يرسل بيانات تقييم علامة الميزة إلى Application Insights. لتمكين Application Insights، يمكن تثبيت مكتبة إدارة الميزات مع Azure Monitor عبر pip install FeatureManagement[AzureMonitor]. يقوم هذا الأمر بتثبيت الحزمة azure-monitor-events-extension ، والتي تستخدم لنمط القياس عن بعد إلى Application Insights باستخدام OpenTelemetry.

إشعار

azure-monitor-events-extension تضيف الحزمة بيانات تتبع الاستخدام فقط إلى البنية الأساسية لبرنامج ربط العمليات التجارية Open Telemetry. لا يزال تسجيل Application Insights مطلوبا.

from azure.monitor.opentelemetry import configure_azure_monitor

configure_azure_monitor(
        connection_string="InstrumentationKey=00000000-0000-0000-0000-000000000000"
    )

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

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

عند تقييم علامة ميزة وتمكين القياس عن بعد، يستدعي مدير الميزة رد اتصال بيانات تتبع الاستخدام بمعلمة EvaluationEvent . EvaluationEvent تتضمن الخصائص التالية:

علامة ‏‏الوصف
feature علامة الميزة المستخدمة.
user معرف المستخدم المستخدم للاستهداف.
enabled ما إذا كان يتم تقييم علامة الميزة على أنها ممكنة.
Variant المتغير المعين.
VariantAssignmentReason سبب تعيين المتغير.

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

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

Python

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

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

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

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

  • Last updated on