JavaScript-konfigurationsprovider

Azure App Configuration är en hanterad tjänst som hjälper utvecklare att centralisera sina programkonfigurationer enkelt och säkert. Med JavaScript-konfigurationsproviderbiblioteket kan du läsa in konfigurationen från ett Azure App Configuration Store på ett hanterat sätt. Det här klientbiblioteket lägger till ytterligare funktioner ovanför Azure SDK för JavaScript.

Läs in konfiguration

Metoden load som exporteras i @azure/app-configuration-provider paketet används för att läsa in konfigurationen från Azure App Configuration. Med load metoden kan du antingen använda Microsoft Entra-ID eller anslutningssträng för att ansluta till App Configuration Store.

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://free.blessedness.top/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();

const { load } = require("@azure/app-configuration-provider");
const connectionString = process.env.AZURE_APPCONFIG_CONNECTION_STRING;

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

run();

Metoden load returnerar en instans av AzureAppConfiguration typen som definieras på följande sätt:

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

Mer information om refresh och onRefresh metoder finns i avsnittet Konfigurationsuppdatering .

Använda konfiguration

Typen AzureAppConfiguration utökar följande gränssnitt:

• IGettable

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

  Gränssnittet IGettable tillhandahåller get en metod för att hämta värdet för ett nyckelvärde från den kartformaterade datastrukturen.

  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

  Typen AzureAppConfiguration utökar ReadonlyMap också gränssnittet, vilket ger skrivskyddad åtkomst till nyckel/värde-par.

• IConfigurationObject

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

  Gränssnittet IConfigurationObject tillhandahåller constructConfigurationObject en metod för att konstruera ett konfigurationsobjekt baserat på en mappad datastruktur och hierarkiska nycklar. Den valfria ConfigurationObjectConstructionOptions parametern kan användas för att ange avgränsaren för att konvertera hierarkiska nycklar till objektegenskaper. Som standard är "."avgränsaren .

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

  I JavaScript används objekt eller kartor ofta som de primära datastrukturerna för att representera konfigurationer. JavaScript-konfigurationsproviderbiblioteket stöder båda konfigurationsmetoderna, vilket ger utvecklare flexibilitet att välja det alternativ som bäst passar deras behov.

  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
  

Hantering av JSON-innehållstyp

Du kan skapa JSON-nyckelvärden i App Configuration. När du läser in nyckelvärden från Azure App Configuration konverterar konfigurationsprovidern automatiskt nyckelvärdena för giltig JSON-innehållstyp (t.ex. application/json) till objekt.

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

Nyckelvärdet ovan läses in som { size: 12, color: "red" }.

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

Läs in specifika nyckelvärden med hjälp av väljare

Som standard load läser metoden in alla konfigurationer utan etikett från konfigurationsarkivet. Du kan konfigurera metodens load beteende via den valfria parametern av AzureAppConfigurationOptions typen .

Om du vill förfina eller expandera de konfigurationer som läses in från App Configuration Store kan du ange nyckel- eller etikettväljarna under egenskapen 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"
        }
    ]
});

Filter för taggar

Parametern taggfilter väljer nyckelvärden med specifika taggar. Ett nyckelvärde läses bara in om alla taggar och motsvarande värden anges i filtren.

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

Trimma prefix från nycklar

Du kan trimma bort prefixet från nycklar genom att ange en lista över trimmade nyckelprefix för egenskapen AzureAppConfigurationOptions.trimKeyPrefixes .

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

Konfigurationsuppdatering

Med dynamisk uppdatering för konfigurationerna kan du hämta de senaste värdena från App Configuration Store utan att behöva starta om programmet. Du kan ställa in AzureAppConfigurationOptions.refreshOptions för att aktivera uppdaterings- och konfigurationsalternativen. Den inlästa konfigurationen uppdateras när alla ändringar av valda nyckelvärden identifieras på servern. Som standard används ett uppdateringsintervall på 30 sekunder, men du kan åsidosätta det med refreshIntervalInMs egenskapen .

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

Konfigurationen uppdateras inte automatiskt när du konfigurerar refreshOptions den. Du måste anropa metoden på refresh den AzureAppConfiguration instans som returneras av load metoden för att utlösa en uppdatering.

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

Den här designen förhindrar onödiga begäranden till App Configuration när programmet är inaktivt. Du bör inkludera anropet där programaktiviteten refresh inträffar. Detta kallas aktivitetsdriven konfigurationsuppdatering. Du kan till exempel anropa refresh när du bearbetar en inkommande begäran eller inuti en iteration där du utför en komplex uppgift.

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

Även om uppdateringsanropet misslyckas av någon anledning fortsätter programmet att använda den cachelagrade konfigurationen. Ett annat försök görs när det konfigurerade uppdateringsintervallet har passerat och uppdateringsanropet utlöses av programaktiviteten. Anrop refresh är en no-op innan det konfigurerade uppdateringsintervallet förflutit, så dess prestandapåverkan är minimal även om den anropas ofta.

Återanrop till anpassad uppdatering

Med onRefresh metoden kan du använda anpassade återanropsfunktioner som anropas varje gång den lokala konfigurationen uppdateras med ändringar från Azure App Configuration Store. Det returnerar ett disponibelt objekt som du kan använda för att ta bort det registrerade återanropet

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

Uppdatera sentinelnyckeln

