Zprostředkovatel konfigurace JavaScriptu

Azure App Configuration je spravovaná služba, která vývojářům pomáhá jednoduše a bezpečně centralizovat konfigurace aplikací. Knihovna zprostředkovatele konfigurace JavaScriptu umožňuje načítat konfiguraci z úložiště konfigurace Aplikace Azure spravovaným způsobem. Tato klientská knihovna přidává další funkce nad sadu Azure SDK pro JavaScript.

Konfigurace načtení

Metoda load exportovaná v @azure/app-configuration-provider balíčku se používá k načtení konfigurace z Aplikace Azure Konfigurace. Tato load metoda umožňuje buď použít ID Microsoft Entra, nebo připojovací řetězec pro připojení k App Configuration Storu.

Microsoft Entra ID
Připojovací řetězec

Použijete DefaultAzureCredential k ověření ve službě App Configuration Store. Postupujte podle pokynů a přiřaďte své přihlašovací údaje roli Čtenář dat konfigurace aplikace.

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

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

Metoda load vrátí instanci AzureAppConfiguration typu, která je definována takto:

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

Další informace o refresh metodách najdete onRefresh v části Aktualizace konfigurace.

Využití konfigurace

Typ AzureAppConfiguration rozšiřuje následující rozhraní:

IGettable

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

Rozhraní IGettable poskytuje get metodu pro načtení hodnoty klíče-hodnota z mapové datové struktury.

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

Tento AzureAppConfiguration typ také rozšiřuje ReadonlyMap rozhraní a poskytuje přístup jen pro čtení ke párům klíč-hodnota.
IConfigurationObject
```
interface IConfigurationObject {
    constructConfigurationObject(options?: ConfigurationObjectConstructionOptions): Record<string, any>;
}
```
Rozhraní IConfigurationObject poskytuje constructConfigurationObject metodu pro vytvoření objektu konfigurace založené na mapové datové struktuře a hierarchických klíčích. Volitelný ConfigurationObjectConstructionOptions parametr lze použít k určení oddělovače pro převod hierarchických klíčů na vlastnosti objektu. Ve výchozím nastavení je "."oddělovač .
```
interface ConfigurationObjectConstructionOptions {
    separator?: "." | "," | ";" | "-" | "_" | "__" | "/" | ":"; // supported separators
}
```
V JavaScriptu se objekty nebo mapy běžně používají jako primární datové struktury, které představují konfigurace. Knihovna zprostředkovatele konfigurace JavaScriptu podporuje oba přístupy konfigurace, což vývojářům poskytuje flexibilitu při výběru možnosti, která nejlépe vyhovuje jejich potřebám.
```
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
```

Zpracování typu obsahu JSON

Hodnoty klíčů JSON můžete vytvořit v App Configuration. Při načítání hodnot klíčů z Azure App Configuration poskytovatel konfigurace automaticky převede hodnoty klíče platného typu obsahu JSON (např. application/json) na objekt.

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

Výše uvedená hodnota klíče se načte jako { size: 12, color: "red" }.

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

Poznámka:

Počínaje verzí 2.2.0@azure/app-configuration-provider umožňuje poskytovatel konfigurace přidávat komentáře, jak je definováno v JSONC, do klíčových hodnot s typem obsahu application/json.

Načtení konkrétních hodnot klíče pomocí selektorů

Ve výchozím nastavení metoda load načte všechny konfigurace bez popisku z úložiště konfigurace. Chování load metody můžete nakonfigurovat pomocí volitelného parametru AzureAppConfigurationOptions typu.

Pokud chcete upřesnit nebo rozbalit konfigurace načtené z App Configuration Storu AzureAppConfigurationOptions.selectors , můžete zadat klíč nebo selektory popisků pod vlastností.

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

Poznámka:

Hodnoty klíče se načtou v pořadí, ve kterém jsou uvedeny selektory. Pokud více selektorů načte hodnoty klíče se stejným klíčem, hodnota z poslední hodnoty přepíše všechny dříve načtené hodnoty.

Filtry značek

Parametr pro filtrování vybírá hodnoty klíčů s konkrétními značkami. Hodnota klíče se načte pouze v případě, že obsahuje všechny značky a odpovídající hodnoty zadané ve filtrech.

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

Poznámka:

Znaky hvězdička (), čárka (*,) a zpětné lomítko (\) jsou vyhrazeny a musí být uchvácené zpětným lomítkem při použití ve filtru značek.

Oříznutí předpony z klíčů

Předponu z klíčů můžete oříznout zadáním seznamu předpon oříznutých klíčů vlastnosti AzureAppConfigurationOptions.trimKeyPrefixes .

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

Aktualizace konfigurace

