Compartir a través de

Proveedor de configuración de JavaScript

configuration-provider-npm-package

Azure App Configuration es un servicio administrado que ayuda a los desarrolladores a centralizar la configuración de sus aplicaciones de forma sencilla y segura. La biblioteca del proveedor de configuración de JavaScript permite cargar la configuración desde un almacén de Azure App Configuration de forma administrada. Esta biblioteca cliente agrega funcionalidad adicional encima del SDK de Azure para JavaScript.

Carga de la configuración

El método load exportado en el paquete @azure/app-configuration-provider se usa para cargar la configuración desde Azure App Configuration. El método load permite usar Microsoft Entra ID o una cadena de conexión para conectarse al almacén de App Configuration.

Use DefaultAzureCredential para autenticarse en el almacén de App Configuration. Siga las instrucciones para asignar la credencial al rol Lector de datos de App Configuration.

const { load } = require("@azure/app-configuration-provider");
const { DefaultAzureCredential } = require("@azure/identity");
const endpoint = process.env.AZURE_APPCONFIG_ENDPOINT;
const credential = new DefaultAzureCredential(); // For more information, see https://learn.microsoft.com/azure/developer/javascript/sdk/credential-chains#use-defaultazurecredential-for-flexibility

async function run() {
    // Connect to Azure App Configuration using a token credential and load all key-values with no label.
    const appConfig = await load(endpoint, credential);
    console.log('appConfig.get("message"):', appConfig.get("message"));
}

run();

El método load devuelve una instancia del tipo AzureAppConfiguration que se define de la siguiente manera:

type AzureAppConfiguration = {
    refresh(): Promise<void>;
    onRefresh(listener: () => any, thisArg?: any): Disposable;
} & IGettable & ReadonlyMap<string, any> & IConfigurationObject;

Para más información sobre los métodos refresh y onRefresh, vea la sección Actualización de la configuración.

Consumo de la configuración

El tipo AzureAppConfiguration extiende las interfaces siguientes:

  • IGettable

    interface IGettable {
    get<T>(key: string): T | undefined;
}

    La interfaz IGettable proporciona el método get para recuperar el valor de un par clave-valor de la estructura de datos con estilo Map.

    const appConfig = await load(endpoint, credential);
const fontSize = appConfig.get("app:font:size"); // value of the key "app:font:size" from the App Configuration store

  • ReadonlyMap

    El tipo AzureAppConfiguration también amplía la interfaz ReadonlyMap, lo que proporciona acceso de solo lectura a pares clave-valor.

  • IConfigurationObject

    interface IConfigurationObject {
    constructConfigurationObject(options?: ConfigurationObjectConstructionOptions): Record<string, any>;
}

    La interfaz IConfigurationObject proporciona el método constructConfigurationObject para crear un objeto de configuración basado en una estructura de datos de estilo Map y claves jerárquicas. El parámetro opcional ConfigurationObjectConstructionOptions se puede usar para especificar el separador para convertir claves jerárquicas en propiedades de objeto. De manera predeterminada, el separador es ".".

    interface ConfigurationObjectConstructionOptions {
    separator?: "." | "," | ";" | "-" | "_" | "__" | "/" | ":"; // supported separators
}

    En JavaScript, los objetos o asignaciones se suelen usar como estructuras de datos principales para representar configuraciones. La biblioteca de proveedores de configuración de JavaScript admite los dos enfoques de configuración, lo que proporciona a los desarrolladores la flexibilidad de elegir la opción que mejor se adapte a sus necesidades.

    const appConfig = await load(endpoint, credential);
const settingsObj = appConfig.constructConfigurationObject({separator: ":"});
const fontSize1 = appConfig.get("app:font:size"); // map-style configuration representation
const fontSize2 = settingsObj.app.font.size; // object-style configuration representation

Control de tipos de contenido JSON

Puede crear valores de clave JSON en App Configuration. Al cargar valores clave desde Azure App Configuration, el proveedor de configuración convertirá automáticamente los valores clave del tipo de contenido JSON válido (por ejemplo, application/json) en un objeto.

{
    "key": "font",
    "label": null,
    "value": "{\r\n\t\"size\": 12,\r\n\t\"color\": \"red\"\r\n}",
    "content_type": "application/json"
}

