Compartir a través de

Administración de funciones de Python

La biblioteca de administración de funciones de Python permite desarrollar y exponer las funcionalidades de la aplicación en función de los marcadores de funciones. Una vez desarrollada una nueva función, muchas aplicaciones tienen requisitos especiales, como cuándo se debe habilitar la función y en qué condiciones. Esta biblioteca ofrece una forma de definir estas relaciones y también se integra en patrones de código de Python comunes para hacer posible la exposición de estas funciones.

Los marcadores de funciones son una manera de que las aplicaciones de Python activen o desactiven dinámicamente las funciones. Los desarrolladores pueden usar marcadores de funciones en casos de uso simples, como instrucciones condicionales.

Estas son algunas de las ventajas de usar la biblioteca de administración de funciones de Python:

  • Una convención común para la administración de funciones

  • Baja barrera de entrada

    • Admite la configuración de marcadores de funciones JSON

  • Administración de la duración de marcadores de funciones

    • Los valores de configuración pueden cambiar en tiempo real; las marcadores de funciones pueden ser coherentes en toda la solicitud

  • Se adapta a casos sencillos a complejos

    • Activar o desactivar funciones mediante el archivo de configuración declarativo
    • Evaluar dinámicamente el estado de la función según la llamada al servidor

    La biblioteca de administración de funciones de Python es de código abierto. Para obtener más información, visite el repositorio de GitHub.

Marcas de funciones

Las marcadores de funciones se componen de dos partes, un nombre y una lista de filtros de funciones que se usan para activar la función.

Filtros de funciones

Los filtros de funciones definen un escenario para cuando se debe habilitar una función. Cuando se evalúa si una función está activada o desactivada, se recorre su lista de filtros de funciones hasta que uno de los filtros decide que la función debe estar habilitada. En este momento, la función se considera habilitada y se recorre a través de los filtros de funciones se detiene. Si no hay ningún filtro de funciones que indique que la función debe estar habilitada, se considera deshabilitada.

Por ejemplo, se podría diseñar un filtro de funciones del explorador Microsoft Edge. Este filtro de funciones activaría cualquiera a la que está asociada siempre que una solicitud HTTP provenga de Microsoft Edge.

Configuración de marcadores de funciones

Se usa un diccionario de Python para definir los marcadores de funciones. El diccionario se compone de nombres de funciones como claves y objetos de marcadores de funciones como valores. El objeto de marcadores de funciones es un diccionario que incluye una clave conditions, que asimismo contiene la clave client_filters. La clave client_filters es una lista de filtros de funciones que se usan para determinar si se debe habilitar la función.

Declaración de la marca de funciones

La biblioteca de administración de funciones admite json como fuente de marcadores de funciones. El siguiente es un ejemplo del formato usado para configurar marcadores de funciones en un archivo 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 sección feature_management del documento json se usa por convención para cargar la configuración de la marca de funciones. La sección feature_flags es una lista de las marcadores de funciones que se cargan en la biblioteca. En la sección anterior, vemos tres funciones diferentes. Las funciones definen sus filtros de funciones usando la propiedad client_filters, dentro de conditions. En los filtros de funciones de FeatureT, vemos que enabled es true sin filtros definidos, lo que da como resultado que FeatureT devuelva siempre true. FeatureU es igual que FeatureT per con enabled es false, dando como resultado que la función siempre devuelva false. FeatureV especifica un filtro de funciones denominado Microsoft.TimeWindow. FeatureV es un ejemplo de filtro de funciones configurable. Podemos ver en el ejemplo que el filtro tiene una propiedad parameters. La propiedad parameters se usa para configurar el filtro. En este caso, se configuran las horas de inicio y finalización de la función que se va a activar.

Puede encontrar el esquema detallado de la sección feature_managementaquí.

Avanzado: El uso de dos puntos ":" está prohibido en los nombres de marcadores de funciones.

Declaración activada/desactivada

En el fragmento de código siguiente se muestra una manera alternativa de definir una función que se puede usar para las funciones activadas y desactivadas.

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