Dynamická aktualizace pro konfigurace umožňuje vyžádat si nejnovější hodnoty z App Configuration Storu, aniž byste museli aplikaci restartovat. Můžete nastavit AzureAppConfigurationOptions.refreshOptions , aby se aktualizace povolila a nakonfigurovali možnosti aktualizace. Načtená konfigurace se aktualizuje, když se na serveru zjistí jakákoli změna vybraných hodnot klíčů. Ve výchozím nastavení se používá interval aktualizace 30 sekund, ale můžete ho refreshIntervalInMs přepsat vlastností.

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

Samotné nastavení refreshOptions nebude automaticky aktualizovat konfiguraci. K aktivaci aktualizace je potřeba volat metodu refreshAzureAppConfiguration pro load instanci vrácenou metodou.

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

Tento návrh zabraňuje zbytečným požadavkům na konfiguraci aplikace, když je vaše aplikace nečinná. Měli byste zahrnout volání, refresh ve kterém dojde k aktivitě vaší aplikace. To se označuje jako aktualizace konfigurace řízené aktivitami. Můžete například volat refresh při zpracování příchozího požadavku nebo uvnitř iterace, kde provádíte složitou úlohu.

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

I když volání aktualizace z nějakého důvodu selže, bude vaše aplikace i nadále používat konfiguraci uloženou v mezipaměti. Další pokus se provede, když se předá nakonfigurovaný interval aktualizace a aktivita vaší aplikace aktivuje volání aktualizace. Volání refresh je no-op před uplynutím nakonfigurovaného intervalu aktualizace, takže jeho dopad na výkon je minimální, i když se volá často.

Zpětná volání vlastní aktualizace

Tato onRefresh metoda umožňuje vlastní funkce zpětného volání, které budou vyvolány pokaždé, když se místní konfigurace úspěšně aktualizuje o změny z úložiště konfigurace Aplikace Azure. Vrátí uvolnitelný objekt, který můžete použít k odebrání registrované zpětného volání.

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

Aktualizace klíče sentinel

Klíč sentinelu je klíč, který aktualizujete po dokončení změny všech ostatních klíčů. Zprostředkovatel konfigurace bude místo všech vybraných hodnot klíčů monitorovat klíč sentinelu. Když se zjistí změna, aplikace aktualizuje všechny konfigurační hodnoty.

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

Další informace o konfiguraci aktualizace najdete v tématu Použití dynamické konfigurace v JavaScriptu.

Příznak funkce

Příznaky funkcí můžete vytvářet v konfiguraci Aplikace Azure. Ve výchozím nastavení nebudou příznaky funkcí načteny poskytovatelem konfigurace. Při volání AzureAppConfigurationOptions.featureFlagOptions metody můžete povolit příznaky načítání a aktualizace funkcí prostřednictvím load vlastnosti.

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

Poznámka:

Pokud featureFlagOptions je povolený a není zadán žádný selektor, poskytovatel konfigurace načte všechny příznaky funkcí bez popisku z App Configuration Storu.

Důležité

Pokud chcete efektivně využívat a spravovat příznaky funkcí načtené ze služby Azure App Configuration, nainstalujte a použijte @microsoft/feature-management balíček. Tato knihovna poskytuje strukturovaný způsob řízení chování funkcí ve vaší aplikaci.

Správa funkcí

Knihovna pro správu funkcí poskytuje způsob vývoje a zveřejnění funkcí aplikace na základě příznaků funkcí. Knihovna pro správu funkcí je navržená tak, aby fungovala ve spojení s knihovnou zprostředkovatele konfigurace. Zprostředkovatel konfigurace načte všechny vybrané příznaky funkcí do konfigurace v feature_flags seznamu oddílu feature_management . Knihovna pro správu funkcí bude využívat a spravovat příznaky načtených funkcí pro vaši aplikaci.

Následující příklad ukazuje, jak integrovat knihovnu @microsoft/feature-management s poskytovatelem konfigurace pro dynamické řízení přístupnosti rozhraní API v aplikaci Express na základě stavu příznaku Beta funkce.

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

Další informace o tom, jak používat knihovnu pro správu funkcí JavaScriptu, najdete v rychlém startu s příznakem funkce.

Referenční informace ke službě Key Vault

konfigurace Aplikace Azure podporuje odkazování na tajné kódy uložené ve službě Azure Key Vault. V App Configuration můžete vytvořit klíče, které se mapuje na tajné kódy uložené ve službě Key Vault. Tajné kódy jsou bezpečně uložené ve službě Key Vault, ale po načtení se k nim dají přistupovat stejně jako k jakékoli jiné konfiguraci.

Knihovna zprostředkovatele konfigurace načítá odkazy na službu Key Vault stejně jako u všech dalších klíčů uložených v App Configuration. Vzhledem k tomu, že klient rozpozná klíče jako reference ke službě Key Vault, má jedinečný typ obsahu a klient se připojí ke službě Key Vault a načte své hodnoty pro vaši aplikaci. Musíte nakonfigurovat AzureAppConfigurationOptions.KeyVaultOptions vlastnost se správnými přihlašovacími údaji, aby se poskytovatel konfigurace mohl připojit ke službě Azure Key Vault.

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

