Klientská knihovna Azure App Configuration pro JavaScript – verze 1.10.0

azure App Configuration je spravovaná služba, která vývojářům pomáhá jednoduše a bezpečně centralizovat nastavení aplikací a funkcí.

Klíčové odkazy:

Zdrojový kód
balíčku (NPM)
Referenční dokumentace k rozhraní API
dokumentace k produktu
Ukázky

Vyberte si správný balíček

Pomocí @azure/app-configuration (tato knihovna) můžete:

Správa nastavení konfigurace a snímků v Azure App Configuration
Provádějte granulární čtení, která fungují mimo sféru běžné spotřeby konfigurace

Většina aplikací by měla začínat knihovnou @azure/app-configuration-provider , která vychází z této klientské knihovny nízké úrovně a je doporučeným způsobem, jak využívat konfiguraci za běhu. Dodává:

Flexibilní vzory přístupu využívající konfiguraci jako mapu klíč/hodnota nebo strukturovaný objekt JSON
Mechanismus dotazů pro deklarativní vytváření konfigurace aplikace
Aktualizace konfigurace za běhu
Vysoká spolehlivost s ukládáním do mezipaměti, zjišťováním replik, převzetím služeb při selhání a vyrovnáváním zátěže
Řešení odkazů na trezor klíčů a automatická aktualizace
Integrace příznaků funkcí pro knihovnu @microsoft / správu funkcí

Další informace naleznete v článku Přehled poskytovatele konfigurace.

Začínáme

Instalace balíčku

npm install @azure/app-configuration

Poznámka: Pro aplikace, které potřebují pouze číst konfigurační hodnoty, doporučujeme místo toho použít knihovnu @azure/app-configuration-provider .

Aktuálně podporovaná prostředí

Verze LTS Node.js
Nejnovější verze Safari, Chrome, Edge a Firefox.

Další podrobnosti najdete v našich zásadách podpory .

Požadavky

předplatného Azure
Prostředek konfigurace aplikace

Vytvoření prostředku App Configuration

K vytvoření prostředku azure App Configuration můžete použít webu Azure Portal nebo Azure CLI.

Příklad (Azure CLI):

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

Ověření klienta

AppConfigurationClient se může ověřit pomocí instančního objektu nebo pomocípřipojovacího řetězce .

Ověřování pomocí instančního objektu

Ověřování prostřednictvím instančního objektu provádí:

Vytvoření přihlašovacích údajů pomocí balíčku @azure/identity
Nastavení odpovídajících pravidel RBAC pro prostředek AppConfiguration Další informace o rolích App Configuration najdete zde.

Použití defaultAzureCredential

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

Další informace o @azure/identity najdete zde

Suverénní cloudy

Chcete-li se ověřit pomocí zdroje v suverénním cloudu, budete muset nastavit možnosti konstruktoru audienceAppConfigurationClient .

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

Poznámka: Pokud audience vlastnost není definovaná, sada SDK bude ve výchozím nastavení nastavena na veřejný cloud Azure.

Ověřování pomocí připojovacího řetězce

Pokud chcete získat primárního připojovacího řetězce pro prostředek App Configuration, můžete použít tento příkaz Azure CLI:

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

A v kódu teď můžete vytvořit klienta služby App Configuration pomocí připojovacího řetězce , který jste získali z Azure CLI:

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

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

Klíčové koncepty

AppConfigurationClient má na portálu určité změny terminologie z konfigurace aplikace.

Páry klíč/hodnota jsou reprezentovány jako objekty ConfigurationSetting
Uzamčení a odemknutí nastavení je znázorněno v poli isReadOnly, které můžete přepnout pomocí setReadOnly.
Snímky jsou reprezentovány jako objekty ConfigurationSnapshot.

Klient se řídí jednoduchou metodou návrhu – ConfigurationSetting lze předat do jakékoli metody, která přebírá ConfigurationSettingParam nebo ConfigurationSettingId.

To znamená, že tento model funguje:

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

nebo například opětovné získání nastavení:

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