Tipo de requisito

La propiedad requirement_type de una marca de función se usa para determinar si los filtros deben usar Any o All lógica al evaluar el estado de una función. Si no se especifica requirement_type, el valor predeterminado es Any.

  • Any significa que solo un filtro debe evaluarse como true para que se habilite la función.
  • All significa que cada filtro debe evaluarse como true para que se habilite la función.

Un requirement_type de All cambia el recorrido. En primer lugar, si no hay ningún filtro, la función está deshabilitada. A continuación, los filtros de funciones se recorren hasta que uno de los filtros decide que la función debe deshabilitarse. Si no hay ningún filtro que indique que la función debe deshabilitarse, se considera habilitada.

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

En el ejemplo anterior, FeatureW especifica un requirement_type de All, lo que significa que todos sus filtros deben evaluarse como true para que se habilite la función. En este caso, la función está habilitada para el 50 % de los usuarios durante el período de tiempo especificado.

Consumo

La forma básica de administración de funciones es comprobar si está habilitada una marca de función y, a continuación, realizar acciones en función del resultado. La comprobación del estado de una marca de función se realiza en FeatureManager a través del método is_enabled.

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

El feature_flags facilitado para FeatureManager puede ser AzureAppConfigurationProvider o un diccionario de marcadores de funciones.

Implementación de un filtro de funciones

La creación de un filtro de funciones proporciona una manera de habilitar las funciones en función de los criterios que defina. Para implementar un filtro de funciones, se debe implementar la interfaz FeatureFilter. FeatureFilter tiene un único método denominado evaluate. Cuando una función especifica que se puede habilitar para un filtro de funciones, se llama al método evaluate. Si evaluate devuelve true, significa que la función debe estar habilitada.

En el fragmento de código siguiente se muestra cómo agregar un filtro de funciones personalizado MyCustomFilter.

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

Los filtros de funciones se registran al pasarlos a la propiedad feature_filters cuando se crea FeatureManager. Si un filtro de funciones personalizado necesita algún contexto, se pueden pasar al llamar a is_enabled mediante kwargs.

Atributo de alias de filtro

Cuando se registra un filtro de funciones para un marcador de funciones, el nombre del filtro se usa como alias de forma predeterminada.

El identificador del filtro de funciones se puede invalidar mediante @FeatureFilter.alias("MyFilter"). Un filtro de funciones se puede decorar con este atributo para declarar el nombre que se debe usar en la configuración para hacer referencia a este filtro de funciones dentro de una marca de función.

Filtros de funciones no disponibles

Si una función está configurada para ser habilitada en un filtro de funciones específico y ese filtro de funciones no está registrado, se produce una excepción ValueError al evaluar la función.

Filtros de funciones integrados

Hay dos filtros de funciones que vienen con el paquete FeatureManagement: TimeWindowFilter y TargetingFilter.

Cada uno de los filtros de funciones integrados tiene sus propios parámetros. Esta es la lista de filtros de funciones junto con ejemplos.

Microsoft.TimeWindow

El Microsoft.TimeWindow filtro proporciona una manera de habilitar una característica basada en un período de tiempo.

  • Si especifica solo un valor End, la característica se considera activada hasta ese momento.
  • Si especifica solo el valor Start, la función se considera activa en todos los puntos después de ese momento.
{
    "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"
                }
            }
        ]
    }
}

Puede configurar el filtro para aplicar un período de tiempo de forma periódica. Esta funcionalidad puede ser útil cuando necesita activar una característica durante un período de tráfico bajo o de alto tráfico de un día o de determinados días de una semana. Para expandir un período de tiempo individual a un período de tiempo periódico, use un Recurrence parámetro para especificar una regla de periodicidad.

Nota:

Para usar la periodicidad, debe especificar los Start y End valores. Con recurrencia, la parte de fecha del valor End no especifica una fecha de finalización para considerar el filtro activo. En su lugar, el filtro usa la fecha de finalización, relativa a la fecha de inicio, para definir la duración del período de tiempo que se repite.

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

