Aracılığıyla paylaş

Python özellik yönetimi

Python özellik yönetimi kitaplığı, özellik bayraklarını temel alarak uygulama işlevselliği geliştirmenin ve kullanıma sunmanın bir yolunu sağlar. Yeni bir özellik geliştirildikten sonra, birçok uygulamanın özelliğin ne zaman etkinleştirilmesi gerektiği ve hangi koşullar altında olduğu gibi özel gereksinimleri vardır. Bu kitaplık, bu ilişkileri tanımlamanın bir yolunu sağlar ve ayrıca bu özelliklerin kullanıma sunulmasını mümkün kılmak için ortak Python kod desenleriyle tümleştirilir.

Özellik bayrakları, Python uygulamalarının özellikleri dinamik olarak açması veya kapatması için bir yol sağlar. Geliştiriciler, koşullu deyimler gibi basit kullanım örneklerinde özellik bayraklarını kullanabilir.

Python özellik yönetimi kitaplığını kullanmanın avantajlarından bazıları şunlardır:

  • Özellik yönetimi için ortak bir kural

  • Giriş için düşük bariyer

    • JSON özellik bayrağı kurulumunu destekler

  • Özellik bayrağı yaşam süresi yönetimi

    • Yapılandırma değerleri gerçek zamanlı olarak değişebilir; özellik bayrakları isteğin tamamında tutarlı olabilir

  • Ele alınan basit ve karmaşık senaryolar

    • Bildirim temelli yapılandırma dosyası aracılığıyla özellikleri açma/kapatma
    • Sunucu çağrısına göre özelliğin durumunu dinamik olarak değerlendirme

    Python özellik yönetimi kitaplığı açık kaynak. Daha fazla bilgi için GitHub deposunu ziyaret edin.

Özellik bayrakları

Özellik bayrakları, özelliği açmak için kullanılan bir ad ve özellik filtreleri listesi olmak üzere iki bölümden oluşur.

Özellik filtreleri

Özellik filtreleri, bir özelliğin ne zaman etkinleştirilmesi gerektiğine yönelik bir senaryo tanımlar. Özellik açık mı yoksa kapalı mı olduğu değerlendirildiğinde, filtrelerden biri özelliğin etkinleştirilmesi gerektiğine karar verene kadar özellik filtreleri listesinden geçilir. Bu noktada özellik etkin olarak kabul edilir ve özellik filtreleri durakları arasında geçiş yapılır. Özellik filtresi özelliğin etkinleştirilmesi gerektiğini belirtmiyorsa devre dışı olarak kabul edilir.

Örneğin, bir Microsoft Edge tarayıcı özellik filtresi tasarlanabilir. Bu özellik filtresi, Microsoft Edge'den http isteği geldiği sürece bu filtreye eklenen tüm özellikleri etkinleştirir.

Özellik bayrağı yapılandırması

Özellik bayraklarını tanımlamak için Python sözlüğü kullanılır. Sözlük, anahtar olarak özellik adlarından ve değer olarak özellik bayrak nesnelerinden oluşur. Özellik bayrağı nesnesi, anahtarı içeren ve anahtarı içeren bir conditions sözlüktür client_filters . Anahtar client_filters , özelliğin etkinleştirilmesi gerekip gerekmediğini belirlemek için kullanılan özellik filtrelerinin listesidir.

Özellik bayrağı bildirimi

Özellik yönetimi kitaplığı, özellik bayrağı kaynağı olarak json'yi destekler. Aşağıda bir JSON dosyasında özellik bayraklarını ayarlamak için kullanılan biçime bir örnek verilmiştir.

