Share via

App Configuration Clientbibliothek für JavaScript

  • Artikel

Azure App Configuration ist ein verwalteter Dienst, mit dem Entwickler ihre Anwendungs- und Featureeinstellungen einfach und sicher zentralisieren können.

Verwenden Sie die Clientbibliothek für App Configuration für Folgendes:

  • Erstellen von flexiblen Schlüsseldarstellungen und Zuordnungen
  • Tagschlüssel mit Bezeichnungen
  • Wiedergabeeinstellungen ab einem beliebigen Zeitpunkt
  • Verwalten von Momentaufnahmen der Konfiguration einer App

Wichtige Links:

Erste Schritte

Installieren des Pakets

npm install @azure/app-configuration

Die derzeitig unterstützten Umgebungen

Ausführlichere Informationen finden Sie in der Supportrichtlinie.

Voraussetzungen

Erstellen einer App Configuration Ressource

Sie können das Azure-Portal oder die Azure CLI verwenden, um eine Azure App Configuration-Ressource 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 mit einem Dienstprinzipal oder mit einem Verbindungszeichenfolge authentifizieren.

Authentifizieren anhand eines Dienstprinzipal

Die Authentifizierung über den Dienstprinzipal erfolgt durch:

  • Erstellen von Anmeldeinformationen mithilfe des @azure/identity Pakets.
  • Festlegen geeigneter RBAC-Regeln für Ihre AppConfiguration-Ressource. Weitere Informationen zu App Configuration Rollen finden Sie hier.

Verwenden von DefaultAzureCredential

const azureIdentity = require("@azure/identity");
const appConfig = require("@azure/app-configuration");

const credential = new azureIdentity.DefaultAzureCredential();
const client = new appConfig.AppConfigurationClient(
  endpoint, // ex: <https://<your appconfig resource>.azconfig.io>
  credential
);

Weitere Informationen finden @azure/identity Sie hier.

Sovereign Clouds

Um sich bei einer Ressource in einer Sovereign Cloud zu authentifizieren, müssen Sie die authorityHost in den Anmeldeinformationen oder über die Umgebungsvariable AZURE_AUTHORITY_HOST festlegen.

const { AppConfigurationClient } = require("@azure/app-configuration");
const { DefaultAzureCredential, AzureAuthorityHosts } = require("@azure/identity");

// Create an AppConfigurationClient that will authenticate through AAD in the China cloud
const client = new AppConfigurationClient(
  endpoint, // ex: <https://<your appconfig resource>.azconfig.azure.cn>
  new DefaultAzureCredential({ authorityHost: AzureAuthorityHosts.AzureChina })
);

Weitere Informationen finden @azure/identity Sie hier.

Authentifizieren mit einem Verbindungszeichenfolge

Um den primären Verbindungszeichenfolge für eine App Configuration Ressource abzurufen, können Sie den folgenden Azure CLI-Befehl verwenden:

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

Im Code können Sie jetzt Ihren App Configuration-Client mit dem Verbindungszeichenfolge erstellen, den Sie von der Azure CLI erhalten haben:

const client = new AppConfigurationClient("<connection string>");

Wichtige Begriffe

Es AppConfigurationClient gibt einige Terminologieänderungen gegenüber App Configuration im Portal.

  • Schlüssel-Wert-Paare werden als ConfigurationSetting Objekte dargestellt
  • Das Sperren und Entsperren einer Einstellung wird im Feld dargestellt, das isReadOnly Sie mit umschalten setReadOnlykönnen.
  • Momentaufnahmen werden als ConfigurationSnapshot Objekte dargestellt.

Der Client folgt einer einfachen Entwurfsmethodik: ConfigurationSetting Kann an jede Methode übergeben werden, die ein ConfigurationSettingParam oder ConfigurationSettingIdakzeptiert.

