Udostępnij za pośrednictwem

Biblioteka klienta usługi App Configuration dla języka JavaScript

  • Artykuł

azure App Configuration to usługa zarządzana, która ułatwia deweloperom proste i bezpieczne scentralizowanie ustawień aplikacji i funkcji.

Użyj biblioteki klienta dla usługi App Configuration, aby:

  • Tworzenie elastycznych reprezentacji kluczy i mapowań
  • Tagowanie kluczy z etykietami
  • Ustawienia odtwarzania z dowolnego punktu w czasie
  • Zarządzanie migawkami konfiguracji aplikacji

Kluczowe linki:

Wprowadzenie

Instalowanie pakietu

npm install @azure/app-configuration

Obecnie obsługiwane środowiska

  • wersje Node.js LTS
  • Najnowsze wersje przeglądarek Safari, Chrome, Edge i Firefox.

Aby uzyskać więcej informacji, zobacz nasze zasad pomocy technicznej.

Warunki wstępne

  • subskrypcji platformy Azure
  • Zasób App Configuration

Tworzenie zasobu usługi App Configuration

Aby utworzyć zasób usługi Azure App Configuration, możesz użyć Azure Portal lub interfejsu wiersza polecenia platformy Azure .

Przykład (interfejs wiersza polecenia platformy Azure):

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

Uwierzytelnianie klienta

Element AppConfigurationClient może uwierzytelniać się przy użyciu jednostki usługi lub parametrów połączenia .

Uwierzytelnianie za pomocą jednostki usługi

Uwierzytelnianie za pośrednictwem jednostki usługi odbywa się przez:

  • Tworzenie poświadczeń przy użyciu pakietu @azure/identity.
  • Ustawianie odpowiednich reguł kontroli dostępu opartej na rolach dla zasobu AppConfiguration. Więcej informacji na temat ról usługi App Configuration można znaleźć tutaj.

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

Więcej informacji na temat @azure/identity można znaleźć tutaj,

Suwerenne chmury

Aby uwierzytelnić się przy użyciu zasobu w Suwerennej chmurze, należy ustawić authorityHost w opcjach poświadczeń lub za pomocą zmiennej środowiskowej 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 })
);

Więcej informacji na temat @azure/identity można znaleźć tutaj,

Uwierzytelnianie przy użyciu parametrów połączenia

Aby uzyskać podstawowe parametry połączenia dla zasobu usługi App Configuration, możesz użyć tego polecenia interfejsu wiersza polecenia platformy Azure:

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

W kodzie możesz teraz utworzyć klienta usługi App Configuration przy użyciu parametrów połączenia uzyskanych z interfejsu wiersza polecenia platformy Azure:

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

Kluczowe pojęcia

AppConfigurationClient zawiera pewne zmiany w terminologii z usługi App Configuration w portalu.

  • Pary klucz/wartość są reprezentowane jako obiekty ConfigurationSetting
  • Blokowanie i odblokowywanie ustawienia jest reprezentowane w polu isReadOnly, które można przełączać przy użyciu setReadOnly.
  • Migawki są reprezentowane jako obiekty ConfigurationSnapshot.

Klient stosuje prostą metodologię projektowania — ConfigurationSetting można przekazać do dowolnej metody, która przyjmuje ConfigurationSettingParam lub ConfigurationSettingId.

Oznacza to, że ten wzorzec działa:

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

lub, na przykład, ponowne uzyskanie ustawienia:

let setting = await client.getConfigurationSetting({
  key: "hello"
});

// re-get the setting
setting = await client.getConfigurationSetting(setting);

Wersja interfejsu API 2022-11-01-preview obsługuje migawki konfiguracji: niezmienne kopie magazynu konfiguracji do punktu w czasie. Migawki można tworzyć za pomocą filtrów, które określają, które pary klucz-wartość znajdują się w migawce, tworząc niezmienny widok magazynu konfiguracji. Ta funkcja umożliwia aplikacjom utrzymywanie spójnego widoku konfiguracji, zapewniając, że nie ma niezgodności wersji z poszczególnymi ustawieniami z powodu odczytu w miarę wprowadzania aktualizacji. Na przykład ta funkcja może służyć do tworzenia "migawek konfiguracji wydania" w ramach usługi App Configuration. Zobacz tworzenia i pobierania sekcji migawki w poniższym przykładzie.

