Sdílet prostřednictvím

App Configuration klientské knihovny pro JavaScript

  • Článek

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

Pomocí klientské knihovny App Configuration:

  • Vytváření flexibilních reprezentací a mapování klíčů
  • 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:

Začínáme

Instalace balíčku

npm install @azure/app-configuration

Aktuálně podporovaná prostředí

  • LtS verze Node.js
  • Nejnovější verze prohlížečů Safari, Chrome, Edge a Firefox.

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

Požadavky

Vytvoření prostředku App Configuration

K vytvoření prostředku Azure App Configuration můžete použít 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 připojovací řetězec.

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í @azure/identity balíčku
  • Nastavení odpovídajících pravidel RBAC pro prostředek AppConfiguration Další informace o rolích App Configuration najdete tady.

Použití výchozího přihlašovacího údajeAzureCredential

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 najdete @azure/identitytady.

Suverénní cloudy

Pokud chcete provést ověřování pomocí prostředku v suverénním cloudu, budete muset nastavit authorityHost v možnostech přihlašovacích údajů nebo prostřednictvím AZURE_AUTHORITY_HOST proměnné prostředí.

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 najdete @azure/identitytady.

Ověřování pomocí připojovací řetězec

Pokud chcete získat primární připojovací řetězec 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 App Configuration pomocí připojovací řetězec, který jste získali z Azure CLI:

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

Klíčové koncepty

Má AppConfigurationClient několik změn terminologie oproti App Configuration na portálu.

  • Páry klíč-hodnota jsou reprezentovány jako ConfigurationSetting objekty.
  • V poli je znázorněno isReadOnly zamykání a odemknutí nastavení, které můžete přepínat pomocí setReadOnly.
  • Snímky jsou reprezentovány jako ConfigurationSnapshot objekty.

Klient se řídí jednoduchou metodologií návrhu – ConfigurationSetting lze ji předat jakékoli metodě, která používá 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 2022-11-01-preview rozhraní API podporuje snímky konfigurace: neměnné kopie úložiště konfigurace k určitému bodu v čase. Snímky je možné vytvářet s filtry, které určují, které páry klíč-hodnota jsou obsaženy ve snímku, a vytvářejí tak neměnné a složené zobrazení úložiště konfigurace. Tato funkce umožňuje aplikacím uchovávat konzistentní zobrazení konfigurace a zajistit tak, aby nedochází k neshodám verzí s jednotlivými nastaveními z důvodu čtení při aktualizacích. Tuto funkci můžete například použít k vytvoření snímků konfigurace vydané verze v rámci App Configuration. Podívejte se na část vytvoření a získání 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"
  });

  let 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 poskytne pollera, který se bude dotazovat 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));

Pomocí příkazu můžete také beginCreateSnapshotAndWait získat výsledek vytvoření 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);

Zobrazení seznamu ConfigurationSetting ve snímku

let 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

let 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
let archivedSnapshot = await client.archiveSnapshot("testsnapshot");
console.log("Snapshot updated status is:", archivedSnapshot.status);

// Snapshot is in archive status
let recoverSnapshot = await client.recoverSnapshot("testsnapshot");
console.log("Snapshot updated status is:", recoverSnapshot.status);

Poradce při potížích

protokolování

Povolení protokolování může pomoct odhalit užitečné informace o selháních. Pokud chcete zobrazit protokol požadavků a odpovědí HTTP, nastavte proměnnou AZURE_LOG_LEVEL prostředí na info. Případně je možné 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 balíčkům @azure/protokolovacího nástroje.

podpora React Native

React Native nepodporuje některé javascriptové rozhraní API používané touto knihovnou sady SDK, takže pro ně musíte 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 App Configuration:

  • 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 nebo produkční verze.
  • optimisticConcurrencyViaEtag.ts – Nastavte hodnoty pomocí značek etag, abyste zabránili náhodnému přepsání.
  • setReadOnlySample.ts - Označení nastavení jako 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 informace o tom, kdy byly nastaveny.
  • secretReference.ts – SecretReference představuje nastavení konfigurace, které odkazuje na tajný klíč služby Key Vault.
  • snapshot.ts – Vytvořit, vypsat nastavení konfigurace a archivovat snímky.
  • featureFlag.ts – Příznaky funkcí jsou nastavení, která se řídí konkrétním schématem JSON pro danou hodnotu.

Podrobnější příklady najdete ve složce s ukázkami na GitHubu.

Přispívání

Pokud chcete přispívat do této knihovny, přečtěte si příručku pro přispívání , kde najdete další informace o tom, jak sestavit a otestovat kód.

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

  1. rush update
  2. rush build -t @azure/app-configuration
  3. Ve složce vytvořte soubor .env s následujícím obsahem sdk\appconfiguration\app-configuration : APPCONFIG_CONNECTION_STRING=connection string for your App Configuration instance
  4. cd sdk\appconfiguration\app-configuration
  5. npm run test.

Další podrobnosti najdete v naší složce testů .

Imprese