Partager via

Fournisseur de configuration JavaScript

configuration-provider-npm-package

Azure App Configuration est un service managé qui permet aux développeurs de centraliser leurs configurations d’application de façon simple et sécurisée. La bibliothèque du fournisseur de configuration JavaScript permet de charger la configuration à partir d’un magasin Azure App Configuration de manière managée. Cette bibliothèque cliente ajoute des fonctionnalités supplémentaires au-dessus du Kit de développement logiciel (SDK) Azure pour JavaScript.

Charger la configuration

La méthode load exportée dans le package @azure/app-configuration-provider est utilisée pour charger la configuration à partir d’Azure App Configuration. La méthode load vous permet d’utiliser Microsoft Entra ID ou la chaîne de connexion pour vous connecter au magasin App Configuration.

Vous utilisez le DefaultAzureCredential pour vous authentifier auprès de votre magasin App Configuration. Suivez les instructions pour attribuer vos informations d’identification au rôle Lecteur de données 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();

La méthode load retourne une instance de type AzureAppConfiguration qui est définie comme suit :

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

Pour plus d’informations sur les méthodes refresh et onRefresh , consultez la section Actualisation de la configuration.

Utiliser la configuration

Le type AzureAppConfiguration étend les interfaces suivantes :

  • IGettable

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

    L’interface IGettable fournit une méthode get pour récupérer la valeur d’une paire clé-valeur depuis la structure de données de type 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

    Le type AzureAppConfiguration étend également l’interface ReadonlyMap, qui fournit un accès en lecture seule aux paires clé-valeur.

  • IConfigurationObject

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

    L’interface IConfigurationObject fournit une méthode constructConfigurationObject pour construire un objet de configuration basé sur une structure de données de type Map et des clés hiérarchiques. Le paramètre facultatif ConfigurationObjectConstructionOptions peut être utilisé pour spécifier le séparateur permettant de convertir des clés hiérarchiques en propriétés d’objet. Par défaut, le séparateur est ".".

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

    Dans JavaScript, les objets ou les mappages sont couramment utilisés comme structures de données principales pour représenter des configurations. La bibliothèque de fournisseurs de configuration JavaScript prend en charge les deux approches de configuration, ce qui permet aux développeurs de choisir l’option qui convient le mieux à leurs besoins.

    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

Gestion des types de contenu JSON

Vous pouvez créer des valeurs de clé JSON dans App Configuration. Lors du chargement de clés à partir d’Azure App Configuration, le fournisseur de configuration convertit automatiquement les valeurs clés du type de contenu JSON valide (par exemple, application/json) en objet.

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

La clé-valeur ci-dessus sera chargée sous la forme de { size: 12, color: "red" }.

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

Remarque

À compter de la version 2.2.0 de @azure/app-configuration-provider, le fournisseur de configuration autorise les commentaires, tels que définis dans (JSONC), dans les clés-valeurs avec un type de contenu application/json.

Charger des valeurs de clé spécifiques à l’aide de sélecteurs

Par défaut, la méthode load charge toutes les configurations sans étiquette à partir du magasin de configuration. Vous pouvez configurer le comportement de la méthode load par le biais du paramètre facultatif de type AzureAppConfigurationOptions.

Pour affiner ou développer les configurations chargées à partir du magasin App Configuration, vous pouvez spécifier les sélecteurs de clé ou d’étiquette sous la propriété 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 with "dev" label"
            keyFilter: "*",
            labelFilter: "dev"
        }
    ]
});

Remarque

Les paires clé-valeur sont chargées dans l’ordre dans lequel les sélecteurs sont répertoriés. Si plusieurs sélecteurs récupèrent des paires clé-valeur ayant la même clé, la valeur provenant du dernier sélecteur remplacera toute valeur chargée auparavant.

Filtres d’étiquettes

Le paramètre de filtre d’étiquettes sélectionne les valeurs clés avec des balises spécifiques. Une clé-valeur est chargée uniquement si toutes les balises et les valeurs correspondantes sont spécifiées dans les filtres.

const appConfig = await load(endpoint, credential, {
    selectors: [
        { // load the subset of keys with "test" label" and three tags
            keyFilter: "*",
            labelFilter: "test",
            tagFilters: [
                "emptyTag=",
                "nullTag=\0",
                "tag1=value1"
            ]
        }
    ]
});

Remarque

Les caractères astérisque (*), virgule (,) et barre oblique inverse (\) sont réservés et doivent être échappés avec une barre oblique inverse lorsqu'ils sont utilisés dans un filtre d'étiquette.

Supprimer le préfixe des clés

Vous pouvez supprimer le préfixe des clés en fournissant une liste de préfixes de clés à la propriété AzureAppConfigurationOptions.trimKeyPrefixes.

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

