Lezen in het Engels

Delen via


JavaScript-configuratieprovider

configuration-provider-npm-package

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.

U gebruikt de DefaultAzureCredential app om u te verifiëren bij uw App Configuration-archief. Volg de instructies om uw referenties toe te wijzen aan de rol App Configuration Data Reader .

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

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

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

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

Configuratie gebruiken

Het AzureAppConfiguration type breidt de volgende interfaces uit:

  • IGettable

    TypeScript
    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.

    TypeScript
    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

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

  • IConfigurationObject

    TypeScript
    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 .

    TypeScript
    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.

    TypeScript
    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
    

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.

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

Notitie

Sleutelwaarden worden geladen in de volgorde waarin de selectors worden weergegeven. Als meerdere selectors sleutelwaarden met dezelfde sleutel ophalen, overschrijft de waarde van de laatste waarde een eerder geladen waarde.

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.

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

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.

TypeScript
const credential = new DefaultAzureCredential();
const settings = 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.

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

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

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

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.

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

TypeScript
// this call is not blocking, the configuration will be updated asynchronously
settings.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.

TypeScript
const server = express();
// Use an express middleware to refresh configuration whenever a request comes in
server.use((req, res, next) => {
    settings.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

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

Vernieuwen op sentinel-sleutel (verouderd)

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.

TypeScript
const settings = 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 Configuratie. 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.

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

Notitie

Als featureFlagOptions deze optie is ingeschakeld en er geen selector is opgegeven, laadt de configuratieprovider alle functievlagmen zonder label uit het App Configuration-archief.

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.

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

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.