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.

Microsoft Entra ID

Du använder för att autentisera DefaultAzureCredential till appkonfigurationsarkivet. Följ anvisningarna för att tilldela dina autentiseringsuppgifter rollen App Configuration Data Reader.

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 settings = await load(endpoint, credential);
    console.log('settings.get("message"):', settings.get("message"));
}

run();

Anslutningssträng

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 settings = await load(connectionString);
    console.log('settings.get("message"):', settings.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 metoder finns i avsnittet KonfigurationsuppdateringonRefresh.

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 settings = await load(endpoint, credential);
  const fontSize = settings.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 settings = await load(endpoint, credential);
  const settingsObj = settings.constructConfigurationObject({separator: ":"});
  const fontSize1 = settings.get("app:font:size"); // map-style configuration representation
  const fontSize2 = settingsObj.app.font.size; // object-style configuration representation
  

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

Kommentar

Nyckelvärden läses in i den ordning som väljarna visas. Om flera väljare hämtar nyckelvärden med samma nyckel åsidosätter värdet från den förra något tidigare inläst värde.

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 settings = await load(endpoint, credential, {
    selectors: [{
        keyFilter: "app.*"
    }],
    trimKeyPrefixes: ["app."]
});

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 settings = 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.

const { SecretClient } = require("@azure/keyvault-secrets");

const credential = new DefaultAzureCredential();
const secretClient = new SecretClient(keyVaultUrl, credential, {
    serviceVersion: "7.0",
});
const settings = 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 settings = await load(endpoint, credential, {
    keyVaultOptions: {
        secretResolver: resolveSecret
    }
});

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 settings = 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å AzureAppConfiguration den refresh instans som returneras av load metoden för att utlösa en uppdatering.

// this call is not blocking, the configuration will be updated asynchronously
settings.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) => {
    settings.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 settings = await load(endpoint, credential, {
    refreshOptions: {
        enabled: true
    }
});
const disposer = settings.onRefresh(() => {
    console.log("Config refreshed.");
});

settings.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 på sentinel-nyckeln (äldre)

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 settings = 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 settings = await load(endpoint, credential, {
    featureFlagOptions: {
        enabled: true,
        selectors: [ { keyFilter: "*", labelFilter: "Prod" } ],
        refresh: {
            enabled: true, // the refresh for feature flags need to be enbaled in addition to key-values
            refreshIntervalInMs: 10_000
        }
    }
});

Kommentar

Om featureFlagOptions är aktiverat och ingen väljare har angetts läser konfigurationsprovidern in alla funktionsflaggor utan etikett från App Configuration Store.

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.

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

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.

Använda dynamisk konfiguration i JavaScript