JavaScript-configuratieprovider

Azure App Configuration is een beheerde service waarmee ontwikkelaars hun toepassingsconfiguraties eenvoudig en veilig kunnen centraliseren. Met de JavaScript-configuratieproviderbibliotheek kunt u configuratie laden vanuit een Azure-app Configuratiearchief op een beheerde manier. Deze clientbibliotheek voegt extra functionaliteit toe boven de Azure SDK voor JavaScript.

Configuratie laden

De load methode die in het @azure/app-configuration-provider pakket wordt geëxporteerd, wordt gebruikt om de configuratie uit de Azure-app-configuratie te laden. Met de load methode kunt u Microsoft Entra ID of verbindingsreeks gebruiken om verbinding te maken met het App Configuration-archief.

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

De load methode retourneert een exemplaar van het AzureAppConfiguration type dat als volgt is gedefinieerd:

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

Zie de sectie refresh voor meer informatie over onRefresh en methoden.

Configuratie gebruiken

Het AzureAppConfiguration type breidt de volgende interfaces uit:

• IGettable

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

  De IGettable interface biedt get een methode voor het ophalen van de waarde van een sleutelwaarde uit de gegevensstructuur in kaartstijl.

  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

  Het AzureAppConfiguration type breidt ook de ReadonlyMap interface uit en biedt alleen-lezentoegang tot sleutel-waardeparen.

• IConfigurationObject

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

  De IConfigurationObject interface biedt constructConfigurationObject een methode voor het maken van een configuratieobject op basis van een gegevensstructuur in kaartstijl en hiërarchische sleutels. De optionele ConfigurationObjectConstructionOptions parameter kan worden gebruikt om het scheidingsteken op te geven voor het converteren van hiërarchische sleutels naar objecteigenschappen. Standaard is "."het scheidingsteken .

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

  In JavaScript worden objecten of kaarten vaak gebruikt als de primaire gegevensstructuren om configuraties weer te geven. De Bibliotheek van de JavaScript-configuratieprovider ondersteunt beide configuratiemethoden, zodat ontwikkelaars de flexibiliteit hebben om de optie te kiezen die het beste bij hun behoeften past.

  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
  

Verwerking van JSON-inhoudstypen

U kunt JSON-sleutelwaarden maken in App Configuration. Bij het laden van sleutelwaarden uit Azure App Configuration converteert de configuratieprovider automatisch de sleutelwaarden van het geldige JSON-inhoudstype (bijvoorbeeld application/json) naar het object.

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

De bovenstaande sleutelwaarde wordt geladen als { size: 12, color: "red" }.

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

Specifieke sleutelwaarden laden met behulp van selectors

De methode laadt standaard load alle configuraties zonder label uit het configuratiearchief. U kunt het gedrag van de load methode configureren via de optionele parameter van het AzureAppConfigurationOptions type.

Als u de configuraties wilt verfijnen of uitvouwen die zijn geladen vanuit het App Configuration-archief, kunt u de sleutel- of labelkiezers onder de AzureAppConfigurationOptions.selectors eigenschap opgeven.

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

Tagfilters

De parameter tagfilters selecteert sleutelwaarden met specifieke tags. Een sleutelwaarde wordt alleen geladen als deze alle tags en bijbehorende waarden bevat die zijn opgegeven in de filters.

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

Voorvoegsel bijsnijden van sleutels

U kunt het voorvoegsel van sleutels knippen door een lijst met bijgesneden sleutelvoorvoegsels op te geven voor de AzureAppConfigurationOptions.trimKeyPrefixes eigenschap.

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

Configuratie vernieuwen

Met dynamische vernieuwing voor de configuraties kunt u de meest recente waarden ophalen uit het App Configuration-archief zonder dat u de toepassing opnieuw hoeft op te starten. U kunt instellen AzureAppConfigurationOptions.refreshOptions dat de opties voor vernieuwen en vernieuwen worden ingeschakeld. De geladen configuratie wordt bijgewerkt wanneer een wijziging van geselecteerde sleutelwaarden op de server wordt gedetecteerd. Standaard wordt een vernieuwingsinterval van 30 seconden gebruikt, maar u kunt dit overschrijven met de refreshIntervalInMs eigenschap.

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

