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 bietet zusätzliche Funktionen zum Azure SDK für JavaScript.

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

Sie verwenden die DefaultAzureCredential für die Authentifizierung beim App Configuration-Speicher. Befolgen Sie die Anweisungen, um Ihre Anmeldeinformationen der 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 settings = await load(endpoint, credential);
    console.log('settings.get("message"):', settings.get("message"));
}

run();

Verbindungszeichenfolge

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

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

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

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

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.

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

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

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

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

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 settings = 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
settings.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) => {
    settings.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 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();

Aktualisieren bei einem Sentinelschlüssel (Legacy)

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

Hinweis

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

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.

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

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