{
    "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 belgesinin bölümü, özellik bayrağı ayarlarını yüklemek için kural tarafından kullanılır. feature_flags bölümü, kitaplığa yüklenen özellik bayraklarının listesidir. Yukarıdaki bölümde üç farklı özellik görüyoruz. Özellikler, client_filtersiçinde özelliğini kullanarak conditions özellik filtrelerini tanımlar. için FeatureTözellik filtrelerinde tanımlı filtre olmadığını ve bunun sonucunda her zaman döndürüldiğini enabledtrue görüyoruz FeatureTtrue. FeatureUile aynıdırFeatureT, ancak özelliğin enabled her zaman döndürüleceği falsesonucuna neden olurfalse. FeatureV adlı Microsoft.TimeWindowbir özellik filtresi belirtir. FeatureV yapılandırılabilir özellik filtresi örneğidir. Örnekte filtrenin bir parameters özelliği olduğunu görebiliriz. parameters özelliği, filtreyi yapılandırmak için kullanılır. Bu durumda, özelliğin etkin olması için başlangıç ve bitiş saatleri yapılandırılır.

Bölümün feature_management ayrıntılı şemasına buradan ulaşabilirsiniz.

Gelişmiş: Özellik bayrağı adlarında ':' iki nokta üst üste kullanımı yasaktır.

Açık/kapalı bildirimi

Aşağıdaki kod parçacığında, açık/kapalı özellikler için kullanılabilecek bir özelliği tanımlamanın alternatif bir yolu gösterilmektedir.

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

Gereksinim türü

requirement_type Özellik bayrağının özelliği, bir özelliğin durumunu değerlendirirken filtrelerin mi yoksa Any mantığın mı kullanılacağını All belirlemek için kullanılır. Belirtilmezse requirement_type , varsayılan değer olur Any.

  • Any , özelliğin etkinleştirilmesi için yalnızca bir filtrenin true olarak hesaplanması gerektiği anlamına gelir.
  • All , özelliğin etkinleştirilmesi için her filtrenin true olarak hesaplanması gerektiği anlamına gelir.

Geçiş requirement_type değişikliklerinden biri All . İlk olarak, filtre yoksa özellik devre dışı bırakılır. Ardından, filtrelerden biri özelliğin devre dışı bırakılması gerektiğine karar verene kadar özellik filtreleri geçirilir. Hiçbir filtre özelliğin devre dışı bırakılması gerektiğini belirtmezse etkin olarak kabul edilir.

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

Yukarıdaki örnekte, FeatureW özelliğinin etkinleştirilmesi requirement_typeiçin tüm filtrelerinin true olarak hesaplanması gerektiği anlamına gelen öğesini All belirtir. Bu durumda özellik, belirtilen zaman penceresinde kullanıcıların %50'sinde etkinleştirilir.

Tüketim

Özellik yönetiminin temel biçimi, özellik bayrağının etkinleştirilip etkinleştirilmediğini denetlemek ve ardından sonucta göre eylemler gerçekleştirmektir. Özellik bayrağının durumunu denetleme işlemi ' nin FeatureManager yöntemi aracılığıyla is_enabledyapılır.

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

feature_flags için sağlananFeatureManager, özellik bayraklarının sözlüğü veya sözlüğü olabilirAzureAppConfigurationProvider.

Özellik filtresi uygulama

Özellik filtresi oluşturmak, tanımladığınız ölçütlere göre özellikleri etkinleştirmenin bir yolunu sağlar. Özellik filtresi uygulamak için arabiriminin FeatureFilter uygulanması gerekir. FeatureFilter adlı evaluatetek bir yöntemi vardır. Özellik, özellik filtresi için etkinleştirilebileceğini belirttiğinde evaluate yöntemi çağrılır. döndürürse evaluatetrue, özelliğin etkinleştirilmesi gerektiği anlamına gelir.

Aşağıdaki kod parçacığında özelleştirilmiş özellik filtresinin MyCustomFilternasıl ekleneceği gösterilmektedir.

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

Özellik filtreleri oluşturulurken feature_filtersözelliğine FeatureManager sağlanarak kaydedilir. Özel özellik filtresinin herhangi bir bağlama ihtiyacı varsa, kullanılarak is_enabledçağrılırken kwargs geçirilebilir.

Filtre diğer adı özniteliği

Özellik bayrağı için bir özellik filtresi kaydedildiğinde, filtrenin adı varsayılan olarak diğer ad olarak kullanılır.

Özellik filtresi tanımlayıcısı kullanılarak @FeatureFilter.alias("MyFilter")geçersiz kılınabilir. Bir özellik filtresi, bir özellik bayrağı içinde bu özellik filtresine başvurmak üzere yapılandırmada kullanılması gereken adı bildirmek için bu öznitelikle donatılabilir.

Eksik özellik filtreleri

Bir özellik belirli bir özellik filtresi için etkinleştirilecek şekilde yapılandırılmışsa ve bu özellik filtresi kayıtlı değilse, özellik değerlendirildiğinde bir ValueError özel durum oluşur.

Yerleşik özellik filtreleri

Paketiyle birlikte FeatureManagement gelen iki özellik filtresi vardır: TimeWindowFilter, ve TargetingFilter.

Yerleşik özellik filtrelerinin her birinin kendi parametreleri vardır. Örneklerle birlikte özellik filtrelerinin listesi aşağıda verilmiştir.

Microsoft.TimeWindow

Filtre, Microsoft.TimeWindow bir özelliği bir zaman penceresine göre etkinleştirmenin bir yolunu sağlar.

  • Yalnızca bir End değer belirtirseniz, özellik o zamana kadar açık olarak kabul edilir.
  • Yalnızca bir Start değer belirtirseniz, bu özellik bu sürenin ardından tüm noktalarda açık kabul edilir.
{
    "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"
                }
            }
        ]
    }
}