Actualisation de la configuration

L’actualisation dynamique des configurations vous permet d’extraire leurs dernières valeurs du magasin App Configuration sans avoir à redémarrer l’application. Vous pouvez définir AzureAppConfigurationOptions.refreshOptions pour activer l’actualisation et configurer les options d’actualisation. La configuration chargée sera mise à jour dès qu’un changement des paires clé-valeur sélectionnées est détecté sur le serveur. Par défaut, un intervalle d'actualisation de 30 secondes est utilisé, mais vous pouvez le remplacer avec la propriété refreshIntervalInMs.

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

La configuration seule refreshOptions n’actualisera pas automatiquement la configuration. Vous devez appeler la méthode refresh sur l’instance AzureAppConfiguration retournée par la méthode load pour déclencher une actualisation.

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

Cette conception empêche les demandes inutiles adressées à App Configuration lorsque votre application est inactive. Vous devez inclure l’appel refresh où se produit votre activité d’application. C'est ce qu'on appelle l'actualisation de la configuration basée sur l'activité. Par exemple, vous pouvez appeler refresh lors du traitement d’une requête entrante ou à l’intérieur d’une itération où vous effectuez une tâche complexe.

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

Même si l’appel d’actualisation échoue pour une raison quelconque, votre application continue d’utiliser la configuration mise en cache. Une autre tentative est effectuée lorsque l’intervalle d’actualisation configuré est passé et que l’appel d’actualisation est déclenché par l’activité de votre application. L’appel de refresh est une opération sans opération avant l’expiration de l’intervalle d’actualisation configuré, de sorte que son impact sur les performances est minimal même s’il est appelé fréquemment.

Rappel d’actualisation personnalisé

La méthode onRefresh vous permet de définir des fonctions de rappel personnalisées (callbacks) qui seront invoquées chaque fois que la configuration locale est mise à jour avec succès à partir des modifications du magasin Azure App Configuration. Cela renvoie un objet Disposable, que vous pouvez utiliser pour supprimer le callback enregistré

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();

Actualiser sur la clé sentinelle

Une clé Sentinel est une clé que vous mettez à jour après avoir modifié toutes les autres clés. Le fournisseur de configuration surveillera la clé sentinelle au lieu de toutes les paires clé-valeur sélectionnées. Lorsqu’un changement est détecté, votre application actualise toutes les valeurs de configuration.

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

Pour plus d’informations sur la configuration de l’actualisation, accédez à Utiliser la configuration dynamique dans JavaScript.

Indicateur de fonctionnalité

Vous pouvez créer des indicateurs de fonctionnalité dans Azure App Configuration. Par défaut, les indicateurs de fonctionnalité ne seront pas chargés par le fournisseur de configuration. Vous pouvez activer le chargement et l’actualisation des indicateurs de fonctionnalité via la propriété AzureAppConfigurationOptions.featureFlagOptions lors de l’appel de la méthode 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
        }
    }
});

Remarque

Si featureFlagOptions est activé et qu’aucun sélecteur n’est spécifié, le fournisseur de configuration charge tous les indicateurs de fonctionnalité sans étiquette dans le magasin App Configuration.

Important

Pour consommer et gérer efficacement les indicateurs de fonctionnalité chargés à partir d’Azure App Configuration, installez et utilisez le @microsoft/feature-management package. Cette bibliothèque offre un moyen structuré de contrôler le comportement des fonctionnalités dans votre application.

Gestion des fonctionnalités

La bibliothèque de gestion des fonctionnalités permet de développer et d’exposer les fonctionnalités d’application en fonction des indicateurs de fonctionnalité. La bibliothèque de gestion des fonctionnalités est conçue pour fonctionner conjointement avec la bibliothèque du fournisseur de configuration. Le fournisseur de configuration charge tous les indicateurs de fonctionnalités sélectionnés dans la configuration sous la liste feature_flags de la section feature_management. La bibliothèque de gestion des fonctionnalités consomme et gère les indicateurs de fonctionnalité chargés pour votre application.

L’exemple suivant montre comment intégrer la @microsoft/feature-management bibliothèque au fournisseur de configuration pour contrôler dynamiquement l’accessibilité des API dans une application Express en fonction de l’état de l’indicateur Beta de fonctionnalité.

// 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");
    }
});

Pour plus d’informations sur l’utilisation de la bibliothèque de gestion des fonctionnalités JavaScript, consultez le guide de démarrage rapide sur les indicateurs de fonctionnalités.

Référence Key Vault

Azure App Configuration prend en charge le référencement des secrets stockés dans Azure Key Vault. Dans App Configuration, vous pouvez créer des clés qui associent des secrets stockés dans Key Vault. Les secrets sont stockés en toute sécurité dans Key Vault, mais sont accessibles comme toute autre configuration une fois chargés.

