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

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

run();

Připojovací řetězec

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

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

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

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

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.

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

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

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

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 settings = await load(endpoint, credential, {
    keyVaultOptions: {
        secretResolver: resolveSecret
    }
});

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 settings = 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 refreshload pro AzureAppConfiguration instanci vrácenou metodou.

// this call is not blocking, the configuration will be updated asynchronously
settings.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) => {
    settings.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 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();

Aktualizace klíče sentinelu (starší verze)

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 settings = 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í load metody můžete povolit příznaky načítání a aktualizace funkcí prostřednictvím AzureAppConfigurationOptions.featureFlagOptions vlastnosti.

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

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.

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.

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

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