Azure App Configuration-clientbibliotheek voor JavaScript - versie 1.10.0

Azure App Configuration is een beheerde service waarmee ontwikkelaars hun toepassings- en functie-instellingen eenvoudig en veilig kunnen centraliseren.

Sleutelkoppelingen:

Kies het juiste pakket

Gebruik @azure/app-configuratie (deze bibliotheek) om het volgende te doen:

Configuratie-instellingen en momentopnamen beheren in Azure App Configuration
Voer gedetailleerde leesbewerkingen uit die buiten het bereik van het normale configuratieverbruik vallen

De meeste toepassingen moeten beginnen met de bibliotheek @azure/app-configuration-provider , die voortbouwt op deze clientbibliotheek op laag niveau en de aanbevolen manier is om configuratie tijdens runtime te gebruiken. Het voegt eraan toe:

Flexibele toegangspatronen met behulp van configuratie als een sleutel-/waardetoewijzing of een gestructureerd JSON-object
Querymechanisme voor het declaratief samenstellen van app-configuratie
Configuratie vernieuwen tijdens runtime
Hoge betrouwbaarheid met caching, replicadetectie, failover en taakverdeling
Referentieresolutie en automatisch vernieuwen van de sleutelkluis
Integratie van functievlaggen voor @microsoft-/functiebeheerbibliotheek

Ga voor meer informatie naar het overzicht van de configuratieprovider.

Slag

Het pakket installeren

npm install @azure/app-configuration

Notitie: Voor toepassingen die alleen configuratiewaarden hoeven te lezen, raden we u aan in plaats daarvan de bibliotheek @azure/app-configuration-provider te gebruiken.

Momenteel ondersteunde omgevingen

LTS-versies van Node.js
Nieuwste versies van Safari, Chrome, Edge en Firefox.

Zie ons ondersteuningsbeleid voor meer informatie.

Voorwaarden

Een Azure-abonnement
Een App Configuration--resource

Een App Configuration-resource maken

U kunt de Azure Portal of de Azure CLI- gebruiken om een Azure App Configuration-resource te maken.

Voorbeeld (Azure CLI):

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

De client verifiëren

AppConfigurationClient kan worden geverifieerd met behulp van een service-principal of met behulp van een verbindingsreeks.

Verifiëren met een service-principal

Verificatie via service-principal wordt uitgevoerd door:

Een referentie maken met behulp van het @azure/identity-pakket.
De juiste RBAC-regels instellen voor uw AppConfiguration-resource. Meer informatie over App Configuration-rollen vindt u hier .

DefaultAzureCredential- gebruiken

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

Meer informatie over @azure/identity vindt u hier

Onafhankelijke clouds

Als u wilt verifiëren met een resource in een onafhankelijke cloud, moet u de opties in de audienceAppConfigurationClient constructor instellen.

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

Opmerking: Wanneer audience de eigenschap niet is gedefinieerd, wordt de SDK standaard ingesteld op Azure Public Cloud.

Verifiëren met een verbindingsreeks

Als u de primaire verbindingsreeks wilt ophalen voor een App Configuration-resource, kunt u deze Azure CLI-opdracht gebruiken:

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

En in code kunt u nu uw App Configuration-client maken met de verbindingsreeks u hebt verkregen vanuit de Azure CLI:

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

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

Sleutelbegrippen

De AppConfigurationClient heeft enkele terminologiewijzigingen ten laste van App Configuration in de portal.

Sleutel-/waardeparen worden weergegeven als ConfigurationSetting objecten
Het vergrendelen en ontgrendelen van een instelling wordt weergegeven in het isReadOnly veld, dat u kunt in- en uitschakelen met behulp van setReadOnly.
Momentopnamen worden weergegeven als ConfigurationSnapshot objecten.

De klant volgt een eenvoudige ontwerpmethodologie: ConfigurationSetting kan worden doorgegeven aan elke methode die een ConfigurationSettingParam of ConfigurationSettingIdgebruikt.

Dit betekent dat dit patroon werkt:

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

of bijvoorbeeld het opnieuw ophalen van een instelling:

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