El valor de clave anterior se cargará como { size: 12, color: "red" }.

const appConfig = await load(endpoint, credential);
const { size, color } = appConfig.get("font");

Carga de pares clave-valor específicos mediante selectores

De manera predeterminada, el método load cargará todas las configuraciones sin etiqueta desde el almacén de configuración. Puede configurar el comportamiento del método load mediante el parámetro opcional de tipo AzureAppConfigurationOptions.

Para refinar o expandir las configuraciones cargadas desde el almacén de App Configuration, puede especificar los selectores de clave o etiqueta en la propiedad AzureAppConfigurationOptions.selectors.

const appConfig = await load(endpoint, credential, {
    selectors: [
        { // load the subset of keys starting with "app1." prefix and "test" label
            keyFilter: "app1.*",
            labelFilter: "test"
        },
        { // load the subset of keys starting with "dev" label"
            labelFilter: "dev*"
        }
    ]
});

Nota:

Los pares de clave-valor se cargan en el orden en que aparecen los selectores. Si varios selectores recuperan los pares de clave-valor con la misma clave, el valor del último invalidará cualquier valor cargado antes.

Recorte del prefijo de las claves

Puede recortar el prefijo de las claves si proporciona una lista de prefijos de clave recortados a la propiedad AzureAppConfigurationOptions.trimKeyPrefixes.

const appConfig = await load(endpoint, credential, {
    selectors: [{
        keyFilter: "app.*"
    }],
    trimKeyPrefixes: ["app."]
});

Actualización de configuración

La actualización dinámica de las configuraciones le permite extraer sus valores más recientes del almacén de App Configuration sin tener que reiniciar la aplicación. Puede establecer AzureAppConfigurationOptions.refreshOptions para habilitar las opciones de actualización y configurar la actualización. La configuración cargada se actualizará cuando se detecte un cambio de los pares de clave-valor seleccionados en el servidor. De forma predeterminada, se usa un intervalo de actualización de 30 segundos, pero puede invalidarlo con la propiedad refreshIntervalInMs.

const appConfig = await load(endpoint, credential, {
    refreshOptions: {
        enabled: true,
        refreshIntervalInMs: 15_000
    }
});

La configuración de refreshOptions por sí sola no actualizará automáticamente la configuración. Debe llamar al método refresh en la instancia de AzureAppConfiguration devuelta por el método load para desencadenar una actualización.

// this call is not blocking, the configuration will be updated asynchronously
appConfig.refresh();

Este diseño evita solicitudes innecesarias a App Configuration cuando la aplicación está inactiva. Debe incluir la llamada refresh en la que se produce la actividad de la aplicación. Esto se conoce como actualización de configuración controlada por actividad. Por ejemplo, puede llamar a refresh al procesar una solicitud entrante o dentro de una iteración en la que se realiza una tarea compleja.

const server = express();
// Use an express middleware to refresh configuration whenever a request comes in
server.use((req, res, next) => {
    appConfig.refresh();
    next();
})

Incluso si se produce un error en la llamada de la actualización por cualquier motivo, la aplicación seguirá usando la configuración almacenada en caché. Se realizará otro intento cuando se haya superado el intervalo de actualización configurado y la actividad de la aplicación desencadene la llamada a la actualización. Llamar a refresh es una operación no operativa antes de que transcurre el intervalo de actualización configurado, por lo que su impacto en el rendimiento es mínimo incluso si se llama con frecuencia.

Devolución de llamada de actualización personalizada

El método onRefresh permite realizar funciones de devolución de llamada personalizadas que se invocarán cada vez que la configuración local se actualice correctamente con los cambios del almacén de Azure App Configuration. Devuelve un objeto Disposable, que se puede usar para quitar la devolución de llamada registrada

const appConfig = await load(endpoint, credential, {
    refreshOptions: {
        enabled: true
    }
});
const disposer = appConfig.onRefresh(() => {
    console.log("Config refreshed.");
});

appConfig.refresh();
// Once the refresh is successful, the callback function you registered will be executed.
// In this example, the message "Config refreshed" will be printed.

disposer.dispose();

Actualización en la clave sentinel

Una clave de Sentinel es una clave que se actualiza después de completar el cambio de todas las demás claves. El proveedor de configuración supervisará la clave de Sentinel en lugar de todos los pares de clave-valor seleccionados. Cuando se detecta un cambio, la aplicación actualiza todos los valores de configuración.

