Dostawca konfiguracji języka JavaScript

Usługa Azure App Configuration to usługa zarządzana, która pomaga deweloperom w prosty i bezpieczny sposób scentralizować konfigurację aplikacji. Biblioteka dostawcy konfiguracji języka JavaScript umożliwia ładowanie konfiguracji z magazynu konfiguracji aplikacja systemu Azure w zarządzany sposób. Ta biblioteka klienta dodaje dodatkowe funkcje powyżej zestawu Azure SDK dla języka JavaScript.

Ładowanie konfiguracji

Metoda load wyeksportowana w pakiecie @azure/app-configuration-provider służy do ładowania konfiguracji z aplikacja systemu Azure Configuration. Metoda load umożliwia użycie identyfikatora Entra firmy Microsoft lub parametry połączenia w celu nawiązania połączenia z magazynem App Configuration.

Tożsamość Microsoft Entra
Parametry połączenia

Użyj polecenia DefaultAzureCredential , aby uwierzytelnić się w magazynie usługi App Configuration. Postępuj zgodnie z instrukcjami, aby przypisać poświadczenia roli Czytelnik danych konfiguracji aplikacji.

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 zwraca wystąpienie AzureAppConfiguration typu, które jest zdefiniowane w następujący sposób:

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

Aby uzyskać więcej informacji na temat refresh metod i onRefresh , zobacz sekcję Odświeżanie konfiguracji.

Korzystanie z konfiguracji

Typ AzureAppConfiguration rozszerza następujące interfejsy:

IGettable

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

Interfejs IGettable udostępnia get metodę pobierania wartości klucz-wartość ze struktury danych w stylu mapy.

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

Typ AzureAppConfiguration rozszerza ReadonlyMap również interfejs, zapewniając dostęp tylko do odczytu do par klucz-wartość.
IConfigurationObject
```
interface IConfigurationObject {
    constructConfigurationObject(options?: ConfigurationObjectConstructionOptions): Record<string, any>;
}
```
Interfejs IConfigurationObject udostępnia constructConfigurationObject metodę konstruowania obiektu konfiguracji na podstawie struktury danych w stylu mapy i kluczy hierarchicznych. Opcjonalny ConfigurationObjectConstructionOptions parametr może służyć do określenia separatora do konwertowania kluczy hierarchicznych na właściwości obiektu. Domyślnie separatorem jest ".".
```
interface ConfigurationObjectConstructionOptions {
    separator?: "." | "," | ";" | "-" | "_" | "__" | "/" | ":"; // supported separators
}
```
W języku JavaScript obiekty lub mapy są często używane jako podstawowe struktury danych do reprezentowania konfiguracji. Biblioteka dostawcy konfiguracji języka JavaScript obsługuje obie metody konfiguracji, zapewniając deweloperom elastyczność wyboru opcji, która najlepiej odpowiada ich potrzebom.
```
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
```

Obsługa typów zawartości JSON

Możesz utworzyć wartości kluczy JSON w usłudze App Configuration. Podczas ładowania par klucz-wartość z usługi Azure App Configuration dostawca konfiguracji automatycznie konwertuje wartości kluczowe prawidłowego typu zawartości JSON (np. application/json) do formatu obiektu.

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

Powyższa wartość klucza zostanie załadowana jako { size: 12, color: "red" }.

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

Uwaga

Począwszy od wersji 2.2.0 programu @azure/app-configuration-provider, dostawca konfiguracji zezwala na komentarze zgodnie z definicją w formacie (JSONC) w wartościach klucza z typem application/json zawartości.

Ładowanie określonych klucz-wartości przy użyciu selektorów

Domyślnie load metoda załaduje wszystkie konfiguracje bez etykiety z magazynu konfiguracji. Zachowanie metody można skonfigurować load za pomocą opcjonalnego parametru AzureAppConfigurationOptions typu.

Aby uściślić lub rozwinąć konfiguracje załadowane ze sklepu App Configuration, możesz określić selektory kluczy lub etykiet w ramach AzureAppConfigurationOptions.selectors właściwości .

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