Filtreyi, yinelenen olarak bir zaman penceresi uygulayacak şekilde yapılandırabilirsiniz. Bu özellik, bir günün düşük trafikli veya yüksek trafikli bir döneminde veya haftanın belirli günlerinde bir özelliği açmanız gerektiğinde yararlı olabilir. Tek bir zaman penceresini yinelenen bir zaman penceresine genişletmek için, yinelenme kuralı belirtmek için bir Recurrence parametre kullanırsınız.

Not

Yinelenmeyi kullanmak için Start ve End değerlerini belirtmeniz gerekir. Bazı durumlarda, değerin tarih bölümü, filtreyi aktif olarak değerlendirmek için bir bitiş tarihi belirtmez. Bunun yerine filtre, yinelenen zaman penceresinin süresini tanımlamak için başlangıç tarihine göre bitiş tarihini kullanır.

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

Ayarlar Recurrence iki bölümden oluşur:

  • Ayarlar Pattern , zaman penceresinin ne sıklıkta yineleneceğini belirtir.
  • Ayarlar, Range yineleme düzeninin ne kadar süreyle yineleneceğini belirtir.

Yinelenme düzeni

İki olası yinelenme deseni türü vardır: Daily ve Weekly. Örneğin, bir zaman penceresi her gün, her üç günde, her Pazartesi veya her cuma yinelenebilir.

Türüne bağlı olarak, ayarların Pattern belirli alanları zorunludur, isteğe bağlıdır veya yoksayılır.

  • Daily

    Günlük yinelenme düzeni, zaman penceresinin her oluşum arasındaki belirtilen gün sayısına göre yinelenmesine neden olur.

    Özellik İlgililik Açıklama
    Type Gerekli Yinelenme desen türü. Dailyolarak ayarlanmalıdır.
    Interval Opsiyonel Her oluşum arasındaki gün sayısı. Varsayılan değer şudur: 1.

  • Weekly

    Haftalık yinelenme düzeni, zaman penceresinin haftanın aynı günü veya günlerinde tekrarlanmalarına neden olur. Ancak her yineleme kümesi arasındaki hafta sayısını belirtebilirsiniz.

    Özellik İlgililik Açıklama
    Type Gerekli Yinelenme desen türü. Weeklyolarak ayarlanmalıdır.
    DaysOfWeek Gerekli Olayın gerçekleştiği haftanın günleri.
    Interval Opsiyonel Her yineleme kümesi arasındaki hafta sayısı. Varsayılan değer şudur: 1.
    FirstDayOfWeek Opsiyonel Haftanın ilk günü olarak kullanılacak gün. Varsayılan değer şudur: Sunday.

    Aşağıdaki örnek, zaman penceresini her Pazartesi ve Salı günü yineler:

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

Not

Değer, Start yinelenme düzenine uyan geçerli bir ilk oluşum olmalıdır. Ayrıca, zaman penceresinin süresi ne sıklıkta oluştuğundan daha uzun olamaz. Örneğin, 25 saatlik bir zaman penceresi her gün yinelenemez.

Yinelenme aralığı

