Azure App Configuration-Clientbibliothek für JavaScript – Version 1.10.0

Azure App Configuration ist ein verwalteter Dienst, der Entwicklern hilft, ihre Anwendungs- und Featureeinstellungen einfach und sicher zu zentralisieren.

Wichtige Links:

Wählen Sie das richtige Paket

Verwenden Sie @azure/app-configuration (diese Bibliothek) für Folgendes:

Verwalten von Konfigurationseinstellungen und Momentaufnahmen in Azure App Configuration
Granulare Lesevorgänge durchführen, die außerhalb des Bereichs der normalen Konfigurationsnutzung liegen

Die meisten Anwendungen sollten mit der Bibliothek @azure/app-configuration-provider beginnen, die auf dieser Clientbibliothek auf niedriger Ebene aufbaut und die empfohlene Methode zum Nutzen der Konfiguration zur Laufzeit darstellt. Er fügt hinzu:

Flexible Zugriffsmuster durch Konfiguration als Schlüssel-Wert-Map oder strukturiertes JSON-Objekt
Abfragemechanismus zum deklarativen Erstellen der App-Konfiguration
Aktualisierung der Konfiguration während der Laufzeit
Hohe Zuverlässigkeit durch Caching, Replikaterkennung, Failover und Lastausgleich
Auflösung und automatische Aktualisierung von Schlüsseltresorverweisen
Integration von Feature-Flags für @microsoft-/Feature-Management-Bibliothek

Weitere Informationen finden Sie in der Übersicht des Konfigurationsanbieters.

Erste Schritte

Installieren des Pakets

npm install @azure/app-configuration

Anmerkung: Für Anwendungen, die nur Konfigurationswerte lesen müssen, empfehlen wir, stattdessen die Bibliothek @azure/app-configuration-provider zu verwenden.

Derzeit unterstützte Umgebungen

LTS-Versionen von Node.js
Neueste Versionen von Safari, Chrome, Edge und Firefox.

Weitere Informationen finden Sie in unserer Supportrichtlinie.

Voraussetzungen

Ein Azure-Abonnement
Eine App-Konfiguration Ressource

Erstellen einer App-Konfigurationsressource

Sie können das Azure Portal oder die Azure CLI verwenden, um eine Azure App-Konfigurationsressource zu erstellen.

Beispiel (Azure CLI):

az appconfig create --name <app-configuration-resource-name> --resource-group <resource-group-name> --location eastus

Authentifizieren des Clients

AppConfigurationClient kann sich mithilfe eines Dienstprinzipals oder mithilfe einer Verbindungszeichenfolgeauthentifizieren.

Authentifizieren mit einem Dienstprinzipal

Die Authentifizierung über den Dienstprinzipal erfolgt durch:

Erstellen einer Anmeldeinformation mithilfe des @azure/identity-Pakets.
Festlegen der entsprechenden RBAC-Regeln für Ihre AppConfiguration-Ressource. Weitere Informationen zu App-Konfigurationsrollen finden Sie hier.

Verwenden DefaultAzureCredential-

import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

Weitere Informationen zu @azure/identity finden Sie hier

Souveräne Clouds

Um sich mit einer Ressource in einer Sovereign Cloud zu authentifizieren, müssen Sie die audience in den AppConfigurationClient Konstruktoroptionen festlegen.

import { AppConfigurationClient, KnownAppConfigAudience } from "@azure/app-configuration";
import { DefaultAzureCredential } from "@azure/identity";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.azure.cn";
// Create an AppConfigurationClient that will authenticate through AAD in the China cloud
const client = new AppConfigurationClient(endpoint, new DefaultAzureCredential(), {
  audience: KnownAppConfigAudience.AzureChina,
});

Hinweis: Wenn audience die Eigenschaft nicht definiert ist, wird das SDK standardmäßig auf Azure Public Cloud gesetzt.

Authentifizieren mit einer Verbindungszeichenfolge

Um die primäre Verbindungszeichenfolge für eine App-Konfigurationsressource abzurufen, können Sie diesen Azure CLI-Befehl verwenden:

az appconfig credential list -g <resource-group-name> -n <app-configuration-resource-name> --query "([?name=='Primary'].connectionString)[0]"

Und im Code können Sie jetzt Ihren App-Konfigurationsclient mit der Verbindungszeichenfolge erstellen, Sie von der Azure CLI erhalten haben:

import { AppConfigurationClient } from "@azure/app-configuration";

