JavaScript-Konfigurationsanbieter

Azure App Configuration ist ein verwalteter Dienst, mit dem Entwickler ihre Anwendungskonfigurationen einfach und sicher zentralisieren können. Die JavaScript-Konfigurationsanbieterbibliothek ermöglicht das verwaltete Laden einer Konfiguration aus einem Azure App Configuration-Speicher. Diese Clientbibliothek fügt zusätzliche Funktionen über dem Azure SDK für JavaScript hinzu.

Laden der Konfiguration

Die exportierte Methode load im Paket @azure/app-configuration-provider wird verwendet, um die Konfiguration aus Azure App Configuration zu laden. Mit der load-Methode können Sie entweder Microsoft Entra ID oder eine Verbindungszeichenfolge verwenden, um eine Verbindung mit dem App Configuration-Speicher herzustellen.

Microsoft Entra-ID
Verbindungszeichenfolge

Sie verwenden die DefaultAzureCredential für die Authentifizierung beim App Configuration-Speicher. Befolgen Sie die Anweisungen, um Ihren Anmeldeinformationen die Rolle App Configuration-Datenleser zuzuweisen.

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

Die load-Methode gibt eine Instanz vom Typ AzureAppConfiguration zurück, die wie folgt definiert ist:

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

Weitere Informationen zu den Methoden refresh und onRefresh finden Sie im Abschnitt Konfigurationsaktualisierung.

Nutzen der Konfiguration

Der Typ AzureAppConfiguration erweitert die folgenden Schnittstellen:

IGettable

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

Die Schnittstelle IGettable stellt die Methode get zum Abrufen des Werts eines Schlüsselwerts aus der Datenstruktur im Kartenstil bereit.

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

Der Typ AzureAppConfiguration erweitert außerdem die Schnittstelle ReadonlyMap und bietet schreibgeschützten Zugriff auf Schlüssel-Wert-Paare.
IConfigurationObject
```
interface IConfigurationObject {
    constructConfigurationObject(options?: ConfigurationObjectConstructionOptions): Record<string, any>;
}
```
Die Schnittstelle IConfigurationObject stellt die Methode constructConfigurationObject bereit, um ein Konfigurationsobjekt basierend auf einer Datenstruktur im Kartenstil und hierarchischen Schlüsseln zu erstellen. Der optionale Parameter ConfigurationObjectConstructionOptions kann verwendet werden, um das Trennzeichen zum Konvertieren hierarchischer Schlüssel in Objekteigenschaften anzugeben. Standardmäßig ist das Trennzeichen ".".
```
interface ConfigurationObjectConstructionOptions {
    separator?: "." | "," | ";" | "-" | "_" | "__" | "/" | ":"; // supported separators
}
```
In JavaScript werden häufig Objekte oder Zuordnungen als primäre Datenstrukturen verwendet, um Konfigurationen darzustellen. Die JavaScript-Konfigurationsanbieterbibliothek unterstützt beide Konfigurationsansätze und bietet Entwickenden die Flexibilität, die Option auszuwählen, die ihren Anforderungen am besten entspricht.
```
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
```

JSON-Inhaltstypbehandlung

Sie können JSON-Schlüsselwerte in der App-Konfiguration erstellen . Beim Laden von Schlüsselwerten aus der Azure App-Konfiguration konvertiert der Konfigurationsanbieter automatisch die Schlüsselwerte des gültigen JSON-Inhaltstyps (z. B. Application/json) in ein Objekt.

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

Der obige Schlüsselwert wird als { size: 12, color: "red" }geladen.

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

Hinweis

Ab Version 2.2.0@azure/app-configuration-providerermöglicht der Konfigurationsanbieter Kommentare, wie in JSONC definiert, in Schlüsselwerten mit einem application/json Inhaltstyp.

Laden bestimmter Schlüsselwerte mithilfe von Selektoren

Standardmäßig lädt die Methode load alle Konfigurationen ohne Bezeichnung aus dem Konfigurationsspeicher. Sie können das Verhalten der Methode load über den optionalen Parameter vom Typ AzureAppConfigurationOptions konfigurieren.

Um die aus dem App Configuration-Speicher geladenen Konfigurationen zu optimieren oder zu erweitern, können Sie die Schlüssel- oder Bezeichnungsselektoren unter der Eigenschaft AzureAppConfigurationOptions.selectors angeben.

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