La Recurrence configuración consta de dos partes:

  • La Pattern configuración especifica la frecuencia con la que se repite la ventana de tiempo.
  • La Range configuración especifica durante cuánto tiempo se repite el patrón de periodicidad.

Patrón de periodicidad

Hay dos tipos de patrón de periodicidad posibles: Daily y Weekly. Por ejemplo, una ventana de tiempo puede repetirse cada día, cada tres días, cada lunes o cada otro viernes.

Según el tipo, ciertos campos de la Pattern configuración pueden ser obligatorios, opcionales o ignorados.

  • Daily

    El patrón de periodicidad diaria hace que la ventana de tiempo se repita en función de un número especificado de días entre cada repetición.

    Propiedad Pertinencia Descripción
    Type Obligatorio Tipo de patrón de periodicidad. Debe establecerse en Daily.
    Interval Opcional Número de días entre cada repetición. El valor predeterminado es 1.

  • Weekly

    El patrón de periodicidad semanal hace que la ventana de tiempo se repita el mismo día o días de la semana. Pero puede especificar el número de semanas entre cada conjunto de ocurrencias.

    Propiedad Pertinencia Descripción
    Type Obligatorio Tipo de patrón de periodicidad. Debe establecerse en Weekly.
    DaysOfWeek Obligatorio Días de la semana en los que se produce el evento.
    Interval Opcional Número de semanas entre cada conjunto de eventos. El valor predeterminado es 1.
    FirstDayOfWeek Opcional El día que se va a usar como primer día de la semana. El valor predeterminado es Sunday.

    En el ejemplo siguiente se repite la ventana de tiempo cada otro lunes y martes:

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

Nota:

El Start valor debe ser una primera aparición válida que se ajuste al patrón de periodicidad. Además, la duración del período de tiempo no puede ser mayor que la frecuencia con la que se produce. Por ejemplo, un período de tiempo de 25 horas no se puede repetir todos los días.

Intervalo de periodicidad

Hay tres tipos de intervalos de periodicidad posibles: NoEnd, EndDatey Numbered.

  • NoEnd

    El NoEnd intervalo ocasiona que la recurrencia ocurra indefinidamente.

    Propiedad Pertinencia Descripción
    Type Obligatorio Tipo de intervalo de periodicidad. Debe establecerse en NoEnd.

  • EndDate

    El intervalo de EndDate hace que el período de tiempo se produzca en todos los días que se ajusten al patrón aplicable hasta la fecha de finalización.

    Propiedad Pertinencia Descripción
    Type Obligatorio Tipo de intervalo de periodicidad. Debe establecerse en EndDate.
    EndDate Obligatorio Fecha y hora para dejar de aplicar el patrón. Si la hora de inicio de la última ocurrencia cae antes de la fecha de finalización, la hora de finalización de esa ocurrencia puede extenderse más allá de ella.

    En el ejemplo siguiente, el período de tiempo se repite todos los días hasta la última aparición el 1 de abril de 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

    El Numbered rango hace que la ventana de tiempo se produzca un número especificado de veces.

    Propiedad Pertinencia Descripción
    Type Obligatorio Tipo de intervalo de periodicidad. Debe establecerse en Numbered.
    NumberOfOccurrences Obligatorio Número de ocurrencias.

    En el ejemplo siguiente, el período de tiempo se repite el lunes y el martes para un total de tres repeticiones, que se producen en las fechas siguientes:

    • Lunes, 1 de abril
    • Martes, 2 de abril
    • Lunes, 8 de abril
    "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
    }
}

Para crear una regla de periodicidad, debe especificar tanto las Pattern como las Range configuraciones. Cualquier tipo de patrón puede funcionar con cualquier tipo de intervalo.

Avanzado: El desplazamiento de zona horaria de la Start propiedad se aplica a la configuración de periodicidad.

Microsoft.Targeting

