Klientská knihovna App Configuration pro JavaScript

Článek
07/17/2024

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

Ke konfiguraci aplikace použijte klientskou knihovnu pro:

Vytváření flexibilních klíčových reprezentací a mapování
Označování klíčů pomocí popisků
Přehrání nastavení z libovolného bodu v čase
Správa snímků konfigurace aplikace

Klíčové odkazy:

zdrojového kódu
balíčku (NPM)
Referenční dokumentace k rozhraní API
dokumentace k produktu
ukázky

Začínáme

Instalace balíčku

npm install @azure/app-configuration

Aktuálně podporovaná prostředí

LTS verze 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

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

Další informace o @azure/identity najdete zde

Suverénní cloudy

Pokud se chcete ověřit pomocí prostředku v suverénním cloudu, budete muset nastavit authorityHost v možnostech přihlašovacích údajů nebo prostřednictvím proměnné prostředí 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 })
);

Další informace o @azure/identity najdete zde

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:

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

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:

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

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

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

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

Vytvoření snímku

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

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

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

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

Získání snímku

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

Výpis `ConfigurationSetting` na snímku

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

const snapshots = await client.listSnapshots();

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

Obnovení a archivace snímku

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

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

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

imprese

Sdílet prostřednictvím

Klientská knihovna App Configuration pro JavaScript

Začínáme

Instalace balíčku

Aktuálně podporovaná prostředí

Požadavky

Vytvoření prostředku App Configuration

Ověření klienta

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

Suverénní cloudy

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

Klíčové koncepty

Příklady

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

Vytvoření snímku

Získání snímku

Výpis `ConfigurationSetting` na snímku

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

Obnovení a archivace snímku

Řešení problémů

Protokolování

Podpora React Native

Další kroky

Přispívající

Další materiály

Sdílet prostřednictvím

Klientská knihovna App Configuration pro JavaScript

Začínáme

Instalace balíčku

Aktuálně podporovaná prostředí

Požadavky

Vytvoření prostředku App Configuration

Ověření klienta

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

Suverénní cloudy

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

Klíčové koncepty

Příklady

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

Vytvoření snímku

Získání snímku

Výpis ConfigurationSetting na snímku

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

Obnovení a archivace snímku

Řešení problémů

Protokolování

Podpora React Native

Další kroky

Přispívající

Související projekty

Další materiály

Výpis `ConfigurationSetting` na snímku