Üç olası yineleme aralığı türü vardır: NoEnd, EndDate, ve Numbered.

  • NoEnd

    Aralık NoEnd , yinelenmenin süresiz olarak gerçekleşmesine neden olur.

    Özellik İlgililik Açıklama
    Type Gerekli Yinelenme aralığı türü. NoEndolarak ayarlanmalıdır.

  • EndDate

    Bu aralık, EndDate zaman penceresinin bitiş tarihine kadar belirlenen desene uyan tüm günlerde oluşmasına neden olur.

    Özellik İlgililik Açıklama
    Type Gerekli Yinelenme aralığı türü. EndDateolarak ayarlanmalıdır.
    EndDate Gerekli Desenin uygulanmasının durdurulacağı tarih ve saat. Son oluşumun başlangıç saati bitiş tarihinden önceyse, bu oluşumun bitiş saati bunun ötesine uzanabilir.

    Aşağıdaki örnekte, zaman penceresi 1 Nisan 2024'teki son oluşuma kadar her gün yineler.

    "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

    Belirlenen Numbered aralığı, zaman penceresinin belirtilen sayıda tekrarlanmasına neden olur.

    Özellik İlgililik Açıklama
    Type Gerekli Yinelenme aralığı türü. Numberedolarak ayarlanmalıdır.
    NumberOfOccurrences Gerekli Oluşum sayısı.

    Aşağıdaki örnekte, zaman penceresi Pazartesi ve Salı günleri toplam üç kez yinelenerek aşağıdaki tarihlerde gerçekleşir:

    • 1 Nisan Pazartesi
    • 2 Nisan Salı
    • 8 Nisan Pazartesi
    "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
    }
}

Yinelenme kuralı oluşturmak için hem hem de PatternRange ayarlarını belirtmeniz gerekir. Herhangi bir desen türü herhangi bir aralık türüyle çalışabilir.

İleri: Özelliğin Start saat dilimi uzaklığı yinelenme ayarlarına uygulanır.

Microsoft.Targeting

Bu filtre, bir özelliği hedef kitle için etkinleştirme özelliği sağlar. Hedeflemenin ayrıntılı açıklaması aşağıdaki hedefleme bölümünde açıklanmıştır. Filtre parametreleri, kullanıcıları, grupları, dışlanan kullanıcıları/grupları tanımlayan bir nesneyi ve özelliğe erişimi olması gereken kullanıcı tabanının varsayılan yüzdesini içerir Audience . Bölümünde listelenen Groups her grup nesnesi, grup üyelerinin yüzde kaçının erişimi olması gerektiğini de belirtmelidir. Doğrudan veya kullanıcı dışlanan bir grupta yer alırsa, bölümde bir kullanıcı belirtilirse Exclusion özellik devre dışı bırakılır. Aksi takdirde, bir kullanıcı doğrudan bölümde belirtilirse Users veya kullanıcı grup dağıtımlarından herhangi birinin dahil edilen yüzdesindeyse veya kullanıcı varsayılan dağıtım yüzdesine düşerse, bu kullanıcı özelliği etkinleştirmiş olur.

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

Hedefleme

Hedefleme, geliştiricilerin yeni özellikleri kullanıcı tabanına aşamalı olarak dağıtmasını sağlayan bir özellik yönetimi stratejisidir. Strateji, hedef kitle olarak bilinen bir kullanıcı kümesini hedefleme kavramını temel alır. Hedef kitle belirli kullanıcılardan, gruplardan, dışlanan kullanıcılardan/gruplardan ve tüm kullanıcı tabanının belirlenmiş yüzdelerinden oluşur. Hedef kitleye dahil edilen gruplar, toplam üyelerinin yüzdelerine ayrılabilir.

Aşağıdaki adımlarda yeni bir 'Beta' özelliği için aşamalı dağıtım örneği gösterilmektedir:

  1. Bireysel kullanıcılar Jeff ve Alicia'ya Beta erişimi verilir.
  2. Başka bir kullanıcı, Mark, kabul etmek ister ve dahil edilir.
  3. "Ring1" olarak bilinen bir grubun yüzde yirmisi Beta'ya dahil edilir.
  4. Beta'ya dahil edilen "Ring1" kullanıcılarının sayısı yüzde 100'e kadar artırılır.
  5. Kullanıcı tabanının yüzde beşi Beta'ya dahil edilir.
  6. Dağıtım yüzdesi yüzde 100'e kadar artırılır ve özellik tamamen kullanıma sunulmaktadır.

Bir özelliği dağıtmaya yönelik bu strateji, dahil edilen Microsoft.Targeting özellik filtresi aracılığıyla kitaplıkta yerleşik olarak bulunur.

Kullanıcıyı hedefleme

Bir kullanıcı ya doğrudan is_enabled çağrısında belirtilebilir ya da isteğe bağlı grup ile kullanıcıyı belirtmek için TargetingContext kullanılabilir. TargetingContext çağrısı yapıldığında veya FeatureManager oluşturulurken is_enabled çağrısı yapılarak ya da targeting_context_accessor için bir geri çağırma sağlanarak geçirilebilir.