const appConfig = await load(endpoint, credential, {
    refreshOptions: {
        enabled: true,
        watchedSettings: [
            { key: "sentinel" }
        ]
    }
});

Para más información sobre la configuración de actualización, vaya a Uso de la configuración dinámica en JavaScript.

Marca de características

Puede crear marcas de características en Azure App Configuration. De manera predeterminada, el proveedor de configuración no cargará las marcas de características. Puede habilitar la carga y actualización de marcas de características mediante la propiedad AzureAppConfigurationOptions.featureFlagOptions al llamar al método load.

const appConfig = await load(endpoint, credential, {
    featureFlagOptions: {
        enabled: true, // enable loading feature flags
        selectors: [ { keyFilter: "*", labelFilter: "Prod" } ],
        refresh: {
            enabled: true, // enable refreshing feature flags
            refreshIntervalInMs: 60_000
        }
    }
});

Nota:

Si se habilita featureFlagOptions y no se especifica ningún selector, el proveedor de configuración cargará todas las marcas de características sin etiqueta desde el almacén de App Configuration.

Importante

Para consumir y administrar de forma eficaz las marcas de características cargadas desde Azure App Configuration, instale y use el paquete @microsoft/feature-management. Esta biblioteca proporciona una manera estructurada de controlar el comportamiento de las características en la aplicación.

Administración de características

La biblioteca de administración de características proporciona una manera de desarrollar y exponer la funcionalidad de la aplicación en función de las marcas de características. La biblioteca de administración de características está diseñada para funcionar junto con la biblioteca de proveedores de configuración. El proveedor de configuración cargará todas las marcas de características seleccionadas en la configuración de la lista feature_flags de la sección feature_management. La biblioteca de administración de características consumirá y administrará las marcas de características cargadas para la aplicación.

En el ejemplo siguiente se muestra cómo integrar la @microsoft/feature-management biblioteca con el proveedor de configuración para controlar dinámicamente la accesibilidad de la API en una aplicación Express en función del estado de la Beta marca de característica.

// Load feature flags from Azure App Configuration
import { load } from "@azure/app-configuration-provider";
const appConfig = await load(endpoint, credential, {
    featureFlagOptions: {
        enabled: true, // enable loading feature flags
        refresh: {
            enabled: true // enable refreshing feature flags
        }
    }
});

import { ConfigurationMapFeatureFlagProvider, FeatureManager } from "@microsoft/feature-management";
// Create a feature flag provider which uses the configuration provider as feature flag source
const ffProvider = new ConfigurationMapFeatureFlagProvider(appConfig);
// Create a feature manager which will evaluate the feature flag
const fm = new FeatureManager(ffProvider);

import express from "express";
const server = express();

// Use a middleware to achieve request-driven configuration refresh
server.use((req, res, next) => {
    // this call is not blocking, the configuration will be updated asynchronously
    appConfig.refresh();
    next();
});

server.get("/Beta", async (req, res) => {
    if (await featureManager.isEnabled("Beta")) {
        res.send("Welcome to the Beta page!");
    } else {
        res.status(404).send("Page not found");
    }
});

Para más información sobre cómo usar la biblioteca de administración de características de JavaScript, vaya al inicio rápido de características.

Referencia de Key Vault

Azure App Configuration admite la referencia a secretos almacenados en Azure Key Vault. En App Configuration, puede crear claves que se asignen a secretos almacenados en Key Vault. Los secretos se almacenan de forma segura en Key Vault, pero se puede acceder a ellos como cualquier otra configuración una vez que se carguen.

La biblioteca de proveedores de configuración recupera las referencias de Key Vault, como hace para cualquier otra clave almacenada en App Configuration. Como el cliente reconoce las claves como referencias de Key Vault, tienen un tipo de contenido único y el cliente se conectará a Key Vault a fin de recuperar sus valores para la aplicación. Debe configurar la propiedad AzureAppConfigurationOptions.KeyVaultOptions con la credencial adecuada para permitir que el proveedor de configuración se conecte a Azure Key Vault.

const credential = new DefaultAzureCredential();
const appConfig = await load(endpoint, credential, {
    keyVaultOptions: {
        credential: credential
    }
});

