App-Konfigurationsclientbibliothek für JavaScript

Artikel
07/17/2024

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

Verwenden Sie die Clientbibliothek für die App-Konfiguration, um:

Erstellen flexibler Schlüsseldarstellungen und -zuordnungen
Tagschlüssel mit Beschriftungen
Wiedergabeeinstellungen von einem beliebigen Zeitpunkt an
Verwalten von Momentaufnahmen der App-Konfiguration

Wichtige Links:

Erste Schritte

Installieren des Pakets

npm install @azure/app-configuration

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-

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 zu @azure/identity finden Sie hier

Souveräne Clouds

Um sich bei einer Ressource in einer Sovereign Cloudzu authentifizieren, müssen Sie die authorityHost in den Anmeldeinformationsoptionen oder über die AZURE_AUTHORITY_HOST Umgebungsvariable 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 zu @azure/identity finden Sie hier

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:

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

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:

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:

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

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

  const 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

beginCreateSnapshot gibt Ihnen den Abrufer, um die Momentaufnahmeerstellung abzufragen.

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 beginCreateSnapshotAndWait verwenden, um das Ergebnis der Erstellung direkt nach Abschluss der Abstimmung zu erhalten.

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

Abrufen einer Momentaufnahme

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

Auflisten der `ConfigurationSetting` in der Momentaufnahme

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

const snapshots = await client.listSnapshots();

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

Wiederherstellen und Archivieren der Momentaufnahme

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

const { setLogLevel } = require("@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:

rush update
rush build -t @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.

Aufrufe

Freigeben über

App-Konfigurationsclientbibliothek für JavaScript

Erste Schritte

Installieren des Pakets

Derzeit unterstützte Umgebungen

Voraussetzungen

Erstellen einer App-Konfigurationsressource

Authentifizieren des Clients

Authentifizieren mit einem Dienstprinzipal

Souveräne Clouds

Authentifizieren mit einer Verbindungszeichenfolge

Schlüsselkonzepte

Beispiele

Erstellen und Abrufen einer Einstellung

Erstellen einer Momentaufnahme

Abrufen einer Momentaufnahme

Auflisten der `ConfigurationSetting` in der Momentaufnahme

Auflisten aller Momentaufnahmen aus dem Dienst

Wiederherstellen und Archivieren der Momentaufnahme

Fehlerbehebung

Protokollierung

React Native-Unterstützung

Nächste Schritte

Beitragend

Zusätzliche Ressourcen

Freigeben über

App-Konfigurationsclientbibliothek für JavaScript

Erste Schritte

Installieren des Pakets

Derzeit unterstützte Umgebungen

Voraussetzungen

Erstellen einer App-Konfigurationsressource

Authentifizieren des Clients

Authentifizieren mit einem Dienstprinzipal

Souveräne Clouds

Authentifizieren mit einer Verbindungszeichenfolge

Schlüsselkonzepte

Beispiele

Erstellen und Abrufen einer Einstellung

Erstellen einer Momentaufnahme

Abrufen einer Momentaufnahme

Auflisten der ConfigurationSetting in der Momentaufnahme

Auflisten aller Momentaufnahmen aus dem Dienst

Wiederherstellen und Archivieren der Momentaufnahme

Fehlerbehebung

Protokollierung

React Native-Unterstützung

Nächste Schritte

Beitragend

Verwandte Projekte

Zusätzliche Ressourcen

Auflisten der `ConfigurationSetting` in der Momentaufnahme