# 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"]))

Hedefleme bağlam erişimcisi

Her TargetingContext çağrıya bir is_enabled geçirmek yerine, hedefleme bağlamını otomatik olarak sağlayan FeatureManager ile bir geri çağırım fonksiyonu kaydedebilirsiniz. Bu yaklaşım, kullanıcı kimliği ve grupları HTTP isteği üst bilgileri veya oturum verileri gibi ortak bir kaynaktan belirlenebildiğinde kullanışlıdır ve her özellik değerlendirmesi için bağlamı el ile oluşturma ve geçirme gereksinimini ortadan kaldırır.

from quart import request
from featuremanagement import FeatureManager, TargetingContext

# A callback for assigning a TargetingContext for Feature Flag evaluation in a Quart app
def my_targeting_accessor() -> TargetingContext:
    session_id = ""
    if "Session-ID" in request.headers:
        session_id = request.headers["Session-ID"]
    return TargetingContext(user_id=session_id)


# Load feature flags and set up targeting context accessor
feature_manager = FeatureManager(config, targeting_context_accessor=my_targeting_accessor)

Hedefleme dışlaması

Hedef kitle tanımlanırken, kullanıcılar ve gruplar hedef kitlenin dışında tutulabilir. Dışlamalar, bir özelliğin bir kullanıcı grubuna dağıtılması için yararlıdır, ancak birkaç kullanıcı veya grubun piyasaya sürülmesinin dışında tutulması gerekir. Dışlama, hedef kitlenin özelliğine Exclusion bir kullanıcı ve grup listesi eklenerek tanımlanır.

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

Yukarıdaki örnekte, özellik ve Jeffadlı Alicia kullanıcılar için etkinleştirilmiştir. Ayrıca adlı Ring0gruptaki kullanıcılar için de etkinleştirilir. Ancak, kullanıcı olarak adlandırılırsa Mark, grupta Ring0 olup olmadığına bakılmaksızın özellik devre dışı bırakılır. Dışlamalar, hedefleme filtresinin geri kalanından önceliklidir.

Varyantlar

Bir uygulamaya yeni özellikler eklendiğinde, bir özelliğin birden çok farklı tasarım seçeneğinin olduğu bir zaman gelebilir. Tasarıma karar vermek için yaygın bir çözüm, bir tür A/B testidir. A/B testi, özelliğin farklı bir sürümünü kullanıcı tabanının farklı segmentlerine sağlamayı ve kullanıcı etkileşimini temel alan bir sürüm seçmeyi içerir. Bu kitaplıkta bu işlev, bir özelliğin farklı yapılandırmalarını çeşitlemelerle temsil ederek etkinleştirilir.

Çeşitlemeler, özellik bayrağının basit bir açık/kapalı bayrağından daha fazlasına dönüşebilmesini sağlar. Değişken, bir özellik bayrağının dize, sayı, boole, hatta yapılandırma nesnesi olabilecek bir değerini temsil eder. Varyantları bildiren bir özellik bayrağı, varyant ayırma bölümünde daha ayrıntılı olarak ele alınan her bir değişkenin hangi koşullarda kullanılması gerektiğini tanımlamalıdır.

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

Çeşitlemeler alınıyor

Her özellik için, 'nin FeatureManager yöntemi kullanılarak get_variantbir değişken alınabilir.

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

variantConfiguration = variant.configuration;

// Do something with the resulting variant and its configuration

Döndürülen değişken, şu anda değerlendirilmekte olan kullanıcıya bağlıdır ve bu bilgiler bir örneğinden TargetingContextalınır.

Değişken özellik bayrağı bildirimi

Normal özellik bayraklarıyla karşılaştırıldığında, değişken özellik bayraklarının iki özelliği daha vardır: variants ve allocation. variants özelliği, bu özellik için tanımlanan değişkenleri içeren bir dizidir. özelliği, allocation bu varyantların özellik için nasıl ayrılacaklarını tanımlar. Normal özellik bayraklarını bildirme gibi, bir JSON dosyasında da değişken özellik bayrakları ayarlayabilirsiniz. Aşağıda bir değişken özellik bayrağı örneği verilmiştır.

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

Varyantları tanımlama