const connectionString = "Endpoint=https://example.azconfig.io;XXX=YYYY;YYY=ZZZZ";
const client = new AppConfigurationClient(connectionString);

Schlüsselkonzepte

Die AppConfigurationClient hat einige Terminologieänderungen von der App-Konfiguration im Portal.

Schlüssel-/Wert-Paare werden als ConfigurationSetting Objekte dargestellt.
Das Sperren und Entsperren einer Einstellung wird im feld isReadOnly dargestellt, das Sie mit setReadOnlyumschalten können.
Momentaufnahmen werden als ConfigurationSnapshot Objekte dargestellt.

Der Kunde folgt einer einfachen Entwurfsmethodik – ConfigurationSetting kann an jede Methode übergeben werden, die eine ConfigurationSettingParam oder ConfigurationSettingIdakzeptiert.

Dies bedeutet, dass dieses Muster funktioniert:

import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

const setting = await client.getConfigurationSetting({
  key: "hello",
});

setting.value = "new value!";
await client.setConfigurationSetting(setting);

// fields unrelated to just identifying the setting are simply
// ignored (for instance, the `value` field)
await client.setReadOnly(setting, true);

// delete just needs to identify the setting so other fields are
// just ignored
await client.deleteConfigurationSetting(setting);

oder beispielsweise das erneute Abrufen einer Einstellung:

import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

let setting = await client.getConfigurationSetting({
  key: "hello",
});

// re-get the setting
setting = await client.getConfigurationSetting(setting);

Die 2022-11-01-preview-API-Version unterstützt Konfigurationsmomentaufnahmen: unveränderliche, Punkt-in-Time-Kopien eines Konfigurationsspeichers. Momentaufnahmen können mit Filtern erstellt werden, die bestimmen, welche Schlüsselwertpaare in der Momentaufnahme enthalten sind, wodurch eine unveränderliche, zusammengesetzte Ansicht des Konfigurationsspeichers erstellt wird. Dieses Feature ermöglicht Es Anwendungen, eine konsistente Ansicht der Konfiguration zu halten, um sicherzustellen, dass aufgrund des Lesens keine Versionskonflikte zu einzelnen Einstellungen vorhanden sind, da Updates vorgenommen wurden. Dieses Feature kann beispielsweise verwendet werden, um "Releasekonfigurationsmomentaufnahmen" in einer App-Konfiguration zu erstellen. Weitere Informationen finden Sie Erstellen und Abrufen einer Momentaufnahme Abschnitts im folgenden Beispiel.

Beispiele

Anmerkung: Wenn Ihre Anwendung nur Konfigurationswerte abrufen muss und keine Erstellungs-, Aktualisierungs- oder Löschvorgänge für Konfigurationseinstellungen ausführen muss, sollten Sie stattdessen die Bibliothek @azure/app-configuration-provider verwenden. Die Anbieterbibliothek bietet eine vereinfachte Benutzeroberfläche für das Laden von Konfigurationsdaten zur Laufzeit und zusätzliche Features. Viele Codebeispiele finden Sie in der Azure App Configuration-Dokumentation auf Microsoft Learn.

Erstellen und Abrufen einer Einstellung

import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

await client.setConfigurationSetting({
  key: "testkey",
  value: "testvalue",
  // Labels allow you to create variants of a key tailored
  // for specific use-cases like supporting multiple environments.
  // https://learn.microsoft.com/azure/azure-app-configuration/concept-key-value#label-keys
  label: "optional-label",
});

const retrievedSetting = await client.getConfigurationSetting({
  key: "testkey",
  label: "optional-label",
});

console.log("Retrieved value:", retrievedSetting.value);

Erstellen einer Momentaufnahme

beginCreateSnapshot gibt Ihnen den Abrufer, um die Momentaufnahmeerstellung abzufragen.

import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

const key = "testkey";
const value = "testvalue";
const label = "optional-label";

await client.addConfigurationSetting({
  key,
  value,
  label,
});

const poller = await client.beginCreateSnapshot({
  name: "testsnapshot",
  retentionPeriod: 2592000,
  filters: [{ keyFilter: key, labelFilter: label }],
});
const snapshot = await poller.pollUntilDone();

Sie können auch beginCreateSnapshotAndWait verwenden, um das Ergebnis der Erstellung direkt nach Abschluss der Abstimmung zu erhalten.

import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

const key = "testkey";
const value = "testvalue";
const label = "optional-label";

const snapshot = await client.beginCreateSnapshotAndWait({
  name: "testsnapshot",
  retentionPeriod: 2592000,
  filters: [{ keyFilter: key, labelFilter: label }],
});

