Partager via

Gestion des fonctionnalités Python

La bibliothèque de gestion des fonctionnalités Python permet de développer et d’exposer des fonctionnalités d’application basées sur des indicateurs de fonctionnalité. Une fois qu’une nouvelle fonctionnalité est développée, de nombreuses applications ont des exigences particulières, par exemple quand la fonctionnalité doit être activée et dans quelles conditions. Cette bibliothèque permet de définir ces relations et s’intègre également aux modèles de code Python courants pour rendre l’exposition de ces fonctionnalités possible.

Les indicateurs de fonctionnalité permettent aux applications Python d’activer ou de désactiver dynamiquement des fonctionnalités. Les développeurs peuvent utiliser des indicateurs de fonctionnalité dans des cas d’utilisation simples tels que des instructions conditionnelles.

Voici certains des avantages liés à l’utilisation de la bibliothèque de gestion des fonctionnalités Python :

  • Une convention commune pour la gestion des fonctionnalités

  • Prise en main rapide

    • Prise en charge de la configuration d’indicateurs de fonctionnalité JSON

  • Gestion de la durée de vie des indicateurs de fonctionnalité

    • Les valeurs de configuration peuvent changer en temps réel ; les indicateurs de fonctionnalité peuvent être cohérents sur l’ensemble de la requête

  • Scénarios simples à complexes couverts

    • Activation/désactivation des fonctionnalités au moyen du fichier de configuration déclaratif
    • Évaluation dynamique de l’état de la fonctionnalité en fonction de l’appel au serveur

    La bibliothèque de gestion des fonctionnalités Python est open source. Pour plus d’informations, visitez le dépôt GitHub.

Indicateurs de fonctionnalités

Les indicateurs de fonctionnalité se composent de deux éléments : un nom et une liste de filtres de fonctionnalité permettant d’activer la fonctionnalité.

Filtres de fonctionnalité

Les filtres de fonctionnalités définissent un scénario pour lequel une fonctionnalité doit être activée. Lorsqu’une fonctionnalité est évaluée pour savoir si elle est activée ou désactivée, sa liste de filtres de fonctionnalité est parcourue jusqu’à ce que l’un des filtres décide que la fonctionnalité doit être activée. À ce stade, la fonctionnalité est considérée comme activée et le parcours des filtres de fonctionnalité s’arrête. Si aucun filtre de fonctionnalité n’indique que la fonctionnalité doit être activée, elle est considérée comme désactivée.

Par exemple, un filtre de fonctionnalités de navigateur Microsoft Edge peut être conçu. Ce filtre de fonctionnalité active toutes les fonctionnalités auxquelles il est attaché, à condition qu’une requête HTTP provienne de Microsoft Edge.

Configuration de l’indicateur de fonctionnalité

Un dictionnaire Python permet de définir des indicateurs de fonctionnalité. Le dictionnaire se compose de noms de fonctionnalité en tant que clés et d’objets d’indicateur de fonctionnalité en tant que valeurs. L’objet d’indicateur de fonctionnalité est un dictionnaire comportant une clé conditions, qui elle-même contient la clé client_filters. La clé client_filters est une liste de filtres de fonctionnalité permettant de déterminer si la fonctionnalité doit être activée.

Déclaration d’indicateur de fonctionnalité

La bibliothèque de gestion des fonctionnalités prend en charge JSON comme source d’indicateurs de fonctionnalité. Vous trouverez ci-dessous un exemple du format permettant de configurer des indicateurs de fonctionnalité dans un fichier 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"
                            }
                        }
                    ]
                }
            }
        ]
    }
}