Hinweis

Schlüsselwerte werden in der Reihenfolge geladen, in der die Selektoren aufgelistet sind. Wenn mehrere Selektoren Schlüsselwerte mit demselben Schlüssel abrufen, überschreibt der Wert des letzten Selektors alle zuvor geladenen Werte.

Tag-Filter

Der Parameter "Tagfilter" wählt Schlüsselwerte mit bestimmten Tags aus. Ein Schlüsselwert wird nur geladen, wenn er alle Tags und die entsprechenden Werte enthält, die in den Filtern angegeben sind.

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

Hinweis

Die Zeichen Sternchen (*), Komma (,) und umgekehrter Schrägstrich (\) sind reserviert und müssen mit einem umgekehrten Schrägstrich versehen werden, wenn sie in einem Tagfilter verwendet werden.

Kürzen des Schlüsselpräfixes

Sie können das Präfix von Schlüsseln kürzen, indem Sie eine Liste mit gekürzten Schlüsselpräfixen für die Eigenschaft AzureAppConfigurationOptions.trimKeyPrefixes bereitstellen.

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

Konfigurationsaktualisierung

Mit der dynamischen Aktualisierung für die Konfigurationen können Sie die neuesten Werte aus dem App Configuration-Speicher pullen, ohne die Anwendung neu starten zu müssen. Sie können AzureAppConfigurationOptions.refreshOptions festlegen, um die Aktualisierungsoptionen zu aktualisieren und zu konfigurieren. Die geladene Konfiguration wird aktualisiert, wenn Änderungen der ausgewählten Schlüsselwerte auf dem Server erkannt werden. Standardmäßig wird ein Aktualisierungsintervall von 30 Sekunden verwendet, Sie können es jedoch mit der refreshIntervalInMs-Eigenschaft überschreiben.

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

Das Einrichten von refreshOptions allein aktualisiert die Konfiguration nicht automatisch. Sie müssen die Methode refresh für die AzureAppConfiguration-Instanz aufrufen, die von der load-Methode zurückgegeben wird, um eine Aktualisierung auszulösen.

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

Dieses Design verhindert unnötige Anforderungen an die App-Konfiguration, wenn ihre Anwendung im Leerlauf ist. Sie sollten den Aufruf refresh dort verwenden, wo Ihre Anwendungsaktivität auftritt. Dies wird als aktivitätsgesteuerte Konfigurationsaktualisierung bezeichnet. Sie können z. B. refresh beim Verarbeiten einer eingehenden Anforderung oder innerhalb einer Iteration aufrufen, in der Sie eine komplexe Aufgabe ausführen.

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

Selbst wenn der refresh-Aufruf aus irgendeinem Grund fehlschlägt, verwendet Ihre Anwendung weiterhin die zwischengespeicherte Konfiguration. Ein weiterer Versuch wird unternommen, wenn das konfigurierte Aktualisierungsintervall verstrichen ist und der refresh-Aufruf von Ihrer Anwendungsaktivität ausgelöst wird. Das Aufrufen von refresh ist vor Verstreichen des konfigurierten Aktualisierungsintervalls keine Option. Daher sind die Auswirkungen auf die Leistung minimal, auch wenn der Aufruf häufig erfolgt.

Benutzerdefinierter Aktualisierungsrückruf

Mit der onRefresh-Methode können Sie benutzerdefinierte Rückruffunktionen verwenden, die jedes Mal aufgerufen werden, wenn die lokale Konfiguration erfolgreich mit Änderungen aus dem Azure App Configuration-Speicher aktualisiert wird. Sie gibt ein verwerfbares Objekt zurück, mit dem Sie den registrierten Rückruf entfernen können.

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

Aktualisieren bei einem Sentinelschlüssel

Ein Sentinel-Schlüssel ist ein Schlüssel, den Sie aktualisieren, nachdem Sie die Änderung aller anderen Schlüssel abgeschlossen haben. Der Konfigurationsanbieter überwacht den Sentinelschlüssel anstelle aller ausgewählten Schlüsselwerte. Wird eine Änderung erkannt, werden alle Konfigurationswerte von Ihrer App aktualisiert.

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

Weitere Informationen zur Aktualisierungskonfiguration finden Sie unter Verwenden der dynamischen Konfiguration in JavaScript.

Featureflag

