Конфигурация приложений Azure

Azure App Configuration är en hanterad tjänst som hjälper utvecklare att centralisera sina program- och funktionsinställningar enkelt och säkert.

Nyckellänkar:

Välj rätt paket

Använd @azure/app-configuration (det här biblioteket) för att:

Hantera konfigurationsinställningar och ögonblicksbilder i Конфигурация
Utför detaljerade läsningar som fungerar utanför området för normal konfigurationsförbrukning

De flesta program bör börja med @azure/app-configuration-provider-biblioteket , som bygger på det här klientbiblioteket på låg nivå och är det rekommenderade sättet att använda konfigurationen vid körning. Den har tillagt följande:

Flexibla åtkomstmönster med hjälp av konfiguration som en nyckel/värde-karta eller ett strukturerat JSON-objekt
Frågemekanism för att deklarativt skapa appkonfiguration
Konfigurationsuppdatering under körning
Hög tillförlitlighet med cachelagring, replikidentifiering, redundans och belastningsutjämning
Referensupplösning för nyckelvalv och automatisk uppdatering
Integrering av funktionsflagga för bibliotek för @microsoft/funktionshantering

Mer information finns i Översikt över konfigurationsleverantör.

Komma igång

Installera paketet

npm install @azure/app-configuration

Not: För program som bara behöver läsa konfigurationsvärden föreslår vi att du använder biblioteket @azure/app-configuration-provider i stället.

Miljöer som stöds för närvarande

LTS-versioner av Node.js
De senaste versionerna av Safari, Chrome, Edge och Firefox.

Mer information finns i vår supportprincip.

Förutsättningar

En Azure-prenumeration
En appkonfiguration resurs

Skapa en appkonfigurationsresurs

Du kan använda Azure Portal eller Azure CLI- för att skapa en Azure App Configuration-resurs.

Exempel (Azure CLI):

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

Autentisera klienten

AppConfigurationClient kan autentisera med hjälp av ett tjänstens huvudnamn eller med hjälp av en anslutningssträng.

Autentisera med tjänstens huvudnamn

Autentisering via tjänstens huvudnamn utförs av:

Skapa en autentiseringsuppgift med hjälp av @azure/identity-paketet.
Ange lämpliga RBAC-regler för din AppConfiguration-resurs. Mer information om appkonfigurationsroller finns här.

Använda StandardAzureCredential

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

Mer information om @azure/identity finns här

Nationella moln

Om du vill autentisera med en resurs i ett nationellt moln måste du ange alternativen i audienceAppConfigurationClient konstruktorn.

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

audience När egenskapen inte har definierats kommer SDK:n som standard att vara Azure Public Cloud.

Autentisera med en anslutningssträng

Om du vill hämta den primära anslutningssträngen för en appkonfigurationsresurs kan du använda det här Azure CLI-kommandot:

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

Och i kod kan du nu skapa appkonfigurationsklienten med anslutningssträngen du fick från Azure CLI:

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

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

Viktiga begrepp

AppConfigurationClient har vissa terminologiändringar från App Configuration i portalen.

Nyckel/värde-par representeras som ConfigurationSetting objekt
Låsning och upplåsning av en inställning visas i fältet isReadOnly, som du kan växla med hjälp av setReadOnly.
Ögonblicksbilder representeras som ConfigurationSnapshot objekt.

Klienten följer en enkel designmetod – ConfigurationSetting kan skickas till valfri metod som tar en ConfigurationSettingParam eller ConfigurationSettingId.

Det innebär att det här mönstret fungerar:

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

eller, till exempel, återskapa en inställning:

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