La section feature_management du document JSON permet par convention de charger les paramètres d’indicateur de fonctionnalité. La section feature_flags est une liste des indicateurs de fonctionnalité chargés dans la bibliothèque. Dans la section ci-dessus, nous voyons trois fonctionnalités différentes. Les fonctionnalités définissent leurs filtres de fonctionnalité à l’aide de la propriété client_filters, dans conditions. Dans les filtres de fonctionnalité pour FeatureT, nous voyons que enabled est défini sur true sans aucun filtre défini, ce qui fait que FeatureT renvoie toujours true. FeatureU est identique à FeatureT, mais avec enabled défini sur false, ce qui fait que la fonctionnalité renvoie toujours false. FeatureV spécifie un filtre de fonctionnalité nommé Microsoft.TimeWindow. FeatureV est un exemple de filtre de fonctionnalité configurable. Nous pouvons voir dans l’exemple que le filtre a une propriété parameters. La propriété parameters permet de configurer le filtre. Dans ce cas, les heures de début et de fin d’activation de la fonctionnalité sont configurées.

Le schéma détaillé de la section feature_management est disponible ici.

Avancé : l’utilisation du signe deux-points (:) est interdite dans les noms d’indicateurs de fonctionnalité.

Déclaration d’activation/désactivation

L’extrait de code suivant illustre une autre façon de définir une fonctionnalité qui peut être utilisée pour l’activation/désactivation de fonctionnalités.

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

Type d’exigence

La propriété requirement_type d’un indicateur de fonctionnalité permet de déterminer si les filtres doivent utiliser la logique Any ou All lors de l’évaluation de l’état d’une fonctionnalité. Si requirement_type n’est pas spécifié, la valeur par défaut est Any.

  • Any signifie qu’un seul filtre doit renvoyer true afin que la fonctionnalité soit activée.
  • All signifie que tous les filtres doivent renvoyer true afin que la fonctionnalité soit activée.

Un requirement_type de All modifie le parcours. Tout d’abord, s’il n’existe aucun filtre, la fonctionnalité est désactivée. Ensuite, les filtres de fonctionnalité sont parcourus jusqu’à ce que l’un des filtres décide que la fonctionnalité doit être désactivée. Si aucun filtre n’indique que la fonctionnalité doit être désactivée, elle est considérée comme activée.

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

Dans l’exemple ci-dessus, FeatureW spécifie le requirement_typeAll. Autrement dit, tous ses filtres doivent renvoyer true afin que la fonctionnalité soit activée. Dans ce cas, la fonctionnalité est activée pour 50 % des utilisateurs pendant la fenêtre de temps spécifiée.

Consommation

La forme de base de la gestion des fonctionnalités consiste à vérifier si un indicateur de fonctionnalité est activé, puis à effectuer des actions en fonction du résultat. La vérification de l’état d’un indicateur de fonctionnalité est effectuée à l’aide de la méthode is_enabled de FeatureManager.

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

Les feature_flags fournis à FeatureManager peuvent être le AzureAppConfigurationProvider ou un dictionnaire d’indicateurs de fonctionnalité.

Implémentation d’un filtre de fonctionnalité

La création d’un filtre de fonctionnalités permet d’activer des fonctionnalités en fonction des critères que vous définissez. Pour implémenter un filtre de fonctionnalités, l’interface FeatureFilter doit être implémentée. FeatureFilter a une méthode unique nommée evaluate. Lorsqu’une fonctionnalité spécifie qu’elle peut être activée pour un filtre de fonctionnalités, la méthode evaluate est appelée. Si evaluate renvoie true, la fonctionnalité doit être activée.

L’extrait de code suivant montre comment ajouter un filtre de fonctionnalité personnalisé MyCustomFilter.

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

Pour inscrire des filtres de fonctionnalité, vous devez les fournir à la propriété feature_filters lors de la création de FeatureManager. Si un filtre de fonctionnalité personnalisé a besoin d’un contexte, il peut être transmis lors de l’appel de is_enabled à l’aide de kwargs.

Attribut d’alias de filtre

Lorsqu’un filtre de fonctionnalité est inscrit pour un indicateur de fonctionnalité, le nom du filtre est utilisé comme alias par défaut.

Vous pouvez remplacer l’identificateur du filtre de fonctionnalité à l’aide de l’attribut @FeatureFilter.alias("MyFilter"). Un filtre de fonctionnalité peut être décoré avec cet attribut pour déclarer le nom permettant dans la configuration de référencer ce filtre de fonctionnalité dans un indicateur de fonctionnalité.

