Klientbibliotek för App Configuration för JavaScript

Artikel
11/06/2024

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

Använd klientbiblioteket för App Configuration för att:

Skapa flexibla nyckelrepresentationer och mappningar
Tagga nycklar med etiketter
Spela upp inställningar från valfri tidpunkt
Hantera ögonblicksbilder av en apps konfiguration

Nyckellänkar:

Komma igång

Installera paketet

npm install @azure/app-configuration

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

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

Mer information om @azure/identity finns här

Nationella moln

Om du vill autentisera med en resurs i ett Nationellt molnmåste du ange authorityHost i autentiseringsalternativen eller via miljövariabeln AZURE_AUTHORITY_HOST.

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

Mer information om @azure/identity finns här

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:

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

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:

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:

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

Skapa och hämta en inställning

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

Skapa en ögonblicksbild

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

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

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

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

Hämta en ögonblicksbild

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

Visa en lista över `ConfigurationSetting` i ögonblicksbilden

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

const snapshots = await client.listSnapshots();

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

Återställa och arkivera ögonblicksbilden

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

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

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

visningar

Dela via

Klientbibliotek för App Configuration för JavaScript

Komma igång

Installera paketet

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

Förutsättningar

Skapa en appkonfigurationsresurs

Autentisera klienten

Autentisera med tjänstens huvudnamn

Nationella moln

Autentisera med en anslutningssträng

Viktiga begrepp

Exempel

Skapa och hämta en inställning

Skapa en ögonblicksbild

Hämta en ögonblicksbild

Visa en lista över `ConfigurationSetting` i ögonblicksbilden

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

Återställa och arkivera ögonblicksbilden

Felsökning

Skogsavverkning

React Native-stöd

Nästa steg

Bidragande

Ytterligare resurser

Dela via

Klientbibliotek för App Configuration för JavaScript

Komma igång

Installera paketet

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

Förutsättningar

Skapa en appkonfigurationsresurs

Autentisera klienten

Autentisera med tjänstens huvudnamn

Nationella moln

Autentisera med en anslutningssträng

Viktiga begrepp

Exempel

Skapa och hämta en inställning

Skapa en ögonblicksbild

Hämta en ögonblicksbild

Visa en lista över ConfigurationSetting i ögonblicksbilden

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

Återställa och arkivera ögonblicksbilden

Felsökning

Skogsavverkning

React Native-stöd

Nästa steg

Bidragande

Relaterade projekt

Ytterligare resurser

Visa en lista över `ConfigurationSetting` i ögonblicksbilden