Abrufen einer Momentaufnahme

import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

const retrievedSnapshot = await client.getSnapshot("testsnapshot");
console.log("Retrieved snapshot:", retrievedSnapshot);

Auflisten der `ConfigurationSetting` in der Momentaufnahme

import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

const retrievedSnapshotSettings = await client.listConfigurationSettingsForSnapshot("testsnapshot");

for await (const setting of retrievedSnapshotSettings) {
  console.log(`Found key: ${setting.key}, label: ${setting.label}`);
}

Auflisten aller Momentaufnahmen aus dem Dienst

import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

const snapshots = await client.listSnapshots();

for await (const snapshot of snapshots) {
  console.log(`Found snapshot: ${snapshot.name}`);
}

Wiederherstellen und Archivieren der Momentaufnahme

import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

// Snapshot is in ready status
const archivedSnapshot = await client.archiveSnapshot("testsnapshot");
console.log("Snapshot updated status is:", archivedSnapshot.status);

// Snapshot is in archive status
const recoverSnapshot = await client.recoverSnapshot("testsnapshot");
console.log("Snapshot updated status is:", recoverSnapshot.status);

Fehlerbehebung

Protokollierung

Das Aktivieren der Protokollierung kann hilfreiche Informationen zu Fehlern aufdecken. Um ein Protokoll von HTTP-Anforderungen und -Antworten anzuzeigen, legen Sie die AZURE_LOG_LEVEL Umgebungsvariable auf infofest. Alternativ kann die Protokollierung zur Laufzeit durch Aufrufen von setLogLevel im @azure/loggeraktiviert werden:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Ausführlichere Anweisungen zum Aktivieren von Protokollen finden Sie in den @azure/Logger-Paketdokumenten.

React Native-Unterstützung

React Native unterstützt keine JavaScript-API, die von dieser SDK-Bibliothek verwendet wird, sodass Sie Polyfills für sie bereitstellen müssen. Weitere Details finden Sie in unserem React Native-Beispiel mit Expo.

Nächste Schritte

Die folgenden Beispiele zeigen Ihnen die verschiedenen Möglichkeiten, mit der App-Konfiguration zu interagieren:

helloworld.ts – Abrufen, Festlegen und Löschen von Konfigurationswerten.
helloworldWithLabels.ts – Verwenden Sie Bezeichnungen, um Ihren Einstellungen zusätzliche Dimensionen für Szenarien wie Beta oder Produktion hinzuzufügen.
optimisticConcurrencyViaEtag.ts – Legen Sie Werte mithilfe von Etags fest, um versehentliche Überschreibungen zu verhindern.
setReadOnlySample.ts – Markieren von Einstellungen als schreibgeschützt, um Änderungen zu verhindern.
getSettingOnlyIfChanged.ts – Rufen Sie eine Einstellung nur ab, wenn sie von der letzten Zeit geändert wurde, die Sie erhalten haben.
listRevisions.ts – Listet die Überarbeitungen eines Schlüssels auf, sodass Sie frühere Werte und wann sie festgelegt wurden, anzeigen können.
secretReference.ts – SecretReference stellt eine Konfigurationseinstellung dar, die als Schlüsselschlüsselschlüssel verweist.
snapshot.ts – Erstellen, Listenkonfigurationseinstellungen und Archivmomentaufnahmen.
featureFlag.ts – Featurekennzeichnungen sind Einstellungen, die einem bestimmten JSON-Schema für den Wert folgen.

Weitere ausführliche Beispiele finden Sie in den Beispielen Ordners auf GitHub.

Beitragend

Wenn Sie an dieser Bibliothek mitwirken möchten, lesen Sie bitte den mitwirkenden Leitfaden, um mehr über das Erstellen und Testen des Codes zu erfahren.

Die Tests dieses Moduls sind eine Mischung aus Live- und Komponententests, die erfordern, dass Sie über eine Azure App-Konfigurationsinstanz verfügen. Um die Tests auszuführen, müssen Sie Folgendes ausführen:

pnpm install
pnpm build --filter @azure/app-configuration...
Erstellen Sie eine env-Datei mit diesen Inhalten im ordner sdk\appconfiguration\app-configuration: APPCONFIG_CONNECTION_STRING=connection string for your App Configuration instance
cd sdk\appconfiguration\app-configuration
npm run test.

Sehen Sie sich unsere Tests Ordner an, um weitere Details zu erhalten.

Feedback

War diese Seite hilfreich?

Last updated on 2025-11-13