Filtres de fonctionnalité manquants

Si une fonctionnalité est configurée pour être activée pour un filtre de fonctionnalité spécifique et que ce filtre de fonctionnalité n’est pas inscrit, une exception ValueError est générée lorsque la fonctionnalité est évaluée.

Filtres de fonctionnalité intégrés

Deux filtres de fonctionnalité sont fournis avec le package FeatureManagement : TimeWindowFilter et TargetingFilter.

Chacun des filtres de fonctionnalités intégrés a ses propres paramètres. Voici la liste des filtres de fonctionnalités, ainsi que des exemples.

Microsoft.TimeWindow

Le Microsoft.TimeWindow filtre permet d’activer une fonctionnalité en fonction d’une fenêtre de temps.

  • Si vous spécifiez uniquement une End valeur, la fonctionnalité est considérée comme activée jusqu’à ce moment.
  • Si spécifiez une seule valeur Start, la fonctionnalité est considérée comme activée sur tous les points après cette heure.
{
    "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"
                }
            }
        ]
    }
}

Vous pouvez configurer le filtre pour appliquer une fenêtre de temps périodique. Cette fonctionnalité peut être utile lorsque vous devez activer une fonctionnalité pendant une période de faible trafic ou de trafic élevé d’un jour ou d’un certain jour d’une semaine. Pour étendre une fenêtre de temps individuelle à une fenêtre de temps périodique, vous utilisez un Recurrence paramètre pour spécifier une règle de périodicité.

Remarque

Pour utiliser la périodicité, vous devez spécifier Start et End valeurs. En cas de périodicité, la partie date de la valeur End ne spécifie pas de date de fin pour que le filtre soit considéré comme actif. Au lieu de cela, le filtre utilise la date de fin, par rapport à la date de début, pour définir la durée de la fenêtre d’heure qui se répète.

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

Les Recurrence paramètres sont constitués de deux parties :

  • Les Pattern paramètres spécifient la fréquence à laquelle la fenêtre de temps se répète.
  • Les Range paramètres spécifient la durée pendant laquelle le modèle de périodicité se répète.

Modèle de périodicité

Il existe deux types de modèles de périodicité possibles : Daily et Weekly. Par exemple, une fenêtre de temps peut se répéter tous les jours, tous les trois jours, tous les lundis ou tous les autres vendredis.

Selon le type, certains champs des Pattern paramètres sont obligatoires, facultatifs ou ignorés.

  • Daily

    Le modèle de périodicité quotidienne entraîne la répétition de la fenêtre de temps en fonction d’un nombre spécifié de jours entre chaque occurrence.

    Propriété Pertinence Description
    Type Obligatoire Type de modèle de périodicité. Cette propriété doit être définie sur Daily.
    Interval Optional Nombre de jours entre chaque occurrence. La valeur par défaut est 1.

  • Weekly

    Le modèle de périodicité hebdomadaire entraîne la répétition de la fenêtre de temps le ou les mêmes jours de la semaine. Toutefois, vous pouvez spécifier le nombre de semaines entre chaque ensemble d’occurrences.

    Propriété Pertinence Description
    Type Obligatoire Type de modèle de périodicité. Cette propriété doit être définie sur Weekly.
    DaysOfWeek Obligatoire Les jours de la semaine sur lesquels l’événement se produit.
    Interval Optional Nombre de semaines entre chaque ensemble d’occurrences. La valeur par défaut est 1.
    FirstDayOfWeek Optional Jour à utiliser comme premier jour de la semaine. La valeur par défaut est Sunday.

    L’exemple suivant répète la fenêtre de temps tous les autres lundi et mardi :

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

Remarque

La Start valeur doit être une première occurrence valide qui correspond au modèle de périodicité. En outre, la durée de la fenêtre de temps ne peut pas être plus longue que la fréquence à laquelle elle se produit. Par exemple, une fenêtre de temps de 25 heures ne peut pas se reproduire tous les jours.

Plage de périodicité

