Azure App Configuration JavaScripthez készült ügyféloldali kódtár – 1.10.0-s verzió

Azure App Configuration egy felügyelt szolgáltatás, amely segít a fejlesztőknek egyszerűen és biztonságosan központosítani az alkalmazás- és szolgáltatásbeállításokat.

Főbb hivatkozások:

Válassza ki a megfelelő csomagot

A @azure/app-configuration (ez a könyvtár) a következőkre használható:

Konfigurációs beállítások és pillanatképek kezelése a Azure App Configuration
Részletes olvasások végrehajtása, amelyek a normál konfigurációs felhasználás tartományán kívül működnek

A legtöbb alkalmazásnak a @azure/app-configuration-provider kódtárral kell kezdődnie, amely erre az alacsony szintű ügyféloldali kódtárra épül, és a konfiguráció futásidőben történő felhasználásának ajánlott módja. Hozzáteszi:

Rugalmas hozzáférési minták kulcs/érték leképezésként vagy strukturált JSON-objektumként való konfigurációval
Lekérdezési mechanizmus az alkalmazáskonfiguráció deklaratív összeállításához
Konfiguráció frissítése futásidőben
Nagy megbízhatóság a gyorsítótárazással, a replikafelderítéssel, a feladatátvétellel és a terheléselosztással
Key Vault referenciafeloldás és automatikus frissítés
Funkciójelölő integrációja a @microsoft/funkciókezelési kódtárhoz

További információért tekintse meg a konfigurációszolgáltató áttekintését.

Kezdetekhez

A csomag telepítése

npm install @azure/app-configuration

Jegyzet: Olyan alkalmazások esetében, amelyeknek csak a konfigurációs értékeket kell olvasniuk, javasoljuk, hogy inkább a @azure/app-configuration-provider kódtárat használja.

Jelenleg támogatott környezetek

A Node.js LTS-verziói
A Safari, a Chrome, az Edge és a Firefox legújabb verziói.

További részletekért tekintse meg támogatási szabályzatunkat.

Előfeltételek

Egy Azure-előfizetési
alkalmazáskonfigurációs erőforrás

Alkalmazáskonfigurációs erőforrás létrehozása

Azure-alkalmazáskonfigurációs erőforrás létrehozásához használhatja az Azure Portal vagy a Azure CLI-.

Példa (Azure CLI):

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

Az ügyfél hitelesítése

Az AppConfigurationClient egy szolgáltatásnév- vagy kapcsolati sztringhasználatával végezhet hitelesítést.

Hitelesítés szolgáltatásnévvel

A szolgáltatásnévvel történő hitelesítést a következő végzi:

Hitelesítő adatok létrehozása a @azure/identity csomag használatával.
A megfelelő RBAC-szabályok beállítása az AppConfiguration-erőforráson. Az alkalmazáskonfigurációs szerepkörökről itt talál további információt.

A DefaultAzureCredential használata

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

A @azure/identityitt talál további információt

Szuverén felhők

Ha egy szuverén felhőben lévő erőforrással szeretne hitelesíteni, be kell állítania audience a AppConfigurationClient konstruktor beállításait.

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

Megjegyzés: Ha audience a tulajdonság nincs meghatározva, az SDK alapértelmezés szerint az Azure nyilvános felhőt fogja használni.

Hitelesítés kapcsolati sztringgel

Az alkalmazáskonfigurációs erőforrás elsődleges kapcsolati sztringjének lekéréséhez használja ezt az Azure CLI-parancsot:

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

A kódban most már létrehozhatja az alkalmazáskonfigurációs ügyfelet az Azure CLI-ből kapott kapcsolati sztringgel:

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

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

Főbb fogalmak

A AppConfigurationClient a portál alkalmazáskonfigurációjának néhány terminológiája módosul.

A kulcs/érték párok ConfigurationSetting objektumként jelennek meg
A zárolás és a zárolás feloldása a isReadOnly mezőben jelenik meg, amelyet a setReadOnlyhasználatával válthat.
A pillanatképek ConfigurationSnapshot objektumokként jelennek meg.

Az ügyfél egy egyszerű tervezési módszertant követ – ConfigurationSetting bármely olyan metódusba átadható, amely ConfigurationSettingParam vagy ConfigurationSettingIdvesz igénybe.

Ez azt jelenti, hogy ez a minta működik:

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

vagy például egy beállítás újbóli lekérése:

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

