Klientská knihovna App Configuration pro JavaScript

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ý kód
• 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í

• 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

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:

1. rush update
2. rush build -t @azure/app-configuration
3. 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
4. cd sdk\appconfiguration\app-configuration
5. npm run test.

Další podrobnosti najdete ve složce testy.

Související projekty

• sady Microsoft Azure SDK pro JavaScript
• konfigurace Aplikace Azure