Este filtro proporciona la capacidad de habilitar una función para una audiencia de destino. Una explicación detallada de la segmentación se explica en la sección destino siguiente. Los parámetros de filtro incluyen un objeto Audience que describe usuarios, grupos, usuarios o grupos excluidos y un porcentaje predeterminado de la base de usuarios que debe tener acceso a la función. Cada objeto de grupo que aparece en la sección Groups también debe especificar el porcentaje de los miembros del grupo que deben tener acceso. Si se especifica un usuario en la sección Exclusion, ya sea directamente o si el usuario está en un grupo excluido, la función está deshabilitada. De lo contrario, si un usuario se especifica directamente en la sección de Users, o si el usuario está en el porcentaje incluido de cualquiera de los lanzamientos de grupo, o si el usuario entra en el porcentaje de lanzamiento predeterminado, ese usuario tendrá habilitada la función.

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

Destinatarios

El destino es una estrategia de administración de funciones que habilita a los desarrolladores implementar progresivamente nuevas funciones en su base de usuarios. La estrategia se basa en el concepto de dirigirse a un conjunto de usuarios conocidos como destino audiencia. Un público se compone de usuarios específicos, grupos, usuarios o grupos excluidos y un porcentaje designado de toda la base de usuarios. Los grupos que se incluyen en la audiencia se pueden dividir más en porcentajes de sus miembros totales.

En los pasos siguientes se muestra un ejemplo de una implementación progresiva para una nueva función "Beta":

  1. A los usuarios individuales, Jeff y Alicia se les concede acceso a la versión beta.
  2. Otro usuario, Mark, pide participar y está incluido.
  3. El veinte por ciento de un grupo conocido como "Ring1" se incluye en la versión Beta.
  4. El número de usuarios "Ring1" incluidos en la versión beta aumenta hasta el 100 %.
  5. El cinco por ciento de la base de usuarios se incluye en la versión beta.
  6. El porcentaje de lanzamiento se aumenta hasta el 100 % y la función se implementa por completo.

Esta estrategia para implementar una función está integrada en la biblioteca mediante el filtro de funciones Microsoft.Targeting incluido.

Definición de destinos de usuarios

Se puede indicar un usuario directamente en la llamada a is_enabled o se puede usar TargetingContext para especificar el usuario y el grupo opcional.

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

Exclusión de destino

Al definir una audiencia, los usuarios y grupos se pueden excluir de la audiencia. Las exclusiones son útiles cuando se está implementando una funciones para un grupo de usuarios, pero es necesario excluir del lanzamiento a algunos usuarios o grupos. La exclusión se define agregando una lista de usuarios y grupos a la propiedad Exclusion del público.

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

En el ejemplo anterior, la función está habilitada para los usuarios denominados Jeff y Alicia. También está habilitado para los usuarios del grupo denominado Ring0. Sin embargo, si el usuario se denomina Mark, la función está deshabilitada, independientemente de si están en el grupo Ring0 o no. Las exclusiones tienen prioridad sobre el resto del filtro de destino.

Variantes

Cuando se agregan nuevas funciones a una aplicación, puede haber un momento en el que una función tenga varias opciones de diseño propuestas diferentes. Como solución común para decidir sobre un diseño, se puede realiza un tipo de pruebas A/B. Con las pruebas A/B se da una versión diferente de la función a distintos segmentos de la base de usuarios y se elige una versión basada en la interacción del usuario. En esta biblioteca, esta funcionalidad se habilita mediante la representación de diferentes configuraciones de una función con variantes.

Las variantes permiten que una marca de función sea más que una marca de activación o desactivación simple. Una variante representa un valor de una marca de función que puede ser una cadena, un número, un valor booleano o incluso un objeto de configuración. Una marca de función que declara variantes debe definir en qué circunstancias se debe usar cada variante, que se trata con mayor detalle en la sección Asignación 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

Obtención de variantes

Para cada función, se puede recuperar una variante para FeatureManager mediante el método 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 devuelta depende del usuario que se está evaluando actualmente y esa información se obtiene de una instancia de TargetingContext.

Declaración de marca de función de variante