Her değişken iki özelliğe sahiptir: ad ve yapılandırma. Ad, belirli bir değişkene başvurmak için kullanılır ve yapılandırma bu değişkenin değeridir. Yapılandırma özelliği kullanılarak configuration_value ayarlanabilir. configuration_value dize, sayı, boole veya yapılandırma nesnesi olabilecek bir satır içi yapılandırmadır. Belirtilmezse configuration_value , döndürülen değişkenin Configuration özelliği olur None.

Özelliğin altındaki her özellik için tüm olası değişkenlerin variants listesi tanımlanır.

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

Çeşitlemeler ayırma

Bir özelliğin değişkenlerini ayırma işlemi, özelliğin allocation özelliği tarafından belirlenir.

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

Bir allocation özelliğin ayarı aşağıdaki özelliklere sahiptir:

Özellik Açıklama
default_when_disabled Özellik devre dışı olarak kabul edilirken bir değişken istendiğinde hangi değişkenin kullanılacağını belirtir.
default_when_enabled Özellik etkin olarak kabul edilirken ve kullanıcıya başka bir değişken atanmadığında bir değişken istendiğinde hangi değişkenin kullanılacağını belirtir.
user Bir değişken ve bu değişkenin atanması gereken kullanıcıların listesini belirtir.
group Bir değişken ve grup listesi belirtir. Kullanıcı gruplardan en az birindeyse değişken atanır.
percentile Kullanıcının hesaplanan yüzdesinin atanacağı değişken için uyması gereken bir değişken ve yüzde aralığı belirtir.
seed Yüzde hesaplamalarının percentile temel aldığı değer. Belirli bir kullanıcı için yüzde hesaplaması, aynı değer kullanılırsa tüm özelliklerde aynı seed olur. Belirtilmezse seed , özellik adına göre varsayılan bir tohum oluşturulur.

Özellik etkinleştirilmemişse, özellik yöneticisi geçerli kullanıcıya default_when_disabled olarak Small işaretlenmiş değişkeni atar. Bu durumda bu durum geçerlidir.

Özellik etkinleştirilirse, özellik yöneticisi userbir değişken atamak için , groupve percentile ayırmalarını denetler. Bu belirli örnek için, değerlendirilen kullanıcı adlı Marshagrupta Ring1ise veya kullanıcı 0 ile 10. yüzdebirlik arasında kalırsa, belirtilen değişken kullanıcıya atanır. Bu durumda, atanan tüm kullanıcılar değişkenini Big döndürür. Bu ayırmalardan hiçbiri eşleşmiyorsa, kullanıcıya değişken (olandefault_when_enabled) atanırSmall.

Ayırma mantığı Microsoft.Targeting özellik filtresine benzer, ancak hedeflemede bulunan ve ayırmada olmayan bazı parametreler vardır ve tam tersi de geçerlidir. Hedefleme ve ayırmanın sonuçları ilişkili değildir.

Etkin durumu bir değişkenle geçersiz kılma

Özellik bayrağının etkin durumunu geçersiz kılmak için varyantları kullanabilirsiniz. Geçersiz kılma, varyantlara özellik bayrağı değerlendirmesini genişletme fırsatı verir. Özellik yöneticisi, varyantları olan bir bayrak üzerinde çağrı is_enabled yaparken, geçerli kullanıcıya atanan değişkenin sonucu geçersiz kılacak şekilde yapılandırılıp yapılandırılmamış olduğunu denetler. Geçersiz kılma isteğe bağlı variant özelliği status_overridekullanılarak yapılır. Varsayılan olarak, bu özellik olarak Noneayarlanır. Bu, değişkenin bayrağın etkin veya devre dışı olarak kabul edilip edilmediğini etkilemediği anlamına gelir. ayarı status_overrideEnabled , seçildiğinde bir bayrağın etkinleştirilmesini geçersiz kılmak için değişkene izin verir. ayarı status_overrideDisabled tam tersi bir işlev sağlar, bu nedenle değişken seçildiğinde bayrağı devre dışı bırakır. Durumu enabled olan bir false özellik geçersiz kılınamaz.

İkili değişkenli bir özellik bayrağı kullanıyorsanız özelliği status_override yararlı olabilir. Uygulamanızda olduğu gibi is_enabled API'leri kullanmaya devam etmenizi sağlarken, yüzdebirlik ayırma ve tohum gibi çeşitlemelerle birlikte gelen yeni özelliklerden yararlanmanızı sağlar.

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