A 2022-11-01-preview API-verzió támogatja a konfigurációs pillanatképeket: a konfigurációs tár nem módosítható, időponthoz kötött másolatai. A pillanatképek olyan szűrőkkel hozhatók létre, amelyek meghatározzák, hogy mely kulcs-érték párok találhatók a pillanatképben, így a konfigurációs tár nem módosítható, álló nézetét hozhatják létre. Ez a funkció lehetővé teszi az alkalmazások számára, hogy konzisztens konfigurációs nézetet tartsanak fenn, biztosítva, hogy a frissítések olvasása miatt az egyes beállítások verzióbeli eltérései ne legyenek eltérnek. Ezzel a funkcióval például létrehozhat "kiadási konfigurációs pillanatképeket" egy alkalmazáskonfiguráción belül. Az alábbi példában a pillanatképet szakaszt.

Példák

Jegyzet: Ha az alkalmazásnak csak a konfigurációs értékeket kell lekérnie, és nem igényel létrehozási, frissítési vagy törlési műveleteket a konfigurációs beállításokon, fontolja meg a @azure/app-configuration-provider kódtár használatát. A szolgáltatói kódtár egyszerűsített felhasználói élményt kínál a konfigurációs adatok futásidőben történő betöltéséhez és további funkciókhoz. Számos kódmintát talál a Azure App Configuration dokumentációjában a Microsoft Learn.

Beállítás létrehozása és lekérése

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

Pillanatkép létrehozása

beginCreateSnapshot megadja a lekérdezést a pillanatkép-létrehozáshoz.

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

A beginCreateSnapshotAndWait használatával közvetlenül a lekérdezés befejezése után is létrehozhatja a létrehozás eredményét.

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

Pillanatkép lekérése

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

A pillanatképben szereplő `ConfigurationSetting` listázása

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

A szolgáltatás összes pillanatképének listázása

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

Pillanatkép helyreállítása és archiválása

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

Hibaelhárítás

Fakitermelés

A naplózás engedélyezése segíthet a hibákról szóló hasznos információk feltárásában. A HTTP-kérések és válaszok naplójának megtekintéséhez állítsa a AZURE_LOG_LEVEL környezeti változót info. Másik lehetőségként a naplózás futásidőben is engedélyezhető a setLogLevel meghívásával a @azure/logger:

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

setLogLevel("info");

A naplók engedélyezésére vonatkozó részletesebb útmutatásért tekintse meg a @azure/logger csomag dokumentációit.

A React natív támogatása

A React Native nem támogatja az SDK-kódtár által használt JavaScript API-t, ezért több kitöltést kell biztosítania számukra. További részletekért tekintse meg a React natív mintáját az Expo használatával.

Következő lépések

Az alábbi minták az alkalmazáskonfigurációval való interakció különböző módjait mutatják be:

helloworld.ts – Konfigurációs értékek lekérése, beállítása és törlése.
helloworldWithLabels.ts – Címkék használatával további dimenziókat adhat a beállításokhoz olyan forgatókönyvekhez, mint a bétaverzió és az éles környezet.
optimisticConcurrencyViaEtag.ts – Értékeket állíthat be etagekkel a véletlen felülírások elkerülése érdekében.
setReadOnlySample.ts – A beállítások írásvédettként való megjelölése a módosítás megakadályozása érdekében.
getSettingOnlyIfChanged.ts – Csak akkor kérje le a beállítást, ha az az utolsó alkalommal módosult.
listRevisions.ts – Listázhatja a kulcsok korrektúráit, így megtekintheti a korábbi értékeket és azok beállítását.
secretReference.ts – A SecretReference egy olyan konfigurációs beállítást jelöl, amely KeyVault-titkos kódként hivatkozik.
snapshot.ts – Konfigurációs beállítások és archív pillanatképek létrehozása, listázása.
featureFlag.ts – A funkciójelölők olyan beállítások, amelyek az érték adott JSON-sémáját követik.

Részletesebb példákat a GitHub mintáiban talál.

Hozzájárulás

Ha hozzá szeretne járulni ehhez a kódtárhoz, olvassa el a közreműködői útmutatót, amelyből többet is megtudhat a kód összeállításáról és teszteléséről.

A modul tesztjei élő és egységtesztek keverékei, amelyekhez Azure-alkalmazáskonfigurációs példányra van szükség. A tesztek végrehajtásához futtatnia kell a következőt:

pnpm install
pnpm build --filter @azure/app-configuration...
Hozzon létre egy .env fájlt a következő tartalommal a sdk\appconfiguration\app-configuration mappában: APPCONFIG_CONNECTION_STRING=connection string for your App Configuration instance
cd sdk\appconfiguration\app-configuration
npm run test.

További részletekért tekintse meg a teszteket mappát.

Visszajelzés

Hasznosnak találta ezt az oldalt?

Last updated on 2025-11-13