En comparación con los marcadores de funciones normales, los marcadores de funciones variantes tienen dos propiedades adicionales: variants y allocation. La propiedad variants es una matriz que contiene las variantes definidas para esta función. La propiedad allocation define cómo se deben asignar estas variantes para la función. Al igual que declarar marcadores de funciones normales, puede configurar marcadores de funciones de variantes en un archivo JSON. Este es un ejemplo de una marca de función variante.

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

Definición de variantes

Cada variante tiene dos propiedades: un nombre y una configuración. El nombre se usa para hacer referencia a una variante específica y la configuración es el valor de esa variante. La configuración se puede establecer mediante la propiedad configuration_value. configuration_value es una configuración insertada que puede ser una cadena, un número, un valor booleano o un objeto de configuración. Si no se especifica configuration_value, la propiedad Configuration de la variante devuelta es None.

Se define una lista de todas las variantes posibles para cada función en la propiedad variants.

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

Asignación de variantes

El proceso de asignación de variantes de una función viene determinado por la propiedad allocation de la función.

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

La configuración allocation de una función tiene las siguientes propiedades:

Propiedad Descripción
default_when_disabled Especifica qué variante se debe usar cuando se solicita una variante mientras la función se considera deshabilitada.
default_when_enabled Especifica qué variante se debe usar cuando se solicita una variante mientras la función se considera habilitada y no se asignó ninguna otra variante al usuario.
user Especifica una variante y una lista de usuarios a los que se debe asignar esa variante.
group Especifica una variante y una lista de grupos. La variante se asignará si el usuario está en al menos uno de los grupos.
percentile Especifica una variante y un intervalo de porcentajes en el que debe caber el porcentaje calculado del usuario para que se asigne esa variante.
seed Valor en el que se basan los cálculos porcentuales de percentile. El cálculo porcentual de un usuario específico será el mismo en todas las funciones si se usa el mismo valor seed. Si no se especifica ningún seed, se crea una inicialización predeterminada en función del nombre de la función.

Si la función no está habilitada, el administrador de funciones asigna la variante marcada como default_when_disabled al usuario actual, que en este caso es Small.

Si la función está habilitada, el administrador de funciones comprueba las asignaciones de user, group y percentile en ese orden para asignar una variante. En este ejemplo concreto, si el usuario que se evalúa se denomina Marsha, en el grupo denominado Ring1, o el usuario tiene lugar entre el percentil 0 y el 10, la variante especificada se asigna al usuario. En este caso, todos los usuarios asignados devolverían la variante Big. Si ninguna de estas asignaciones coincide, al usuario se le asigna la variante default_when_enabled, que es Small.

La lógica de asignación es similar a el filtro de funciones de Microsoft.Targeting, pero hay algunos parámetros presentes en el destino que no están en la asignación y viceversa. Los resultados de la selección de destino y la asignación no están relacionados.

Invalidar el estado habilitado con una variante

Puede usar variantes para invalidar el estado habilitado de una marca de función. La invalidación ofrece a las variantes la oportunidad de ampliar la evaluación de una marca de función. Al llamar a is_enabled en un marcador con variantes, el administrador de funciones comprobará si la variante asignada al usuario actual está configurada para invalidar el resultado. La invalidación se hace mediante la propiedad de variante opcional status_override. De forma predeterminada, esta propiedad se establece en None, lo que significa que la variante no afecta a si la marca se considera habilitada o deshabilitada. Establecer status_override en Enabled permite que la variante, cuando se elija, invalide una marca que se va a habilitar. Establecer status_override en Disabled proporciona la funcionalidad opuesta, por lo que deshabilitar la marca cuando se elige la variante. No se puede invalidar una función con un enabled estado false.

Si usa un marcador de funciones con variantes binarias, la propiedad status_override puede ser útil. Permite seguir usando API como is_enabled en la aplicación, al tiempo que se beneficia de las nuevas funciones que incluyen variantes, como la asignación de percentil y la inicialización.

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