Sie können in Azure App Configuration Featureflags erstellen. Standardmäßig werden die Featureflags nicht vom Konfigurationsanbieter geladen. Sie können das Laden und Aktualisieren von Featureflags über die Eigenschaft AzureAppConfigurationOptions.featureFlagOptions beim Aufrufen der load-Methode aktivieren.

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

Hinweis

Wenn featureFlagOptions aktiviert und kein Selektor angegeben ist, lädt der Konfigurationsanbieter alle Featureflags ohne Bezeichnung aus dem App Configuration-Speicher.

Von Bedeutung

Um Featurekennzeichnungen, die aus der Azure-App-Konfiguration geladen wurden, effektiv zu nutzen und zu verwalten, installieren und verwenden Sie das @microsoft/feature-management Paket. Diese Bibliothek bietet eine strukturierte Möglichkeit zum Steuern des Featureverhaltens in Ihrer Anwendung.

Funktionsverwaltung

Die Featureverwaltungsbibliothek bietet eine Möglichkeit, Anwendungsfunktionen basierend auf Featureflags zu entwickeln und verfügbar zu machen. Die Featureverwaltungsbibliothek ist so konzipiert, dass sie mit der Konfigurationsanbieterbibliothek zusammenarbeitet. Der Konfigurationsanbieter lädt alle ausgewählten Featureflags in die Konfiguration unter der Liste feature_flags des Abschnitts feature_management. Die Featureverwaltungsbibliothek verwendet und verwaltet die geladenen Featureflags für Ihre Anwendung.

Im folgenden Beispiel wird veranschaulicht, wie die @microsoft/feature-management Bibliothek in den Konfigurationsprovider integriert wird, um die API-Zugänglichkeit in einer Express-Anwendung dynamisch basierend auf dem Status des Beta Feature-Flags zu steuern.

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

Weitere Informationen zur Verwendung der JavaScript-Featureverwaltungsbibliothek finden Sie im Schnellstart zu Featureflags.

Key Vault-Verweis

Azure App Configuration unterstützt das Verweisen auf Geheimnisse, die in Azure Key Vault gespeichert sind. Sie können in App Configuration Schlüssel erstellen, die in Key Vault gespeicherten Geheimnissen zugeordnet sind. Die Geheimnisse werden sicher in Key Vault gespeichert, auf sie kann aber nach dem Laden wie auf jede andere Konfiguration zugegriffen werden.

Die Konfigurationsanbieterbibliothek ruft Key Vault-Verweise ab, wie dies auch für alle anderen Schlüssel der Fall ist, die in App Configuration gespeichert sind. Da der Client die Schlüssel als Key Vault-Verweise erkennt, haben sie einen eindeutigen Inhaltstyp, und der Client stellt eine Verbindung mit Key Vault her, um ihre Werte für Ihre Anwendung abzurufen. Sie müssen die Eigenschaft AzureAppConfigurationOptions.KeyVaultOptions mit den richtigen Anmeldeinformationen konfigurieren, damit der Konfigurationsanbieter eine Verbindung mit Azure Key Vault herstellen kann.

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

Sie können auch die SecretClient-Instanz direkt für KeyVaultOptions bereitstellen. Auf diese Weise können Sie die Optionen beim Erstellen von SecretClient anpassen.

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

Sie können auch die Eigenschaft secretResolver festlegen, um Geheimnisse lokal aufzulösen, denen keine Key Vault-Instanz zugeordnet ist.

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

Sie können auch die Eigenschaft clientOptions festlegen, um SecretClientOptions zu konfigurieren, die zum Herstellen einer Verbindung mit Azure Key Vault verwendet wird, in dem kein SecretClient registriert ist.

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

Parallele Geheimnisauflösung

Azure Key Vault stellt keine Batch-API zum Abrufen mehrerer geheimer Schlüssel in einer einzigen Anforderung bereit. Wenn Ihre Anwendung zahlreiche Key Vault-Verweise laden muss, können Sie die Leistung verbessern, indem Sie die parallele geheime Auflösung mithilfe der parallelSecretResolutionEnabled Eigenschaft in KeyVaultOptionsaktivieren. Dadurch kann der Anbieter mehrere geheime Schlüssel parallel abrufen und nicht sequenziell:

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

Hinweis