Uwaga

Wartości klucza są ładowane w kolejności, w której selektory są wyświetlane. Jeśli wiele selektorów pobiera wartości klucza z tym samym kluczem, wartość z ostatniego selektora zastąpi dowolną wcześniej załadowaną wartość.

Filtry tagów

Parametr filtrów tagów wybiera wartości klucza z określonymi tagami. Wartość-klucz jest ładowana tylko wtedy, gdy zawiera wszystkie tagi i odpowiednie wartości określone w filtrach.

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

Uwaga

Znaki gwiazdki (*), przecinek (,) i ukośnik odwrotny (\) są zastrzeżone i muszą zostać uniknięte ukośnikiem odwrotnym, gdy są używane w filtrze tagu.

Przycinanie prefiksu z kluczy

Prefiks kluczy można przyciąć, podając listę przyciętych prefiksów kluczy do AzureAppConfigurationOptions.trimKeyPrefixes właściwości .

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

Odświeżanie konfiguracji

Dynamiczne odświeżanie konfiguracji umożliwia ściąganie najnowszych wartości ze sklepu App Configuration bez konieczności ponownego uruchamiania aplikacji. Możesz ustawić opcję AzureAppConfigurationOptions.refreshOptions włączania odświeżania i konfigurowania opcji odświeżania. Załadowana konfiguracja zostanie zaktualizowana po wykryciu dowolnej zmiany wybranych wartości kluczy na serwerze. Domyślnie jest używany interwał odświeżania wynoszący 30 sekund, ale można go zastąpić właściwością refreshIntervalInMs .

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

Skonfigurowanie refreshOptions samej konfiguracji nie spowoduje automatycznego odświeżenia konfiguracji. Aby wyzwolić odświeżanie, należy wywołać metodę refresh w AzureAppConfiguration wystąpieniu load zwróconą przez metodę .

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

Ten projekt uniemożliwia niepotrzebne żądania do usługi App Configuration, gdy aplikacja jest bezczynna. Należy dołączyć refresh wywołanie, w którym występuje działanie aplikacji. Jest to nazywane odświeżaniem konfiguracji opartej na działaniach. Można na przykład wywołać refresh metodę przetwarzania żądania przychodzącego lub wewnątrz iteracji, w której wykonujesz złożone zadanie.

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

Nawet jeśli wywołanie odświeżania zakończy się niepowodzeniem z jakiegokolwiek powodu, aplikacja będzie nadal używać buforowanej konfiguracji. Kolejna próba zostanie podjęta po upływie skonfigurowanego interwału odświeżania, a wywołanie odświeżania zostanie wyzwolone przez działanie aplikacji. Wywołanie refresh jest operacją no-op przed upływem skonfigurowanego interwału odświeżania, więc jego wpływ na wydajność jest minimalny, nawet jeśli jest wywoływany często.

Wywołanie zwrotne odświeżania niestandardowego

Metoda onRefresh umożliwia niestandardowe funkcje wywołania zwrotnego, które będą wywoływane za każdym razem, gdy konfiguracja lokalna zostanie pomyślnie zaktualizowana o zmiany z magazynu konfiguracji aplikacja systemu Azure. Zwraca obiekt Jednorazowy, którego można użyć do usunięcia zarejestrowanego wywołania zwrotnego

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

Odświeżanie klucza sentinel

Klucz sentinel to klucz aktualizowany po zakończeniu zmiany wszystkich innych kluczy. Dostawca konfiguracji będzie monitorować klucz sentinel zamiast wszystkich wybranych klucz-wartości. Po wykryciu zmiany aplikacja odświeża wszystkie wartości konfiguracji.

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

Aby uzyskać więcej informacji na temat konfiguracji odświeżania, zobacz Używanie konfiguracji dynamicznej w języku JavaScript.

Flaga funkcji

Flagi funkcji można tworzyć w konfiguracji aplikacja systemu Azure. Domyślnie flagi funkcji nie będą ładowane przez dostawcę konfiguracji. Podczas wywoływania AzureAppConfigurationOptions.featureFlagOptions metody można włączyć ładowanie i odświeżanie flag funkcji za pomocą load właściwości.

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