En sentinel-nyckel är en nyckel som du uppdaterar när du har slutfört ändringen av alla andra nycklar. Konfigurationsprovidern övervakar sentinel-nyckeln i stället för alla valda nyckelvärden. När en ändring identifieras uppdaterar appen alla konfigurationsvärden.

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

Mer information om uppdateringskonfiguration finns i Använda dynamisk konfiguration i JavaScript.

Funktionsflagga

Du kan skapa funktionsflaggor i Azure App Configuration. Som standard läses inte funktionsflaggor in av konfigurationsprovidern. Du kan aktivera inläsning och uppdatering av funktionsflaggor via AzureAppConfigurationOptions.featureFlagOptions egenskapen när du load anropar metoden.

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

Funktionshantering

Med funktionshanteringsbiblioteket kan du utveckla och exponera programfunktioner baserat på funktionsflaggor. Funktionshanteringsbiblioteket är utformat för att fungera tillsammans med konfigurationsproviderbiblioteket. Konfigurationsprovidern läser in alla valda funktionsflaggor i konfigurationen feature_flags under listan i feature_management avsnittet. Funktionshanteringsbiblioteket använder och hanterar de inlästa funktionsflaggorna för ditt program.

I följande exempel visas hur du integrerar @microsoft/feature-management biblioteket med konfigurationsleverantören för att dynamiskt kontrollera API-tillgänglighet i en Express-applikation baserat på status för funktionsflaggan Beta.

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

Mer information om hur du använder JavaScript-funktionshanteringsbiblioteket finns i snabbstarten för funktionsflaggan.

Key Vault-referens

Azure App Configuration har stöd för att referera till hemligheter som lagras i Azure Key Vault. I App Configuration kan du skapa nycklar som mappar till hemligheter som lagras i Key Vault. Hemligheterna lagras säkert i Key Vault, men kan nås som alla andra konfigurationer när de har lästs in.

Konfigurationsproviderbiblioteket hämtar Key Vault-referenser, precis som för andra nycklar som lagras i App Configuration. Eftersom klienten identifierar nycklarna som Key Vault-referenser har de en unik innehållstyp och klienten ansluter till Key Vault för att hämta sina värden för ditt program. Du måste konfigurera AzureAppConfigurationOptions.KeyVaultOptions egenskapen med rätt autentiseringsuppgifter så att konfigurationsprovidern kan ansluta till Azure Key Vault.

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

Du kan också ange SecretClient instansen direkt till KeyVaultOptions. På så sätt kan du anpassa alternativen när du skapar 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 ]
    }
});

Du kan också ange secretResolver att egenskapen ska matcha hemligheter lokalt som inte har ett Key Vault associerat med dem.

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

Du kan också ange clientOptions egenskapen för att konfigurera SecretClientOptions som används för att ansluta till Azure Key Vault som inte har någon registrerad SecretClient.

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

Parallell hemlig lösning

Azure Key Vault tillhandahåller inte ett batch-API för att hämta flera hemligheter i en enda begäran. När programmet behöver läsa in flera Key Vault-referenser kan du förbättra prestandan genom att aktivera parallell hemlig lösning med hjälp av parallelSecretResolutionEnabled egenskapen i KeyVaultOptions. Detta gör att providern kan hämta flera hemligheter parallellt i stället för sekventiellt:

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

Hemlig uppdatering av Key Vault

Med Azure App Configuration kan du konfigurera hemliga uppdateringsintervall oberoende av konfigurationsuppdateringscykeln. Detta är viktigt för säkerheten eftersom även om Key Vault-referens-URI:n i App Configuration förblir oförändrad, kan den underliggande hemligheten i Key Vault roteras som en del av dina säkerhetsrutiner.

För att säkerställa att ditt program alltid använder de senaste hemliga värdena konfigurerar du secretRefreshIntervalInMs egenskapen i KeyVaultOptions. Detta tvingar providern att hämta nya hemliga värden från Key Vault när:

• Programmet anropar AzureAppConfiguration.refresh
• Det konfigurerade uppdateringsintervallet för hemligheten har förflutit

Den här mekanismen fungerar även när inga ändringar identifieras i appkonfigurationsarkivet, vilket säkerställer att programmet förblir synkroniserat med roterade hemligheter.

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

Ögonblicksbild

Ögonblicksbild är en namngiven, oföränderlig delmängd av ett appkonfigurationsarkivs nyckelvärden. De nyckelvärden som utgör en ögonblicksbild väljs under skapandetiden genom användning av nyckel- och etikettfilter. När en ögonblicksbild har skapats kommer nyckelvärdena inom garanterat att förbli oförändrade.

Du kan använda väljaren för ögonblicksbilder för att läsa in nyckelvärden eller funktionsflaggor från en ögonblicksbild:

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

Startförsök igen

Konfigurationsinläsning är en kritisk operation under programstarten. För att säkerställa tillförlitlighet implementerar Azure App Configuration-providern en robust återförsöksmekanism under den första konfigurationsbelastningen. Detta skyddar ditt program från tillfälliga nätverksproblem som annars kan förhindra lyckad start.

Du kan anpassa det här beteendet via AzureAppConfigurationOptions.startupOptions:

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

Geo-replikering

Information om hur du använder geo-replikering finns i Aktivera geo-replikering.

Nästa steg

Om du vill lära dig hur du använder JavaScript-konfigurationsprovidern fortsätter du till följande självstudie.

Om du vill lära dig hur du använder JavaScript-funktionshanteringsbiblioteket fortsätter du till följande dokumentation.