Il existe trois types de plages de périodicité possibles : NoEnd, EndDateet Numbered.

  • NoEnd

    L'NoEnd intervalle provoque une récurrence indéfinie.

    Propriété Pertinence Description
    Type Obligatoire Type de plage de périodicité. Cette propriété doit être définie sur NoEnd.

  • EndDate

    La plage EndDate déclenche l’ouverture de la fenêtre de temps chaque jour correspondant au modèle pertinent jusqu’à la date de fin.

    Propriété Pertinence Description
    Type Obligatoire Type de plage de périodicité. Cette propriété doit être définie sur EndDate.
    EndDate Obligatoire Date et heure d’arrêt de l’application du modèle. Si l’heure de début de la dernière occurrence tombe avant la date de fin, l’heure de fin de cette occurrence peut s’étendre au-delà de celle-ci.

    Dans l’exemple suivant, la fenêtre de temps se répète tous les jours jusqu’au dernier événement le 1er avril 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

    La plage Numbered provoque l'occurrence d'une fenêtre de temps un nombre de fois spécifié.

    Propriété Pertinence Description
    Type Obligatoire Type de plage de périodicité. Cette propriété doit être définie sur Numbered.
    NumberOfOccurrences Obligatoire Nombre d’occurrences.

    Dans l’exemple suivant, la fenêtre de temps se répète le lundi et le mardi pour un total de trois occurrences, qui se produisent à la date suivante :

    • Lundi 1er avril
    • Mardi 2 avril
    • Lundi 8 avril
    "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
    }
}

Pour créer une règle de récurrence, vous devez spécifier les paramètres Pattern et Range. N’importe quel type de modèle peut fonctionner avec n’importe quel type de plage.

Avancé: Le décalage de fuseau horaire de la Start propriété est appliqué aux paramètres de périodicité.

Microsoft.Targeting

Ce filtre permet d’activer une fonctionnalité pour une audience cible. Une explication détaillée du ciblage est expliquée dans la section Ciblage ci-dessous. Les paramètres de filtre incluent un objet Audience qui décrit les utilisateurs, les groupes, les utilisateurs et groupes exclus et un pourcentage par défaut de la base d’utilisateurs qui doit avoir accès à la fonctionnalité. Chaque objet de groupe répertorié dans la section Groups doit également spécifier le pourcentage des membres du groupe qui doivent disposer d’un accès. Si un utilisateur est spécifié dans la section Exclusion, directement ou si l’utilisateur se trouve dans un groupe exclu, la fonctionnalité est désactivée. Sinon, si un utilisateur est spécifié directement dans la section Users, ou si l’utilisateur se trouve dans le pourcentage inclus de l’un des déploiements de groupe, ou si l’utilisateur tombe dans le pourcentage de déploiement par défaut, cette fonctionnalité est activée.

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

Ciblage

Le ciblage est une stratégie de gestion des fonctionnalités qui permet aux développeurs de déployer progressivement de nouvelles fonctionnalités sur leur base d’utilisateurs. La stratégie repose sur le concept de ciblage d’un ensemble d’utilisateurs appelé public cible. Un public est constitué d’utilisateurs, de groupes spécifiques, d’utilisateurs et de groupes exclus, et d’un pourcentage désigné de l’ensemble de la base d’utilisateurs. Les groupes inclus dans le public peuvent être divisés en pourcentages de leurs membres totaux.

Les étapes suivantes illustrent un exemple de déploiement progressif d’une nouvelle fonctionnalité « Bêta » :

  1. Les utilisateurs individuels Jeff et Alicia ont accès à la fonctionnalité Bêta.
  2. Un autre utilisateur, Mark, demande à participer et est inclus.
  3. Vingt pour cent d’un groupe appelé utilisateurs « Ring1 » sont inclus dans la fonctionnalité Bêta.
  4. Le nombre d’utilisateurs « Ring1 » inclus dans la fonctionnalité Bêta est passé à 100 %.
  5. Cinq pour cent de la base d’utilisateurs sont inclus dans la fonctionnalité Bêta.
  6. Le pourcentage de déploiement est passé à 100 % et la fonctionnalité est entièrement déployée.

