Клиентская библиотека конфигурации приложений для JavaScript

конфигурации приложений Azure — это управляемая служба, которая помогает разработчикам централизировать свои параметры приложений и компонентов просто и безопасно.

Использование клиентской библиотеки для конфигурации приложений:

• Создание гибких представлений ключей и сопоставлений
• Теги ключей с метками
• Параметры воспроизведения с любого момента во времени
• Управление моментальными снимками конфигурации приложения

Ключевые ссылки:

• исходный код.
• пакета (NPM)
• Справочная документация по API
• документации по продукту
• Примеры

Начало работы

Установка пакета

npm install @azure/app-configuration

Поддерживаемые в настоящее время среды

• LTS версии Node.js
• Последние версии Safari, Chrome, Edge и Firefox.

Дополнительные сведения см. в политике поддержки .

Необходимые условия

• подписки Azure
• Ресурс конфигурации приложений

Создание ресурса конфигурации приложений

Вы можете использовать портал Azure или Azure CLI для создания ресурса конфигурации приложений Azure.

Пример (Azure CLI):

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

Проверка подлинности клиента

AppConfigurationClient может пройти проверку подлинности с помощью субъекта-службы илистроки подключения .

Проверка подлинности с помощью субъекта-службы

Проверка подлинности с помощью субъекта-службы выполняется следующим образом:

• Создание учетных данных с помощью пакета @azure/identity.
• Задание соответствующих правил RBAC в ресурсе AppConfiguration. Дополнительные сведения о ролях конфигурации приложений можно найти здесь.

Использование 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
);

Дополнительные сведения о @azure/identity можно найти здесь

Суверенные облака

Чтобы выполнить проверку подлинности с помощью ресурса в Sovereign Cloud, необходимо задать authorityHost в параметрах учетных данных или с помощью переменной среды 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 })
);

Дополнительные сведения о @azure/identity можно найти здесь

Проверка подлинности с помощью строки подключения

Чтобы получить строку подключения основного для ресурса конфигурации приложений, можно использовать следующую команду Azure CLI:

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

Теперь вы можете создать клиент конфигурации приложений с помощью строки подключения , полученной из Azure CLI:

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

Основные понятия

AppConfigurationClient имеет некоторые изменения терминологии из конфигурации приложений на портале.

• Пары "Ключ-значение" представляются как объекты ConfigurationSetting
• Блокировка и разблокировка параметра представлена в поле isReadOnly, которое можно переключать с помощью setReadOnly.
• Моментальные снимки представлены как объекты ConfigurationSnapshot.

Клиент следует простой методологии проектирования. ConfigurationSetting можно передать в любой метод, который принимает ConfigurationSettingParam или ConfigurationSettingId.

Это означает, что этот шаблон работает:

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

или, например, повторное получение параметра:

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

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

Версия API 2022-11-01-preview поддерживает моментальные снимки конфигурации: неизменяемые копии хранилища конфигурации на определенный момент времени. Моментальные снимки можно создавать с помощью фильтров, определяющих, какие пары "ключ-значение" содержатся в моментальном снимке, создавая неизменяемое представление хранилища конфигурации. Эта функция позволяет приложениям хранить согласованное представление конфигурации, обеспечивая отсутствие несоответствия версий отдельным параметрам из-за считывания обновлений. Например, эту функцию можно использовать для создания моментальных снимков конфигурации выпуска в конфигурации приложений. См. раздел создания и получения моментального снимка раздела в приведенном ниже примере.

Примеры

Создание и получение параметра

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

Создание моментального снимка

beginCreateSnapshot предоставляет опросщику для создания моментального снимка.

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

Вы также можете использовать beginCreateSnapshotAndWait для получения результата создания непосредственно после завершения опроса.

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

Получение моментального снимка

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

Вывод списка ConfigurationSetting в моментальном снимке

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

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

Вывод списка всех моментальных снимков из службы

const snapshots = await client.listSnapshots();

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

Восстановление и архивация моментального снимка

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

Устранение неполадок

Лесозаготовка

Включение ведения журнала может помочь выявить полезные сведения о сбоях. Чтобы просмотреть журнал HTTP-запросов и ответов, задайте для переменной среды AZURE_LOG_LEVEL значение info. Кроме того, ведение журнала можно включить во время выполнения путем вызова setLogLevel в @azure/logger:

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

setLogLevel("info");

Дополнительные инструкции по включению журналов см. в документации по пакету @azure/loger.

Поддержка React Native

React Native не поддерживает некоторые API JavaScript, используемые этой библиотекой SDK, поэтому для них необходимо предоставить полизаполнения. Дополнительные сведения см. в нашем примере React Native с помощью Expo.

Дальнейшие действия

В следующих примерах показаны различные способы взаимодействия с конфигурацией приложений:

• helloworld.ts — получение, установка и удаление значений конфигурации.
• helloworldWithLabels.ts. Используйте метки для добавления дополнительных измерений в параметры для таких сценариев, как бета-версия и рабочая среда.
• optimisticConcurrencyViaEtag.ts . Задайте значения с помощью etag, чтобы предотвратить случайные перезаписи.
• setReadOnlySample.ts . Маркировка параметров как доступных только для чтения, чтобы предотвратить изменение.
• getSettingOnlyIfChanged.ts — получение параметра только в том случае, если оно изменилось с момента последнего получения.
• listRevisions.ts — вывод списка редакций ключа, что позволяет просматривать предыдущие значения и когда они были заданы.
• secretReference.ts — SecretReference представляет параметр конфигурации, ссылающийся на секрет KeyVault.
• snapshot.ts. Создание, параметры конфигурации списка и архивные моментальные снимки.
• featureFlag.ts . Флаги компонентов — это параметры, которые соответствуют определенной схеме JSON для значения.

Более подробные примеры можно найти в примерах папке на сайте GitHub.

Способствует

Если вы хотите внести свой вклад в эту библиотеку, ознакомьтесь с руководством по вкладу, чтобы узнать больше о том, как создавать и тестировать код.

Тесты этого модуля — это смесь динамических и модульных тестов, которые требуют наличия экземпляра конфигурации приложений Azure. Чтобы выполнить тесты, необходимо выполнить следующее:

1. rush update
2. rush build -t @azure/app-configuration
3. Создайте env-файл с этим содержимым в папке sdk\appconfiguration\app-configuration: APPCONFIG_CONNECTION_STRING=connection string for your App Configuration instance
4. cd sdk\appconfiguration\app-configuration
5. npm run test.

Дополнительные сведения см. в папке тестов.

Связанные проекты

• пакет SDK Microsoft Azure для JavaScript
• Конфигурация приложений Azure