Uwaga

Jeśli featureFlagOptions opcja jest włączona i nie określono selektora, dostawca konfiguracji załaduje wszystkie flagi funkcji bez etykiety ze sklepu App Configuration Store.

Ważne

Aby efektywnie korzystać z flag funkcji załadowanych z usługi Azure App Configuration i zarządzać nimi, zainstaluj pakiet i użyj go @microsoft/feature-management . Ta biblioteka zapewnia ustrukturyzowany sposób kontrolowania zachowania funkcji w aplikacji.

Zarządzanie funkcjami

Biblioteka zarządzania funkcjami umożliwia opracowywanie i uwidacznianie funkcjonalności aplikacji na podstawie flag funkcji. Biblioteka zarządzania funkcjami jest przeznaczona do pracy w połączeniu z biblioteką dostawcy konfiguracji. Dostawca konfiguracji załaduje wszystkie wybrane flagi funkcji do konfiguracji na feature_flags liście feature_management sekcji. Biblioteka zarządzania funkcjami będzie używać flag załadowanych funkcji i zarządzać nimi dla aplikacji.

W poniższym przykładzie pokazano, jak zintegrować bibliotekę @microsoft/feature-management z dostawcą konfiguracji w celu dynamicznego kontrolowania dostępu do API w aplikacji Express na podstawie stanu flag funkcji Beta.

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

Aby uzyskać więcej informacji na temat korzystania z biblioteki zarządzania funkcjami języka JavaScript, przejdź do przewodnika Szybki start flagi funkcji.

Dokumentacja usługi Key Vault

aplikacja systemu Azure Configuration obsługuje odwoływanie się do wpisów tajnych przechowywanych w usłudze Azure Key Vault. W usłudze App Configuration można tworzyć klucze mapowane na wpisy tajne przechowywane w usłudze Key Vault. Wpisy tajne są bezpiecznie przechowywane w usłudze Key Vault, ale można uzyskać dostęp do dowolnej innej konfiguracji po załadowaniu.

Biblioteka dostawcy konfiguracji pobiera odwołania do usługi Key Vault, podobnie jak w przypadku innych kluczy przechowywanych w usłudze App Configuration. Ponieważ klient rozpoznaje klucze jako odwołania do usługi Key Vault, ma unikatowy typ zawartości, a klient połączy się z usługą Key Vault, aby pobrać ich wartości dla aplikacji. Należy skonfigurować AzureAppConfigurationOptions.KeyVaultOptions właściwość przy użyciu odpowiednich poświadczeń, aby umożliwić dostawcy konfiguracji nawiązanie połączenia z usługą Azure Key Vault.

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

Możesz również podać SecretClient wystąpienie bezpośrednio do KeyVaultOptionselementu . W ten sposób można dostosować opcje podczas tworzenia SecretClientelementu .

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

Możesz również ustawić secretResolver właściwość na lokalne rozpoznawanie wpisów tajnych, które nie mają skojarzonej z nimi usługi Key Vault.

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

Możesz również ustawić właściwość clientOptions, aby skonfigurować SecretClientOptions, używaną do łączenia się z usługą Azure Key Vault, która nie ma zarejestrowanego elementu SecretClient.

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

Równoległe tajne rozstrzygnięcie

Usługa Azure Key Vault nie udostępnia interfejsu API do operacji wsadowych do pobierania wielu tajemnic w jednym żądaniu. Jeśli aplikacja musi załadować wiele odwołań usługi Key Vault, możesz zwiększyć wydajność, włączając równoległe rozpoznawanie wpisów tajnych, używając właściwości parallelSecretResolutionEnabled w pliku KeyVaultOptions. Dzięki temu dostawca może pobierać wiele sekretów równolegle, a nie sekwencyjnie.

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

Uwaga