Cette stratégie de déploiement d’une fonctionnalité est intégrée à la bibliothèque via le filtre de fonctionnalité Microsoft.Targeting inclus.

Ciblage d’un utilisateur

Vous pouvez spécifier directement un utilisateur dans l’appel is_enabled ou spécifier l’utilisateur et le groupe facultatif à l’aide d’un 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 de ciblage

Lors de la définition d’une audience, vous pouvez exclure des utilisateurs et des groupes de l’audience. Les exclusions sont utiles pour déployer une fonctionnalité sur un groupe d’utilisateurs en excluant quelques utilisateurs ou groupes du déploiement. L’exclusion est définie en ajoutant une liste d’utilisateurs et de groupes à la propriété Exclusion du public.

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

Dans l’exemple ci-dessus, la fonctionnalité est activée pour les utilisateurs nommés Jeff et Alicia. Elle est également activée pour les utilisateurs du groupe nommé Ring0. Toutefois, si l’utilisateur est nommé Mark, la fonctionnalité est désactivée, qu’il se trouve dans le groupe Ring0 ou non. Les exclusions sont prioritaires sur le reste du filtre de ciblage.

Variantes

Lorsque de nouvelles fonctionnalités sont ajoutées à une application, il peut arriver qu’une fonctionnalité ait différentes options de conception proposées. Une solution courante pour décider d’une conception est une forme de test A/B. Un test A/B consiste à fournir une version différente de la fonctionnalité à différents segments de la base d’utilisateurs et de choisir une version en fonction des interactions utilisateur. Dans cette bibliothèque, cette fonctionnalité est activée en représentant différentes configurations d’une fonctionnalité avec des variantes.

Les variantes permettent à un indicateur de fonctionnalité de devenir plus qu’un simple indicateur d’activation/de désactivation. Une variante représente une valeur d’un indicateur de fonctionnalité qui peut être une chaîne, un nombre, une valeur booléenne ou même un objet de configuration. Un indicateur de fonctionnalité qui déclare des variantes doit définir les circonstances dans lesquelles chaque variante doit être utilisée, ce qui est abordé plus en détail dans la section Allocation de variantes.

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

Obtention de variantes

Pour chaque fonctionnalité, une variante peut être récupérée dans le FeatureManager à l’aide de sa méthode 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

La variante renvoyée dépend de l’utilisateur en cours d’évaluation, et ces informations sont obtenues à partir d’une instance de TargetingContext.

Déclaration d’indicateur de fonctionnalité de variante

Par rapport aux indicateurs de fonctionnalité standard, les indicateurs de fonctionnalité de variante ont deux propriétés supplémentaires : variants et allocation. La propriété variants est un tableau qui contient les variantes définies pour cette fonctionnalité. La propriété allocation définit la façon dont ces variantes doivent être allouées pour la fonctionnalité. Au même titre que la déclaration d’indicateurs de fonctionnalité standard, vous pouvez configurer des indicateurs de fonctionnalité de variante dans un fichier JSON. Voici un exemple d’indicateur de fonctionnalité de variante.

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

Définition de variantes

Chaque variante a deux propriétés : un nom et une configuration. Le nom est utilisé pour faire référence à une variante spécifique, et la configuration est la valeur de cette variante. La configuration peut être définie à l’aide de la propriété configuration_value. configuration_value est une configuration inline qui peut être une chaîne, un nombre, une valeur booléenne ou un objet de configuration. Si vous ne spécifiez pas configuration_value, la propriété Configuration de la variante renvoyée est None.

Une liste de toutes les variantes possibles est définie pour chaque fonctionnalité sous la propriété variants.

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

Allocation de variantes

Le processus d’allocation des variantes d’une fonctionnalité est déterminé par la propriété allocation de la fonctionnalité.

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

Le paramètre allocation d’une fonctionnalité a les propriétés suivantes :