Verze rozhraní API 2022-11-01-preview podporuje snímky konfigurace: neměnné kopie úložiště konfigurace k určitému bodu v čase. Snímky je možné vytvořit pomocí filtrů, které určují, které páry klíč-hodnota jsou obsaženy ve snímku, a vytvářejí neměnné zobrazení složené z úložiště konfigurace. Tato funkce umožňuje aplikacím uchovávat konzistentní zobrazení konfigurace a zajistit, aby se kvůli čtení aktualizací neshodovaly žádné verze s individuálními nastaveními. Tuto funkci můžete například použít k vytvoření "snímků konfigurace vydaných verzí" v rámci konfigurace aplikace. Viz vytvoření a získání oddílu snímku v následujícím příkladu.

Příklady

Poznámka: Pokud vaše aplikace potřebuje pouze načíst hodnoty konfigurace a nevyžaduje provádění operací vytvoření, aktualizace nebo odstranění nastavení konfigurace, zvažte místo toho použití knihovny @azure/app-configuration-provider . Knihovna zprostředkovatele nabízí zjednodušené prostředí pro načítání konfiguračních dat za běhu a další funkce. Spoustu ukázek kódu najdete v dokumentaci ke konfiguraci aplikací Azure na Microsoft Learn.

Vytvoření a získání nastavení

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

Vytvoření snímku

beginCreateSnapshot vám umožní dotazovat se na vytvoření snímku.

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

Můžete také použít beginCreateSnapshotAndWait k tomu, aby výsledek vytvoření proběhlo přímo po dokončení dotazování.

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

Získání snímku

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

Výpis `ConfigurationSetting` na snímku

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

Výpis všech snímků ze služby

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

Obnovení a archivace snímku

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

Řešení problémů

Protokolování

Povolení protokolování může pomoct odhalit užitečné informace o chybách. Pokud chcete zobrazit protokol požadavků a odpovědí HTTP, nastavte proměnnou prostředí AZURE_LOG_LEVEL na info. Případně můžete protokolování povolit za běhu voláním setLogLevel v @azure/logger:

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

setLogLevel("info");

Podrobnější pokyny k povolení protokolů najdete v dokumentaci k @azure/protokolovacímu balíčku.

Podpora React Native

React Native nepodporuje některé javascriptové rozhraní API používané touto knihovnou sady SDK, takže pro ně potřebujete poskytnout polyfills. Další podrobnosti najdete v naší ukázce React Native s expo.

Další kroky

Následující ukázky ukazují různé způsoby interakce s konfigurací aplikace:

helloworld.ts – Získání, nastavení a odstranění konfiguračních hodnot
helloworldWithLabels.ts – Pomocí popisků můžete do nastavení přidat další dimenze pro scénáře, jako je beta verze nebo produkční prostředí.
optimisticConcurrencyViaEtag.ts – Nastavte hodnoty pomocí značek, abyste zabránili náhodnému přepsání.
setReadOnlySample.ts – označení nastavení jen pro čtení, aby se zabránilo úpravám.
getSettingOnlyIfChanged.ts – Nastavení získáte jenom v případě, že se změnilo od posledního okamžiku, kdy jste ho získali.
listRevisions.ts – Zobrazí seznam revizí klíče, což vám umožní zobrazit předchozí hodnoty a kdy byly nastaveny.
secretReference.ts – SecretReference představuje nastavení konfigurace, které odkazuje na tajný klíč KeyVault.
snapshot.ts – Vytvoření, výpis nastavení konfigurace a snímky archivu
featureFlag.ts – Příznaky funkcí jsou nastavení, která pro danou hodnotu sledují konkrétní schéma JSON.

Podrobnější příklady najdete v ukázkách složce na GitHubu.

Přispívající

Pokud chcete přispívat do této knihovny, přečtěte si průvodce přispívání a přečtěte si další informace o vytváření a testování kódu.

Testy tohoto modulu jsou kombinací živých testů a testů jednotek, které vyžadují, abyste měli instanci Azure App Configuration. Pokud chcete spustit testy, budete muset spustit:

pnpm install
pnpm build --filter @azure/app-configuration...
Ve složce sdk\appconfiguration\app-configuration vytvořte soubor .env s následujícím obsahem: APPCONFIG_CONNECTION_STRING=connection string for your App Configuration instance
cd sdk\appconfiguration\app-configuration
npm run test.

Další podrobnosti najdete ve složce testy.

Váš názor

Byla tato stránka užitečná?

Last updated on 2025-11-13