Podczas równoczesnego rozwiązywania tajemnicy możesz napotkać limit usługi Azure Key Vault. Aby efektywnie obsługiwać ograniczanie przepustowości, zaimplementuj najlepsze rozwiązania dotyczące ograniczania przepustowości po stronie klienta , konfigurując odpowiednie opcje ponawiania prób dla elementu SecretClient. Możesz zarejestrować wystąpienia niestandardowe SecretClient lub skonfigurować clientOptions za pomocą polecenia AzureAppConfigurationOptions.keyVaultOptions.

Odświeżanie sekretów Key Vault

Usługa Azure App Configuration umożliwia konfigurowanie interwałów odświeżania tajnych danych niezależnie od cyklu odświeżania konfiguracji. Ma to kluczowe znaczenie dla bezpieczeństwa, ponieważ identyfikator URI odwołania do Key Vault w App Configuration pozostaje niezmieniony, podczas gdy ukryty sekret w Key Vault może być rotowany w ramach praktyk bezpieczeństwa.

Aby upewnić się, że aplikacja zawsze używa najbardziej bieżących wartości wpisów tajnych, skonfiguruj secretRefreshIntervalInMs właściwość w pliku KeyVaultOptions. To zmusza dostawcę do pobierania aktualnych wartości tajnych z usługi Key Vault, gdy:

Twoja aplikacja wywołuje AzureAppConfiguration.refresh
Skonfigurowany interwał odświeżania wpisu tajnego upłynął

Ten mechanizm działa nawet wtedy, gdy w magazynie App Configuration nie zostaną wykryte żadne zmiany, zapewniając, że aplikacja pozostaje zsynchronizowana z aktualizowanymi sekretami.

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

Migawka

Migawka jest nazwanym, niezmiennym podzbiorem wartości kluczy sklepu App Configuration. Wartości klucza tworzące migawkę są wybierane w czasie tworzenia za pomocą filtrów kluczy i etykiet. Po utworzeniu migawki gwarantowane są wartości kluczy w ramach programu .

Za pomocą selektora migawek można załadować wartości kluczy lub flagi funkcji z migawki.

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

Ponów próbę ponownego uruchamiania

Ładowanie konfiguracji jest operacją krytyczną podczas uruchamiania aplikacji. Aby zapewnić niezawodność, dostawca usługi Azure App Configuration implementuje niezawodny mechanizm ponawiania prób podczas początkowego ładowania konfiguracji. Pomaga to chronić aplikację przed przejściowymi problemami z siecią, które w przeciwnym razie mogą uniemożliwić pomyślne uruchomienie.

To zachowanie można dostosować za pomocą polecenia AzureAppConfigurationOptions.startupOptions:

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

Replikacja geograficzna

Aby uzyskać informacje na temat korzystania z replikacji geograficznej, przejdź do tematu Włączanie replikacji geograficznej.

Następne kroki

Aby dowiedzieć się, jak używać dostawcy konfiguracji języka JavaScript, przejdź do następującego samouczka.

Używanie konfiguracji dynamicznej w języku JavaScript

Aby dowiedzieć się, jak używać biblioteki zarządzania funkcjami języka JavaScript, przejdź do poniższej dokumentacji.

Zarządzanie funkcjami języka JavaScript

Sprzężenie zwrotne

Czy ta strona była pomocna?

Last updated on 2025-08-20

Udostępnij za pomocą

Dostawca konfiguracji języka JavaScript

Ładowanie konfiguracji

Korzystanie z konfiguracji

Obsługa typów zawartości JSON

Ładowanie określonych klucz-wartości przy użyciu selektorów

Filtry tagów

Przycinanie prefiksu z kluczy

Odświeżanie konfiguracji

Wywołanie zwrotne odświeżania niestandardowego

Odświeżanie klucza sentinel

Flaga funkcji

Zarządzanie funkcjami

Dokumentacja usługi Key Vault

Równoległe tajne rozstrzygnięcie

Odświeżanie sekretów Key Vault

Migawka

Ponów próbę ponownego uruchamiania

Replikacja geograficzna

Następne kroki

Sprzężenie zwrotne

Dodatkowe zasoby