La bibliothèque du fournisseur de configuration récupère les références Key Vault, tout comme pour les autres clés stockées dans App Configuration. Étant donné que le client reconnaît les clés comme des références Key Vault, elles possèdent un type de contenu unique, et le client se connectera à Key Vault pour récupérer leurs valeurs pour votre application. Vous devez configurer la propriété AzureAppConfigurationOptions.KeyVaultOptions avec les informations d’identification appropriées pour permettre au fournisseur de configuration de se connecter à Azure Key Vault.

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

Vous pouvez également fournir l’instance SecretClient directement à KeyVaultOptions. De cette façon, vous pouvez personnaliser les options lors de la création de 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 ]
    }
});

Vous pouvez également définir la propriété secretResolver pour résoudre localement les secrets qui n’ont pas de coffre de clés qui leur sont associés.

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

Vous pouvez également définir la propriété clientOptions pour configurer SecretClientOptions utilisée pour vous connecter à Azure Key Vault qui n’a pas d’inscription SecretClient.

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

Résolution du secret parallèle

Azure Key Vault ne fournit pas d’API batch pour récupérer plusieurs secrets dans une seule requête. Lorsque votre application doit charger de nombreuses références Key Vault, vous pouvez améliorer les performances en activant la résolution de secret parallèle à l’aide de la parallelSecretResolutionEnabled propriété dans KeyVaultOptions. Cela permet au fournisseur d’extraire plusieurs secrets en parallèle plutôt que séquentiellement :

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

Remarque

Lors de la résolution du secret en parallèle, vous pouvez rencontrer la limite de service d’Azure Key Vault. Pour gérer efficacement la limitation, implémentez les meilleures pratiques de limitation côté client en configurant les options de nouvelle tentative appropriées pour le SecretClient. Vous pouvez inscrire des instances personnalisées SecretClient ou configurer clientOptions via le AzureAppConfigurationOptions.keyVaultOptions.

Actualisation du secret dans Key Vault

Azure App Configuration vous permet de configurer les intervalles d’actualisation des secrets indépendamment de votre cycle d’actualisation de configuration. Cela est essentiel pour la sécurité, car bien que l’URI de référence Key Vault dans App Configuration reste inchangé, le secret sous-jacent dans Key Vault peut être pivoté dans le cadre de vos pratiques de sécurité.

Pour vous assurer que votre application utilise toujours les valeurs secrètes les plus actuelles, configurez la secretRefreshIntervalInMs propriété dans KeyVaultOptions. Cela force le fournisseur à récupérer de nouvelles valeurs secrètes à partir de Key Vault quand :

  • Appels de votre application AzureAppConfiguration.refresh
  • L’intervalle d’actualisation configuré pour le secret s’est écoulé

Ce mécanisme fonctionne même quand aucune modification n’est détectée dans votre magasin App Configuration, ce qui garantit que votre application reste synchronisée avec les secrets pivotés.

const credential = new DefaultAzureCredential();
const appConfig = await load(endpoint, credential, {
    keyVaultOptions: {
        credential: credential,
        secretRefreshIntervalInMs: 7200_000 // 2 hours
    }
});

Instantané

Un instantané est un sous-ensemble nommé et immuable des valeurs clés d’un magasin de App Configuration. Les valeurs clés qui composent un instantané sont choisies au moment de la création via l’utilisation de filtres de clé et d’étiquette. Une fois qu’un instantané est créé, ses valeurs clés sont assurées de rester inchangées.

Vous pouvez utiliser le sélecteur d’instantanés pour charger des indicateurs de clés ou de fonctionnalités à partir d’un instantané :

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

Nouvelle tentative de démarrage

Le chargement de la configuration est une opération de chemin critique au démarrage de l’application. Pour garantir la fiabilité, le fournisseur Azure App Configuration implémente un mécanisme de nouvelle tentative robuste pendant la charge de configuration initiale. Cela permet de protéger votre application contre les problèmes réseau temporaires susceptibles d’empêcher le démarrage réussi.

Vous pouvez personnaliser ce comportement via les AzureAppConfigurationOptions.startupOptionspoints suivants :

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

Géoréplication

Pour plus d’informations sur l’utilisation de la géoréplication, accédez à Activer la géoréplication.

Étapes suivantes

Pour savoir comment utiliser le fournisseur de configuration JavaScript, passez au tutoriel suivant.

Utiliser la configuration dynamique dans JavaScript

Pour savoir comment utiliser la bibliothèque de gestion des fonctionnalités JavaScript, passez à la documentation suivante.

Gestion des fonctionnalités JavaScript

  • Last updated on