Als u de configuratie alleen instelt refreshOptions , wordt de configuratie niet automatisch vernieuwd. U moet de refresh methode aanroepen op AzureAppConfiguration het exemplaar dat wordt geretourneerd door de load methode om een vernieuwing te activeren.

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

Dit ontwerp voorkomt onnodige aanvragen voor App Configuration wanneer uw toepassing niet actief is. Neem de refresh aanroep op waar uw toepassingsactiviteit plaatsvindt. Dit wordt ook wel activiteitgestuurde configuratievernieuwing genoemd. U kunt bijvoorbeeld aanroepen refresh bij het verwerken van een binnenkomende aanvraag of binnen een iteratie waarin u een complexe taak uitvoert.

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

Zelfs als de vernieuwingsoproep om welke reden dan ook mislukt, blijft uw toepassing de configuratie in de cache gebruiken. Er wordt nog een poging gedaan wanneer het geconfigureerde vernieuwingsinterval is verstreken en de vernieuwingsoproep wordt geactiveerd door uw toepassingsactiviteit. Bellen refresh is een no-op voordat het geconfigureerde vernieuwingsinterval is verstreken, dus de invloed op de prestaties is minimaal, zelfs als het vaak wordt aangeroepen.

Aangepaste callback voor vernieuwen

Met onRefresh de methode kunt u aangepaste callback-functies aanroepen die telkens worden aangeroepen wanneer de lokale configuratie is bijgewerkt met wijzigingen uit het Azure-app Configuratiearchief. Het retourneert een wegwerpobject, dat u kunt gebruiken om de geregistreerde callback te verwijderen

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

Verversen van de sentinel-sleutel

Een sentinel-sleutel is een sleutel die u bijwerkt nadat u de wijziging van alle andere sleutels hebt voltooid. De configuratieprovider bewaakt de sentinel-sleutel in plaats van alle geselecteerde sleutelwaarden. Wanneer er een wijziging wordt gedetecteerd, vernieuwt uw app alle configuratiewaarden.

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

Ga naar Dynamische configuratie gebruiken in JavaScript voor meer informatie over het vernieuwen van de configuratie.

Functievlag

U kunt functievlagmen maken in Azure App Configuration. De functievlagmen worden standaard niet geladen door de configuratieprovider. U kunt het laden en vernieuwen van functievlagmen inschakelen via AzureAppConfigurationOptions.featureFlagOptions de eigenschap bij het aanroepen van de load methode.

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

Functiebeheer

Bibliotheek voor functiebeheer biedt een manier om toepassingsfunctionaliteit te ontwikkelen en beschikbaar te maken op basis van functievlagmen. De functiebeheerbibliotheek is ontworpen om te werken in combinatie met de bibliotheek van de configuratieprovider. De configuratieprovider laadt alle geselecteerde functievlagmen in de configuratie onder de feature_flags lijst van de feature_management sectie. De bibliotheek voor functiebeheer gebruikt en beheert de geladen functievlagmen voor uw toepassing.

In het volgende voorbeeld ziet u hoe u de @microsoft/feature-management bibliotheek integreert met de configuratieprovider om de API-toegankelijkheid in een Express-toepassing dynamisch te beheren op basis van de status van de Beta functievlag.

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

Ga naar de quickstart voor functievlagmarkeringen voor meer informatie over het gebruik van de JavaScript-functiebeheerbibliotheek.

Naslaginformatie over Key Vault

Azure-app Configuration ondersteunt het verwijzen naar geheimen die zijn opgeslagen in Azure Key Vault. In App Configuration kunt u sleutels maken die zijn toegewezen aan geheimen die zijn opgeslagen in Key Vault. De geheimen worden veilig opgeslagen in Key Vault, maar kunnen net als elke andere configuratie worden geopend nadat ze zijn geladen.