En el ejemplo anterior, la función siempre está habilitada. Si el usuario actual está en el intervalo de percentil calculado de 10 a 20, se devuelve la variante On. De lo contrario, se devuelve la variante Off y, dado que status_override es igual a Disabled, la función ahora se considerará deshabilitada.

Telemetría

Cuando se implementa un cambio de marca de función, a menudo es importante analizar su efecto en una aplicación. Por ejemplo, estas son algunas preguntas que pueden surgir:

  • ¿Mis marcas están habilitadas o deshabilitadas según lo previsto?
  • ¿Los usuarios de destino obtienen acceso a una determinada función según lo previsto?
  • ¿Qué variante ve un usuario determinado?

Estos tipos de preguntas se pueden responder a través de la emisión y el análisis de eventos de evaluación de marcadores de funciones. Esta biblioteca habilita opcionalmente AzureMonitor para generar una telemetría de seguimiento durante la evaluación del marcador de funciones a través de OpenTelemetry.

Habilitación de telemetría

De forma predeterminada, las marcadores de funciones no tienen telemetría emitida. Para publicar la telemetría de un marcador de funciones determinado, el marcador DEBE declarar que está habilitada para emitir la telemetría.

En los marcadores de funciones definidos en json, la habilitación se realiza usando la propiedad telemetry.

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

El fragmento de código anterior define un marcador de funciones denominado MyFeatureFlag que está habilitado para la telemetría. Del objeto telemetry, la propiedad enabled tiene el valor true. El valor de la propiedad enabled debe ser true para publicar datos de telemetría para la marca.

La sección telemetry de una marca de función tiene las siguientes propiedades:

Propiedad Descripción
enabled Especifica si se debe publicar la telemetría para la marca de función.
metadata Colección de pares clave-valor, modelado como diccionario, que se pueden usar para adjuntar metadatos personalizados sobre la marca de función a eventos de evaluación.

Además, al crear FeatureManager, debe registrarse una devolución de llamada para controlar los eventos de telemetría. Esta devolución de llamada se invoca cada vez que se evalúa una marca de función y se habilita la telemetría para esa marca.

feature_manager = FeatureManager(feature_flags, on_feature_evaluated=publish_telemetry)

Telemetría de Application Insights

La biblioteca de administración de funciones habilita un editor de telemetría integrado que envía los datos de evaluación de los marcadores de funciones a Application Insights. Para habilitar Application Insights, la biblioteca de administración de funciones puede instalarse con Azure Monitor a través de pip install FeatureManagement[AzureMonitor]. Este comando instala el paquete azure-monitor-events-extension, que sirve para dar estilo a la telemetría en Application Insights por medio de OpenTelemetry.

Nota:

El paquete azure-monitor-events-extension solo añade la telemetría a la canalización de telemetría abierta. El registro de Application Insights sigue siendo necesario.

from azure.monitor.opentelemetry import configure_azure_monitor

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

Publicación de telemetría personalizada

Como la devolución de llamada de la telemetría es una función, se puede personalizar para publicar la telemetría en cualquier destino deseado. Por ejemplo, la telemetría podría publicarse en un servicio de registros, una base de datos o un servicio de telemetría personalizado.

Cuando se evalúa un marcador de funciones y se habilita la telemetría, el administrador de funciones llama a la devolución de llamada de telemetría con un parámetro EvaluationEvent. EvaluationEvent incluye las propiedades siguientes:

Etiqueta Descripción
feature Marcador de funciones usado.
user ID de usuario que se usa para la selección de destino.
enabled Si el marcador de funciones se evalúa como habilitado.
Variant Variante asignada.
VariantAssignmentReason Motivo por el que se asigna la variante.

Pasos siguientes

Para conocer detalles sobre cómo usar marcadores de funciones en las aplicaciones, consulte las siguientes guías de inicio rápido.

Python

Para obtener más información sobre cómo usar los filtros de funciones, vea los siguientes tutoriales.

Habilitación de funciones condicionales con filtros de funciones

Habilitación de funciones según una programación

Implementación de funciones en audiencias de destino

  • Last updated on