Den 2022-11-01-preview API-versionen stöder konfigurationsögonblicksbilder: oföränderliga kopior av ett konfigurationsarkiv. Ögonblicksbilder kan skapas med filter som avgör vilka nyckel/värde-par som finns i ögonblicksbilden, vilket skapar en oföränderlig, sammansatt vy över konfigurationsarkivet. Den här funktionen gör det möjligt för program att ha en konsekvent vy över konfigurationen, vilket säkerställer att det inte finns några versionsmatchningar för enskilda inställningar på grund av läsning när uppdateringar gjordes. Den här funktionen kan till exempel användas för att skapa "ögonblicksbilder av versionskonfiguration" i en appkonfiguration. Se avsnittet skapa och hämta en ögonblicksbild i exemplet nedan.

Exempel

Not: Om ditt program bara behöver hämta konfigurationsvärden och inte kräver att du utför åtgärder för att skapa, uppdatera eller ta bort konfigurationsinställningar bör du överväga att använda biblioteket @azure/app-configuration-provider i stället. Providerbiblioteket erbjuder en förenklad upplevelse för att läsa in konfigurationsdata vid körning och ytterligare funktioner. Du hittar många kodexempel i Конфигурация приложений

Skapa och hämta en inställning

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

Skapa en ögonblicksbild

beginCreateSnapshot ger dig den poller som du kan söka efter när ögonblicksbilden skapas.

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

Du kan också använda beginCreateSnapshotAndWait för att få resultatet av skapandet direkt när avsökningen är klar.

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

Hämta en ögonblicksbild

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

Visa en lista över `ConfigurationSetting` i ögonblicksbilden

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

Visa en lista över alla ögonblicksbilder från tjänsten

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

Återställa och arkivera ögonblicksbilden

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

Felsökning

Skogsavverkning

Aktivering av loggning kan hjälpa dig att hitta användbar information om fel. Om du vill se en logg med HTTP-begäranden och svar anger du AZURE_LOG_LEVEL miljövariabeln till info. Du kan också aktivera loggning vid körning genom att anropa setLogLevel i @azure/logger:

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

setLogLevel("info");

Mer detaljerade anvisningar om hur du aktiverar loggar finns i @azure/logger-paketdokumenten.

React Native-stöd

React Native stöder inte vissa JavaScript-API:er som används av det här SDK-biblioteket, så du måste tillhandahålla polyfiller för dem. Mer information finns i vårt React Native-exempel med Expo.

Nästa steg

Följande exempel visar de olika sätt som du kan interagera med App Configuration på:

helloworld.ts – Hämta, ange och ta bort konfigurationsvärden.
helloworldWithLabels.ts – Använd etiketter för att lägga till ytterligare dimensioner i inställningarna för scenarier som beta jämfört med produktion.
optimisticConcurrencyViaEtag.ts – Ange värden med hjälp av etags för att förhindra oavsiktliga överskrivningar.
setReadOnlySample.ts – Markera inställningar som skrivskyddade för att förhindra ändringar.
getSettingOnlyIfChanged.ts – Hämta endast en inställning om den ändrades från senaste gången du fick den.
listRevisions.ts – Visa en lista över revideringar av en nyckel så att du kan se tidigare värden och när de har angetts.
secretReference.ts – SecretReference representerar en konfigurationsinställning som refererar till som KeyVault-hemlighet.
snapshot.ts – Skapa, lista konfigurationsinställningar och arkivera ögonblicksbilder.
featureFlag.ts – Funktionsflaggor är inställningar som följer ett specifikt JSON-schema för värdet.

Mer djupgående exempel finns i exempel mapp på GitHub.

Bidragande

Om du vill bidra till det här biblioteket kan du läsa bidragsguide för att lära dig mer om hur du skapar och testar koden.

Den här modulens tester är en blandning av live- och enhetstester, som kräver att du har en Azure App Configuration-instans. Om du vill köra testerna måste du köra:

pnpm install
pnpm build --filter @azure/app-configuration...
Skapa en .env-fil med följande innehåll i mappen sdk\appconfiguration\app-configuration: APPCONFIG_CONNECTION_STRING=connection string for your App Configuration instance
cd sdk\appconfiguration\app-configuration
npm run test.

Mer information finns i vår tester mapp.

Feedback

Var den här sidan till hjälp?

Last updated on 2025-11-13