Przykłady

Tworzenie i pobieranie ustawienia

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

Tworzenie migawki

beginCreateSnapshot daje narzędzie poller do sondowania utworzenia migawki.

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

Możesz również użyć beginCreateSnapshotAndWait, aby uzyskać wynik utworzenia bezpośrednio po zakończeniu sondowania.

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

Pobieranie migawki

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

Wyświetlanie listy ConfigurationSetting w migawce

const retrievedSnapshotSettings = await client.listConfigurationSettingsForSnapshot("testsnapshot");

for await (const setting of retrievedSnapshotSettings) {
  console.log(`Found key: ${setting.key}, label: ${setting.label}`);
}

Wyświetlanie listy wszystkich migawek z usługi

const snapshots = await client.listSnapshots();

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

Odzyskiwanie i archiwizowanie migawki

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

Rozwiązywanie problemów

Wyrąb

Włączenie rejestrowania może pomóc odkryć przydatne informacje o błędach. Aby wyświetlić dziennik żądań i odpowiedzi HTTP, ustaw zmienną środowiskową AZURE_LOG_LEVEL na info. Alternatywnie rejestrowanie można włączyć w czasie wykonywania, wywołując setLogLevel w @azure/logger:

const { setLogLevel } = require("@azure/logger");

setLogLevel("info");

Aby uzyskać bardziej szczegółowe instrukcje dotyczące włączania dzienników, zapoznaj się z dokumentami dotyczącymi pakietów @azure/rejestratora.

Obsługa oprogramowania React Native

Platforma React Native nie obsługuje niektórych interfejsów API języka JavaScript używanych przez tę bibliotekę ZESTAWU SDK, dlatego należy podać dla nich polyfills. Aby uzyskać więcej szczegółów, zobacz nasz przykład React Native z Expo.

Następne kroki

W poniższych przykładach przedstawiono różne sposoby interakcji z usługą App Configuration:

  • helloworld.ts — pobieranie, ustawianie i usuwanie wartości konfiguracji.
  • helloworldWithLabels.ts — użyj etykiet, aby dodać dodatkowe wymiary do ustawień dla scenariuszy, takich jak wersja beta a produkcja.
  • optimisticConcurrencyViaEtag.ts — ustaw wartości przy użyciu elementów etag, aby zapobiec przypadkowemu zastąpieniu.
  • setReadOnlySample.ts — ustawienia oznaczania jako tylko do odczytu, aby zapobiec modyfikacji.
  • getSettingOnlyIfChanged.ts — pobierz ustawienie tylko wtedy, gdy zmieniono je od czasu ostatniego jego uzyskania.
  • listRevisions.ts — wyświetl listę poprawek klucza, umożliwiając wyświetlanie poprzednich wartości i ich ustawienie.
  • secretReference.ts — SecretReference reprezentuje ustawienie konfiguracji, które odwołuje się do klucza tajnego usługi KeyVault.
  • snapshot.ts — tworzenie, wyświetlanie listy ustawień konfiguracji i archiwizowanie migawek.
  • featureFlag.ts — flagi funkcji to ustawienia zgodne z określonym schematem JSON dla wartości.

Więcej szczegółowych przykładów można znaleźć w folderze przykłady w witrynie GitHub.

Przyczyniając się

Jeśli chcesz współtworzyć tę bibliotekę, przeczytaj przewodnik dotyczący współtworzenia , aby dowiedzieć się więcej na temat tworzenia i testowania kodu.

Testy tego modułu to kombinacja testów na żywo i testów jednostkowych, które wymagają wystąpienia usługi Azure App Configuration. Aby wykonać testy, należy uruchomić:

  1. rush update
  2. rush build -t @azure/app-configuration
  3. Utwórz plik env o następującej zawartości w folderze sdk\appconfiguration\app-configuration: APPCONFIG_CONNECTION_STRING=connection string for your App Configuration instance
  4. cd sdk\appconfiguration\app-configuration
  5. npm run test.

Aby uzyskać więcej informacji, zobacz nasze testy folderze.

wrażenia