También puede proporcionar la instancia de SecretClient directamente a KeyVaultOptions. De este modo, puede personalizar las opciones al crear SecretClient.

import { SecretClient } from "@azure/keyvault-secrets";

const credential = new DefaultAzureCredential();
const secretClient = new SecretClient(keyVaultUrl, credential, {
    serviceVersion: "7.0",
});
const appConfig = await load(endpoint, credential, {
    keyVaultOptions: {
        secretClients: [ secretClient ]
    }
});

También puede establecer la propiedad secretResolver para resolver localmente los secretos que no tienen un almacén de claves asociado.

const resolveSecret = (url) => "From Secret Resolver";
const appConfig = await load(endpoint, credential, {
    keyVaultOptions: {
        secretResolver: resolveSecret
    }
});

También puede establecer clientOptions la propiedad para configurar SecretClientOptions que se usa para conectarse a Azure Key Vault que no tenga registrado SecretClient.

const credential = new DefaultAzureCredential();
const appConfig = await load(endpoint, credential, {
    keyVaultOptions: {
        credential: credential,
        clientOptions: { // configure a custom SecretClientOptions
            retryOptions: { 
                maxRetries: 3, 
                maxRetryDelayInMs: 1000 
            }
        }
    }
});

Resolución de secretos en paralelo

Azure Key Vault no proporciona una API por lotes para recuperar varios secretos en una sola solicitud. Cuando la aplicación necesita cargar numerosas referencias de Key Vault, puede mejorar el rendimiento habilitando la resolución de secretos en paralelo mediante la parallelSecretResolutionEnabled propiedad en KeyVaultOptions. Esto permite al proveedor capturar varios secretos en paralelo en lugar de secuencialmente:

const credential = new DefaultAzureCredential();
const appConfig = await load(endpoint, credential, {
    keyVaultOptions: {
        credential: credential,
        parallelSecretResolutionEnabled: true
    }
});

Nota:

Al resolver el secreto en paralelo, es posible que encuentre el límite de servicio de Azure Key Vault. Para controlar la limitación de forma eficaz, implemente los procedimientos recomendados de limitación del lado cliente mediante la configuración de las opciones de reintento adecuadas para SecretClient. Puede registrar instancias personalizadas SecretClient o configurar clientOptions a través de AzureAppConfigurationOptions.keyVaultOptions.

Instantánea

Una Instantánea es un subconjunto con nombre inmutable de los pares clave-valor de un almacén de App Configuration. Los valores clave que componen una instantánea se eligen durante el tiempo de creación mediante el uso de filtros de clave y etiqueta. Una vez creada una instantánea, se garantiza que los valores clave que contiene permanecen inalterados.

Puede usar el selector de instantáneas para cargar los valores de clave o las marcas de características desde una instantánea:

const appConfig = await load(endpoint, credential, {
    selectors: [
        { snapshotName: "MySnapshot" }, // load key-values from snapshot
        { keyFilter: "test*", labelFilter: "test" }
    ],
    featureFlagOptions: {
        enabled: true,
        selectors: [
            { snapshotName: "MySnapshot" }, // load feature flags from snapshot
            { keyFilter: "*", labelFilter: "test" }
        ]
    }
});

Reintento de reinicio

La carga de configuración es un proceso crítico durante el inicio de la aplicación. Para garantizar la confiabilidad, el proveedor de Azure App Configuration implementa un mecanismo de reintento sólido durante la carga de configuración inicial. Esto ayuda a proteger la aplicación frente a problemas de red transitorios que podrían impedir el inicio correcto.

Puede personalizar este comportamiento a través de AzureAppConfigurationOptions.startupOptions:

const appConfig = await load(endpoint, credential, { 
    startupOptions: { 
        timeoutInMs: 300_000
    }
});

Replicación geográfica

Para obtener información sobre el uso de la replicación geográfica, vaya a Habilitación de la replicación geográfica.

Pasos siguientes

Para obtener información sobre cómo usar el proveedor de configuración de JavaScript, continúe con el siguiente tutorial.

Uso de la configuración dinámica en JavaScript

Para obtener información sobre cómo usar la biblioteca de administración de características de JavaScript, continúe con la siguiente documentación.

Administración de características de JavaScript