Wenn Sie den geheimen Schlüssel parallel auflösen, tritt möglicherweise das Dienstlimit von Azure Key Vault auf. Um die Drosselung effektiv zu handhaben, implementieren Sie die bewährten Verfahren für die clientseitige Drosselung, indem Sie geeignete Wiederholungsoptionen für die SecretClient konfigurieren. Sie können entweder benutzerdefinierte Instanzen von SecretClient registrieren oder clientOptions über die AzureAppConfigurationOptions.keyVaultOptions konfigurieren.

Key Vault-Geheimnisaktualisierung

Mit der Azure App-Konfiguration können Sie geheime Aktualisierungsintervalle unabhängig vom Aktualisierungszyklus der Konfiguration konfigurieren. Dies ist für die Sicherheit von entscheidender Bedeutung, da der Key Vault-Referenz-URI in der App-Konfiguration unverändert bleibt, der zugrunde liegende Schlüssel im Key Vault jedoch möglicherweise im Rahmen Ihrer Sicherheitspraktiken rotiert wird.

Um sicherzustellen, dass Ihre Anwendung immer die aktuellsten geheimen Werte verwendet, konfigurieren Sie die secretRefreshIntervalInMs Eigenschaft in KeyVaultOptions. Dadurch wird der Anbieter gezwungen, frische geheime Werte aus Key Vault abzurufen, wenn:

Ihre Anwendung ruft AzureAppConfiguration.refresh auf
Das konfigurierte Aktualisierungsintervall für den geheimen Schlüssel ist abgelaufen.

Dieser Mechanismus funktioniert auch dann, wenn im App Configuration-Speicher keine Änderungen erkannt werden, um sicherzustellen, dass Ihre Anwendung mit rotierten geheimen Schlüsseln synchronisiert bleibt.

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

Schnappschuss

Snapshot ist eine benannte, unveränderliche Teilmenge der Schlüsselwerte eines App-Konfigurationsspeichers. Die Schlüsselwerte, aus denen eine Momentaufnahme besteht, werden während der Erstellungszeit durch die Verwendung von Schlüssel- und Bezeichnungsfiltern ausgewählt. Nachdem eine Momentaufnahme erstellt wurde, bleiben die darin enthaltenen Schlüsselwerte garantiert unverändert.

Sie können die Momentaufnahmeauswahl verwenden, um Schlüsselwerte oder Featurekennzeichnungen aus einer Momentaufnahme zu 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" }
        ]
    }
});

Neustart-Versuch

Beim Laden der Konfiguration handelt es sich um einen kritischen Pfadvorgang beim Starten der Anwendung. Um die Zuverlässigkeit zu gewährleisten, implementiert der Azure App-Konfigurationsanbieter während der anfänglichen Konfigurationslast einen robusten Wiederholungsmechanismus. Dadurch wird Ihre Anwendung vor vorübergehenden Netzwerkproblemen geschützt, die andernfalls den erfolgreichen Start verhindern können.

Sie können dieses Verhalten über folgendes AzureAppConfigurationOptions.startupOptionsanpassen:

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

Georeplikation

Informationen zur Verwendung der Georeplikation finden Sie unter Aktivieren der Georeplikation.

Nächste Schritte

Um zu erfahren, wie Sie den JavaScript-Konfigurationsanbieter verwenden, fahren Sie mit dem folgenden Tutorial fort:

Verwenden der dynamischen Konfiguration in JavaScript

Um zu erfahren, wie Sie die JavaScript-Featureverwaltungsbibliothek verwenden, fahren Sie mit der folgenden Dokumentation fort.

JavaScript-Featureverwaltung

Feedback

War diese Seite hilfreich?

Last updated on 2025-09-22

Freigeben über

JavaScript-Konfigurationsanbieter

Laden der Konfiguration

Nutzen der Konfiguration

JSON-Inhaltstypbehandlung

Laden bestimmter Schlüsselwerte mithilfe von Selektoren

Tag-Filter

Kürzen des Schlüsselpräfixes

Konfigurationsaktualisierung

Benutzerdefinierter Aktualisierungsrückruf

Aktualisieren bei einem Sentinelschlüssel

Featureflag

Funktionsverwaltung

Key Vault-Verweis

Parallele Geheimnisauflösung

Key Vault-Geheimnisaktualisierung

Schnappschuss

Neustart-Versuch

Georeplikation

Nächste Schritte

Feedback

Zusätzliche Ressourcen