De bibliotheek van de configuratieprovider haalt key Vault-verwijzingen op, net zoals voor andere sleutels die zijn opgeslagen in App Configuration. Omdat de client de sleutels herkent als Key Vault-verwijzingen, hebben ze een uniek inhoudstype en maakt de client verbinding met Key Vault om hun waarden voor uw toepassing op te halen. U moet de eigenschap configureren AzureAppConfigurationOptions.KeyVaultOptions met de juiste referentie, zodat de configuratieprovider verbinding kan maken met Azure Key Vault.

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

U kunt ook rechtstreeks een exemplaar aanleverenSecretClient.KeyVaultOptions Op deze manier kunt u de opties aanpassen tijdens het maken 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 ]
    }
});

U kunt de eigenschap ook instellen secretResolver om geheimen die niet aan een Key Vault zijn gekoppeld, lokaal op te lossen.

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

U kunt ook de eigenschap clientOptions instellen om SecretClientOptions te configureren voor verbinding met Azure Key Vault waarvoor geen geregistreerde SecretClient zijn.

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

Parallelle geheime resolutie

Azure Key Vault biedt geen batch-API voor het ophalen van meerdere geheimen in één aanvraag. Wanneer uw toepassing talloze Key Vault-verwijzingen moet laden, kunt u de prestaties verbeteren door parallelle geheime resolutie in te schakelen met behulp van de parallelSecretResolutionEnabled eigenschap in KeyVaultOptions. Hierdoor kan de provider meerdere geheimen parallel ophalen in plaats van sequentieel:

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

Key Vault geheim verversen

Met Azure App Configuration kunt u geheime vernieuwingsintervallen onafhankelijk van uw configuratievernieuwingscyclus configureren. Dit is van cruciaal belang voor beveiliging, omdat de Key Vault-referentie-URI in App Configuration ongewijzigd blijft, het onderliggende geheim in Key Vault mogelijk wordt geroteerd als onderdeel van uw beveiligingsprocedures.

Om ervoor te zorgen dat uw toepassing altijd de meest recente geheime waarden gebruikt, configureert u de secretRefreshIntervalInMs eigenschap in KeyVaultOptions. Dit dwingt de provider om nieuwe geheime waarden op te halen uit Key Vault wanneer:

• Uw toepassingsoproepen AzureAppConfiguration.refresh
• Het geconfigureerde vernieuwingsinterval voor het geheim is verstreken

Dit mechanisme werkt zelfs wanneer er geen wijzigingen worden gedetecteerd in uw App Configuration-winkel, zodat uw toepassing gesynchroniseerd blijft met gewisselde geheimen.

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

Momentopname

Momentopname is een benoemde, onveranderbare subset van de sleutelwaarden van een App Configuration-archief. De sleutelwaarden waaruit een momentopname bestaat, worden tijdens het maken gekozen via het gebruik van sleutel- en labelfilters. Zodra een momentopname is gemaakt, blijven de sleutelwaarden binnen gegarandeerd ongewijzigd.

U kunt momentopnamekiezer gebruiken om sleutelwaarden of functievlagmen uit een momentopname te laden:

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

Opnieuw opstarten

Het laden van de configuratie is een kritieke padbewerking tijdens het opstarten van de toepassing. Om de betrouwbaarheid te garanderen, implementeert de Azure App Configuration-provider een robuust mechanisme voor opnieuw proberen tijdens de eerste configuratiebelasting. Dit helpt uw toepassing te beschermen tegen tijdelijke netwerkproblemen die anders kunnen voorkomen dat het opstarten is geslaagd.

U kunt dit gedrag aanpassen via het AzureAppConfigurationOptions.startupOptionsvolgende:

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

Geo-replicatie

Ga naar Geo-replicatie inschakelen voor informatie over het gebruik van geo-replicatie.

Volgende stappen

Als u wilt weten hoe u de JavaScript-configuratieprovider gebruikt, gaat u verder met de volgende zelfstudie.

Ga verder met de volgende documentatie voor meer informatie over het gebruik van de JavaScript-functiebeheerbibliotheek.