Propriété Description
default_when_disabled Spécifie quelle variante doit être utilisée lorsqu’une variante est demandée alors que la fonctionnalité est considérée comme désactivée.
default_when_enabled Spécifie la variante à utiliser lorsqu’une variante est demandée alors que la fonctionnalité est considérée comme activée et qu’aucune autre variante n’a été affectée à l’utilisateur.
user Spécifie une variante et une liste d’utilisateurs auxquels cette variante doit être affectée.
group Spécifie une variante et une liste de groupes. La variante est affectée si l’utilisateur se trouve dans au moins l’un des groupes.
percentile Spécifie une variante et une plage de pourcentages dans laquelle le pourcentage calculé de l’utilisateur doit se trouver pour que cette variante soit affectée.
seed Valeur sur laquelle les calculs de pourcentage pour percentile sont basés. Le calcul du pourcentage pour un utilisateur spécifique est le même sur l’ensemble des fonctionnalités si la même valeur seed est utilisée. Si aucune seed n’est spécifiée, une valeur initiale par défaut est créée en fonction du nom de la fonctionnalité.

Si la fonctionnalité n’est pas activée, le gestionnaire de fonctionnalités affecte la variante marquée comme default_when_disabled à l’utilisateur actuel, à savoir Small dans ce cas.

Si la fonctionnalité est activée, le gestionnaire de fonctionnalités vérifie les allocations user, group et percentile dans cet ordre pour affecter une variante. Pour cet exemple particulier, si l’utilisateur évalué est nommé Marsha, dans le groupe nommé Ring1, ou si l’utilisateur se trouve entre le 0 et le 10e centile, la variante spécifiée est affectée à l’utilisateur. Dans ce cas, tous les utilisateurs affectés renvoient la variante Big. Si aucune de ces allocations ne correspond, l’utilisateur reçoit la variante default_when_enabled, à savoir Small.

La logique d’allocation est semblable au filtre de fonctionnalité Microsoft.Targeting, mais certains paramètres présents dans le ciblage ne sont pas dans l’allocation, et inversement. Les résultats du ciblage et de l’allocation ne sont pas liés.

Remplacement de l’état activé par une variante

Vous pouvez utiliser des variantes pour remplacer l’état activé d’un indicateur de fonctionnalité. Le remplacement permet aux variantes d’étendre l’évaluation d’un indicateur de fonctionnalité. Lorsque vous appelez is_enabled sur un indicateur avec des variantes, le gestionnaire de fonctionnalités vérifie si la variante affectée à l’utilisateur actuel est configurée pour remplacer le résultat. Le remplacement est effectué à l’aide de la propriété de variante facultative status_override. Par défaut, cette propriété est définie sur None. Autrement dit, la variante n’affecte pas le fait que l’indicateur soit considéré comme activé ou désactivé. Définir status_override sur Enabled permet à la variante, lorsqu’elle est choisie, de modifier un indicateur afin de l’activer. Définir status_override sur Disabled entraîne le comportement opposé, c’est-à-dire que l’indicateur est désactivé lorsque la variante est choisie. Une fonctionnalité avec un état enabled de false ne peut pas être remplacée.

Si vous utilisez un indicateur de fonctionnalité avec des variantes binaires, la propriété status_override peut être utile. Elle vous permet de continuer à utiliser des API telles que is_enabled dans votre application, tout en bénéficiant des nouvelles fonctionnalités fournies avec des variantes, notamment l’allocation de centile et les valeurs initiales.

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

Dans l’exemple ci-dessus, la fonctionnalité est toujours activée. Si l’utilisateur actuel se trouve dans la plage de centile calculée de 10 à 20, la variante On est renvoyée. Sinon, la variante Off est retournée et, car status_override est égal à Disabled, et la fonctionnalité sera désormais considérée comme désactivée.

Télémétrie

Lorsqu’un changement d’indicateur de fonctionnalité est déployé, il est souvent important d’analyser son effet sur une application. Par exemple, voici quelques questions qui peuvent survenir :

  • Mes indicateurs sont-ils activés/désactivés comme prévu ?
  • Les utilisateurs ciblés ont-ils accès à une certaine fonctionnalité comme prévu ?
  • Quelle variante un utilisateur particulier voit-il ?