Dies bedeutet, dass dieses Muster funktioniert:

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 z. B. erneut eine Einstellung abrufen:

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 Point-in-Time-Kopien eines Konfigurationsspeichers. Momentaufnahmen können mit Filtern erstellt werden, die bestimmen, welche Schlüssel-Wert-Paare im 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 haben, und stellt sicher, dass keine Versionskonflikte mit einzelnen Einstellungen aufgrund des Lesens vorhanden sind, während Updates vorgenommen wurden. Dieses Feature kann beispielsweise verwendet werden, um "Releasekonfigurationsmomentaufnahmen" innerhalb eines App Configuration zu erstellen. Sehen Sie sich den Abschnitt erstellen und abrufen eines Momentaufnahme im folgenden Beispiel an.

Beispiele

Erstellen und Abrufen einer Einstellung

const appConfig = require("@azure/app-configuration");

const client = new appConfig.AppConfigurationClient(
  "<App Configuration connection string goes here>"
);

async function run() {
  const newSetting = 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.
    // /azure/azure-app-configuration/concept-key-value#label-keys
    label: "optional-label"
  });

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

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

run().catch((err) => console.log("ERROR:", err));

Erstellen einer Momentaufnahme

beginCreateSnapshotgibt Ihnen den Poller zum Abrufen der Momentaufnahme Erstellung.

const { AppConfigurationClient } = require("@azure/app-configuration");

const client = new AppConfigurationClient(
  "<App Configuration connection string goes here>"
);


async function run() {
  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();
}

run().catch((err) => console.log("ERROR:", err));

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

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

Einen Schnappschuss erhalten

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

Auflisten der ConfigurationSetting im Momentaufnahme

let 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

let snapshots = await client.listSnapshots();

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

Wiederherstellen und Archivieren des Momentaufnahme

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

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

Problembehandlung

Protokollierung

Die Aktivierung der Protokollierung kann hilfreiche Informationen über Fehler aufdecken. Um ein Protokoll von HTTP-Anforderungen und -Antworten anzuzeigen, legen Sie die Umgebungsvariable AZURE_LOG_LEVEL auf info fest. Alternativ kann die Protokollierung zur Laufzeit aktiviert werden, indem Sie setLogLevel in @azure/logger aufrufen:

const { setLogLevel } = require("@azure/logger");

setLogLevel("info");

Ausführlichere Anweisungen zum Aktivieren von Protokollen finden Sie in der Paketdokumentation zu @azure/logger.

React Native Support

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

Nächste Schritte

Die folgenden Beispiele zeigen Ihnen die verschiedenen Möglichkeiten, mit App Configuration 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 im Vergleich zur 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 sich seit dem letzten Zeitpunkt geändert hat.
  • listRevisions.ts – Listen Sie die Überarbeitungen eines Schlüssels auf, sodass Sie frühere Werte anzeigen können und wann sie festgelegt wurden.
  • secretReference.ts – SecretReference stellt eine Konfigurationseinstellung dar, die als KeyVault-Geheimnis verweist.
  • snapshot.ts – Erstellen, Auflisten von Konfigurationseinstellungen und Archivieren von Momentaufnahmen.
  • featureFlag.ts – Featureflags sind Einstellungen, die einem bestimmten JSON-Schema für den Wert folgen.

Ausführlichere Beispiele finden Sie im Ordner samples auf GitHub.

Mitwirken

Wenn Sie an dieser Bibliothek mitwirken möchten, lesen Sie die Anleitung für Mitwirkende, um mehr darüber zu erfahren, wie Sie den Code erstellen und testen können.

Die Tests dieses Moduls sind eine Mischung aus Live- und Komponententests, für die Sie eine Azure App Configuration instance erfordern. Zum Ausführen der Tests müssen Sie Folgendes ausführen:

  1. rush update
  2. rush build -t @azure/app-configuration
  3. Erstellen Sie eine ENV-Datei mit den folgenden Inhalten im sdk\appconfiguration\app-configuration Ordner: APPCONFIG_CONNECTION_STRING=connection string for your App Configuration instance
  4. cd sdk\appconfiguration\app-configuration
  5. npm run test.

Weitere Informationen finden Sie in unserem Testordner .

Aufrufe