Instanci můžete také poskytnout SecretClient přímo do KeyVaultOptions. Tímto způsobem můžete přizpůsobit možnosti při vytváření 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 ]
    }
});

Můžete také nastavit secretResolver vlastnost pro místní řešení tajných kódů, které nemají přidruženou službu Key Vault.

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

Můžete také nastavit vlastnost clientOptions pro konfiguraci SecretClientOptions, které se používá k připojení k Azure Key Vault, která nemá zaregistrované SecretClient.

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

Paralelní tajné usnesení

Azure Key Vault neposkytuje dávkové rozhraní API pro načítání více tajných kódů v jednom požadavku. Když vaše aplikace potřebuje načíst mnoho odkazů služby Key Vault, můžete zlepšit výkon povolením paralelního překladu parallelSecretResolutionEnabled tajných kódů pomocí vlastnosti v KeyVaultOptions. Zprostředkovatel tak může načítat více tajných kódů paralelně, nikoli postupně:

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

Poznámka:

Při paralelním zpracovávání tajemství můžete narazit na limit služby Azure Key Vault. Pokud chcete efektivně zvládnout omezování, implementujte osvědčené postupy omezování na straně klienta tím, že nakonfigurujete vhodné možnosti opakovaných pokusůSecretClient. Můžete buď zaregistrovat vlastní SecretClient instance, nebo nakonfigurovat clientOptions prostřednictvím nástroje AzureAppConfigurationOptions.keyVaultOptions.

Aktualizace tajných kódů služby Key Vault

Azure App Configuration umožňuje konfigurovat intervaly aktualizace tajných kódů nezávisle na cyklu aktualizace konfigurace. To je důležité pro zabezpečení, protože zatímco referenční identifikátor URI služby Key Vault v konfiguraci aplikace zůstává beze změny, může se v rámci vašich postupů zabezpečení obměňovat základní tajný klíč ve službě Key Vault.

Chcete-li zajistit, aby vaše aplikace vždy používala nejaktuálnější hodnoty tajných kódů, nakonfigurujte secretRefreshIntervalInMs vlastnost v KeyVaultOptions. Zprostředkovatel tak vynutí načtení čerstvých tajných hodnot ze služby Key Vault v těchto případech:

Vaše aplikace volá AzureAppConfiguration.refresh
Nakonfigurovaný interval aktualizace tajného kódu uplynul.

Tento mechanismus funguje i v případě, že se v úložišti konfigurace aplikace nezjistí žádné změny, takže vaše aplikace zůstane synchronizovaná s rotujícími tajemstvími.

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

Snímek

Snímek je pojmenovaná, neměnná podmnožina klíčů a hodnot v úložišti App Configuration. Hodnoty klíčů, které tvoří snímek, se vyberou během vytváření prostřednictvím filtrů klíčů a popisků. Po vytvoření snímku se zaručuje, že hodnoty klíče v rámci zůstanou beze změny.

Pomocí selektoru snímků můžete načíst hodnoty klíčů nebo příznaky funkcí ze snímku:

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

Opakovaný pokus o spuštění

Načítání konfigurace je kritická operace během spouštění aplikace. Kvůli zajištění spolehlivosti implementuje poskytovatel azure App Configuration robustní mechanismus opakování během počátečního zatížení konfigurace. To pomáhá chránit vaši aplikaci před přechodnými problémy se sítí, které by jinak mohly bránit úspěšnému spuštění.

Toto chování můžete přizpůsobit pomocí AzureAppConfigurationOptions.startupOptionspříkazu :

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

Geografická replikace

Informace o použití geografické replikace najdete v tématu Povolení geografické replikace.

Další kroky

Pokud chcete zjistit, jak používat zprostředkovatele konfigurace JavaScriptu, pokračujte následujícím kurzem.

Použití dynamické konfigurace v JavaScriptu

Pokud chcete zjistit, jak používat knihovnu pro správu funkcí JavaScriptu, pokračujte v následující dokumentaci.

Správa funkcí JavaScriptu

Váš názor

Byla tato stránka užitečná?

Last updated on 2025-08-20

Sdílet prostřednictvím

Zprostředkovatel konfigurace JavaScriptu

Konfigurace načtení

Využití konfigurace

Zpracování typu obsahu JSON

Načtení konkrétních hodnot klíče pomocí selektorů

Filtry značek

Oříznutí předpony z klíčů

Aktualizace konfigurace

Zpětná volání vlastní aktualizace

Aktualizace klíče sentinel

Příznak funkce

Správa funkcí

Referenční informace ke službě Key Vault

Paralelní tajné usnesení

Aktualizace tajných kódů služby Key Vault

Snímek

Opakovaný pokus o spuštění

Geografická replikace

Další kroky

Váš názor

Další materiály