De 2022-11-01-preview API-versie ondersteunt configuratiemomentopnamen: onveranderbare, point-in-time kopieën van een configuratiearchief. Momentopnamen kunnen worden gemaakt met filters die bepalen welke sleutel-waardeparen zich in de momentopname bevinden, waardoor een onveranderbare, samengestelde weergave van het configuratiearchief wordt gemaakt. Met deze functie kunnen toepassingen een consistente weergave van de configuratie houden, zodat er geen versies overeenkomen met afzonderlijke instellingen vanwege het lezen wanneer er updates zijn uitgevoerd. Deze functie kan bijvoorbeeld worden gebruikt om 'momentopnamen van releaseconfiguratie' te maken in een App Configuration. Zie de sectie maken en een momentopname maken in het onderstaande voorbeeld.

Voorbeelden

Notitie: Als uw toepassing alleen configuratiewaarden hoeft op te halen en geen bewerkingen voor het maken, bijwerken of verwijderen van configuratie-instellingen vereist, kunt u overwegen in plaats daarvan de bibliotheek @azure/app-configuration-provider te gebruiken. De providerbibliotheek biedt een vereenvoudigde ervaring voor het laden van configuratiegegevens tijdens runtime en extra functies. U kunt veel codevoorbeelden vinden in de documentatie over Azure App Configuration op Microsoft Learn.

Een instelling maken en ophalen

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

Een momentopname maken

beginCreateSnapshot geeft u de poller om te peilen naar het maken van de momentopname.

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

U kunt ook beginCreateSnapshotAndWait gebruiken om het resultaat van het maken direct nadat de polling is voltooid.

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

Een momentopname ophalen

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

De `ConfigurationSetting` weergeven in de momentopname

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

Alle momentopnamen van de service weergeven

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

De momentopname herstellen en archiveren

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

Probleemoplossing

Logboekregistratie

Het inschakelen van logboekregistratie kan helpen nuttige informatie over fouten te ontdekken. Als u een logboek met HTTP-aanvragen en -antwoorden wilt zien, stelt u de omgevingsvariabele AZURE_LOG_LEVEL in op info. U kunt logboekregistratie ook tijdens runtime inschakelen door setLogLevel aan te roepen in de @azure/logger:

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

setLogLevel("info");

Voor meer gedetailleerde instructies over het inschakelen van logboeken, kunt u de @azure/logger pakketdocumentenbekijken.

React Native-ondersteuning

React Native biedt geen ondersteuning voor sommige JavaScript-API's die door deze SDK-bibliotheek worden gebruikt, dus u moet polyfills voor deze api's opgeven. Zie ons React Native-voorbeeld met Expo voor meer informatie.

Volgende stappen

In de volgende voorbeelden ziet u de verschillende manieren waarop u met App Configuration kunt werken:

helloworld.ts: configuratiewaarden ophalen, instellen en verwijderen.
helloworldWithLabels.ts: gebruik labels om extra dimensies toe te voegen aan uw instellingen voor scenario's zoals bèta versus productie.
optimisticConcurrencyViaEtag.ts : stel waarden in met behulp van etags om onbedoelde overschrijven te voorkomen.
setReadOnlySample.ts: instellingen markeren als alleen-lezen om wijziging te voorkomen.
getSettingOnlyIfChanged.ts- Haal een instelling alleen op als deze is gewijzigd van de laatste keer dat u deze hebt gekregen.
listRevisions.ts: de revisies van een sleutel weergeven, zodat u eerdere waarden en wanneer ze zijn ingesteld, kunt zien.
secretReference.ts - SecretReference vertegenwoordigt een configuratie-instelling die verwijst naar KeyVault-geheim.
snapshot.ts: configuratie-instellingen maken, vermelden en momentopnamen archiveren.
featureFlag.ts: functievlagmen zijn instellingen die het specifieke JSON-schema voor de waarde volgen.

Meer uitgebreide voorbeelden vindt u in de voorbeelden map op GitHub.

Bijdragen

Als u een bijdrage wilt leveren aan deze bibliotheek, leest u de gids voor bijdragen voor meer informatie over het bouwen en testen van de code.

De tests van deze module zijn een combinatie van live- en eenheidstests, waarvoor u een Azure App Configuration-exemplaar moet hebben. Als u de tests wilt uitvoeren, moet u het volgende uitvoeren:

pnpm install
pnpm build --filter @azure/app-configuration...
Maak een .env-bestand met deze inhoud in de map sdk\appconfiguration\app-configuration: APPCONFIG_CONNECTION_STRING=connection string for your App Configuration instance
cd sdk\appconfiguration\app-configuration
npm run test.

Bekijk de map tests voor meer informatie.

Feedback

Is deze pagina nuttig?

Last updated on 2025-11-13