Yukarıdaki örnekte özellik her zaman etkindir. Geçerli kullanıcı 10 ile 20 arasında hesaplanan yüzdebirlik aralığındaysa On , değişken döndürülür. Aksi takdirde, Off değişken döndürülür ve status_override değerine eşit Disabledolduğundan özellik artık devre dışı olarak kabul edilir.

Telemetri

Özellik bayrağı değişikliği dağıtıldığında, bunun uygulama üzerindeki etkisini analiz etmek genellikle önemlidir. Örneğin, ortaya çıkabilecek birkaç soru şunlardır:

  • Bayraklarım beklendiği gibi etkin/devre dışı mı?
  • Hedeflenen kullanıcılar beklendiği gibi belirli bir özelliğe erişiyor mu?
  • Belirli bir kullanıcı hangi çeşitle görüşüyor?

Bu tür sorular, özellik bayrağı değerlendirme olaylarının emisyonu ve analizi aracılığıyla yanıtlanabilir. Bu kitaplık isteğe bağlı olarak aracılığıyla AzureMonitorözellik bayrağı değerlendirmesi sırasında izleme telemetrisi üretmeyi etkinleştirirOpenTelemetry.

Telemetriyi etkinleştirme

Varsayılan olarak, özellik bayraklarında telemetri gösterilmez. Belirli bir özellik bayrağı için telemetri yayımlamak için bayrağı , telemetri emisyonu için etkinleştirildiğini BILDIRMESİ GEREKİR .

json'da tanımlanan özellik bayrakları için etkinleştirme özelliği kullanılarak telemetry gerçekleştirilir.

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

Yukarıdaki kod parçacığı, telemetri için etkinleştirilmiş adlı MyFeatureFlag bir özellik bayrağı tanımlar. Nesnenin telemetryenabled özelliği olarak trueayarlanır. özelliğinin enabled değeri, bayrak için telemetri yayımlamak için olmalıdır true .

Özellik telemetry bayrağının bölümü aşağıdaki özelliklere sahiptir:

Özellik Açıklama
enabled Özellik bayrağı için telemetrinin yayımlanıp yayımlanmayacağını belirtir.
metadata Değerlendirme olaylarına özellik bayrağı hakkında özel meta veriler eklemek için kullanılabilen, sözlük olarak modellenen anahtar-değer çiftleri koleksiyonu.

Ayrıca, oluştururken FeatureManagertelemetri olaylarını işlemek için bir geri çağırma kaydedilmelidir. Bu geri çağırma, bir özellik bayrağı değerlendirildiğinde ve bu bayrak için telemetri etkinleştirildiğinde çağrılır.

feature_manager = FeatureManager(feature_flags, on_feature_evaluated=publish_telemetry)

Application Insights telemetrisi

Özellik yönetimi kitaplığı, Application Insights'a özellik bayrağı değerlendirme verileri gönderen yerleşik bir telemetri yayımcısı sağlar. Application Insights'ı etkinleştirmek için özellik yönetimi kitaplığı aracılığıyla pip install FeatureManagement[AzureMonitor]Azure İzleyici ile yüklenebilir. Bu komut, OpenTelemetry kullanarak Application Insights'a telemetri stili uygulamak için kullanılan paketi yükler azure-monitor-events-extension .

Not

Paket azure-monitor-events-extension telemetriyi yalnızca Açık Telemetri işlem hattına ekler. Application Insights'ı kaydetme işlemi hala gereklidir.

from azure.monitor.opentelemetry import configure_azure_monitor

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

Telemetri olaylarını günlüğe kaydetme

Özellik yönetimi kitaplığı, telemetri olaylarını günlüğe kaydetmek için birden çok yol sağlar. Özellik bayrağı değerlendirme olayları için yerleşik geri aramayı kullanabilir veya kullanıcı etkileşimleri ve uygulama olayları için özel olayları el ile izleyebilirsiniz.

Özellik değerlendirme olayları

Telemetri geri çağırması bir işlev olduğundan, telemetriyi istenen herhangi bir hedefe yayımlayacak şekilde özelleştirilebilir. Örneğin, telemetri bir günlük hizmetine, veritabanına veya özel telemetri hizmetine yayımlanabilir.