Il est possible de répondre à ces types de questions par le biais de l’émission et de l’analyse des événements d’évaluation des indicateurs de fonctionnalité. Cette bibliothèque permet éventuellement à AzureMonitor de produire des données de télémétrie de traçage pendant l’évaluation des indicateurs de fonctionnalité au moyen d’OpenTelemetry.

Activation de la télémétrie

Par défaut, les indicateurs de fonctionnalité n’émettent pas de données de télémétrie. Pour publier des données de télémétrie pour un indicateur de fonctionnalité donné, l’indicateur DOIT déclarer qu’il est activé pour l’émission de données de télémétrie.

Pour les indicateurs de fonctionnalité définis en JSON, l’activation est effectuée à l’aide de la propriété telemetry.

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

L’extrait de code ci-dessus définit un indicateur de fonctionnalité nommé MyFeatureFlag qui est activé pour les données de télémétrie. La propriété enabled de l’objet telemetry est définie sur true. La valeur de la propriété enabled doit être true pour publier des données de télémétrie pour l’indicateur.

La section telemetry d’un indicateur de fonctionnalité a les propriétés suivantes :

Propriété Description
enabled Spécifie si les données de télémétrie doivent être publiées pour l’indicateur de fonctionnalité.
metadata Collection de paires clé-valeur, modélisées en tant que dictionnaire, permettant d’attacher des métadonnées personnalisées sur l’indicateur de fonctionnalité aux événements d’évaluation.

En outre, lors de la création de FeatureManager, un rappel doit être inscrit pour gérer les événements de télémétrie. Ce rappel est appelé chaque fois qu’un indicateur de fonctionnalité est évalué et que la télémétrie est activée pour cet indicateur.

feature_manager = FeatureManager(feature_flags, on_feature_evaluated=publish_telemetry)

Application Insights Telemetry

La bibliothèque de gestion des fonctionnalités fournit un éditeur de télémétrie intégré qui envoie les données d’évaluation des indicateurs de fonctionnalité à Application Insights. Pour activer Application Insights, vous pouvez installer la bibliothèque de gestion des fonctionnalités avec Azure Monitor au moyen de pip install FeatureManagement[AzureMonitor]. Cette commande installe le package azure-monitor-events-extension, qui permet d’appliquer un style aux données de télémétrie dans Application Insights à l’aide d’OpenTelemetry.

Remarque

Le package azure-monitor-events-extension ajoute uniquement les données de télémétrie au pipeline Open Telemetry. L’inscription d’Application Insights est toujours requise.

from azure.monitor.opentelemetry import configure_azure_monitor

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

Publication de données de télémétrie personnalisées

Le rappel de télémétrie étant une fonction, vous pouvez le personnaliser pour publier des données de télémétrie sur toute destination souhaitée. Par exemple, vous pouvez publier des données de télémétrie sur un service de journalisation, une base de données ou un service de télémétrie personnalisé.

Lorsqu’un indicateur de fonctionnalité est évalué et que la télémétrie est activée, le gestionnaire de fonctionnalités appelle le rappel de télémétrie avec un paramètre EvaluationEvent. EvaluationEvent comporte les propriétés suivantes :

Tag Description
feature Indicateur de fonctionnalité utilisé.
user ID utilisateur utilisé pour le ciblage.
enabled Indique si l’indicateur de fonctionnalité est évalué comme activé.
Variant Variante affectée.
VariantAssignmentReason Raison pour laquelle la variante est affectée.

Étapes suivantes

Pour découvrir comment utiliser des indicateurs de fonctionnalité dans vos applications, passez aux guides de démarrage rapide suivants.

Python

Pour découvrir comment utiliser des filtres de fonctionnalités, passez aux tutoriels suivants.

Activer des fonctionnalités conditionnelles avec des filtres de fonctionnalité

Activer des fonctionnalités selon un calendrier

Déployer des fonctionnalités pour des audiences ciblées

  • Last updated on