Özellik bayrağı değerlendirildiğinde ve telemetri etkinleştirildiğinde, özellik yöneticisi telemetri geri çağırmasını bir EvaluationEvent parametreyle çağırır. EvaluationEvent aşağıdaki özellikleri içerir:

Etiket Açıklama
feature Kullanılan özellik bayrağı.
user Hedefleme için kullanılan kullanıcı kimliği.
enabled Özellik bayrağının etkin olarak değerlendirilip değerlendirilmediği.
Variant Atanan değişken.
VariantAssignmentReason Değişkenin atanma nedeni.

Özel olayları izleme

Otomatik özellik bayrağı değerlendirme telemetrisinin ötesinde, track_event işlevini kullanarak özel olayları el ile izleyebilirsiniz. Bu özellik bayrağı kullanımıyla bağıntılı olması gereken kullanıcı etkileşimlerini, iş olaylarını veya diğer özel telemetri verilerini izlemek için kullanışlıdır.

from featuremanagement.azuremonitor import track_event

# Track a custom event with a user identifier
track_event("ButtonClicked", "user123")

# Track an event without a user identifier
track_event("ApplicationStarted")

track_event İşlev iki parametre kabul eder:

Parametre Açıklama
event_name İzlenen olayın adı.
user Olayla ilişkilendirilecek isteğe bağlı kullanıcı tanımlayıcısı.

Özel olaylar, özellik bayrağı telemetrisi için yapılandırılan aynı Application Insights örneğine gönderilir ve özellik bayrağı değerlendirmelerini kullanıcı davranışı ve uygulama olaylarıyla ilişkilendirmenizi sağlar.

Telemetriyi hedefleme bağlamıyla zenginleştirme

Kullanıcı tanımlayıcılarını her track_event çağrısına el ile geçirmek yerine, tüm telemetri verilerini hedef bağlam bilgileriyle otomatik olarak zenginleştirmek için TargetingSpanProcessor kullanabilirsiniz. İşlemci, TargetingContext döndüren bir geri çağırma işlevini kabul eder ve telemetrinin her istek için kullanıcı kimliğini otomatik olarak eklemesine izin verir. Bu zenginleştirme, telemetri verilerini belirli kullanıcılar ve gruplarla ilişkilendirmeye yardımcı olur ve telemetri çağrılarınızda açık kullanıcı parametrelerine gerek kalmadan hedeflenen hedef kitleler için özellik bayrağı performansını çözümlemeyi kolaylaştırır.

Not

TargetingSpanProcessor özellikle telemetri zenginleştirmesine yöneliktir. Bir sağlayarak özellik bayrağı değerlendirmesi yapmanız gerekir. Bu, Hedefleme bağlam erişimcisi bölümünde açıklandığı gibi olmalıdır.

Aşağıdaki örnekte, kullanıcı tanımlayıcısı olarak istek üst bilgilerinden bir oturum kimliği kullanarak Quart uygulamasında işlemcinin nasıl yapılandırılır gösterilmektedir. Uygulama örneğinizi oluşturmadan önce düzgün başlatmayı sağlamak için configure_azure_monitor öğesini çağırın.

import os
from quart import request
from azure.monitor.opentelemetry import configure_azure_monitor
from featuremanagement import TargetingContext
from featuremanagement.azuremonitor import TargetingSpanProcessor

async def my_targeting_accessor() -> TargetingContext:
    session_id = ""
    if "Session-ID" in request.headers:
        session_id = request.headers["Session-ID"]
    return TargetingContext(user_id=session_id)

# Configure Azure Monitor with targeting context for telemetry
configure_azure_monitor(
    connection_string=os.getenv("APPLICATIONINSIGHTS_CONNECTION_STRING"),
    span_processors=[TargetingSpanProcessor(targeting_context_accessor=my_targeting_accessor)],
)

# You must also provide the targeting context accessor to FeatureManager for evaluation
feature_manager = FeatureManager(config, targeting_context_accessor=my_targeting_accessor)

Sonraki adımlar

Uygulamalarınızda özellik bayraklarını kullanmayı öğrenmek için aşağıdaki hızlı başlangıçlara geçin.

Python

Özellik filtrelerini kullanmayı öğrenmek için aşağıdaki öğreticilere geçin.

Özellik filtreleri ile koşullu özellikleri etkinleştirme

Zamanlamaya göre özellikleri etkinleştirme

Özellikleri hedeflenen hedef kitlelere sunma

  • Last updated on