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

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

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

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

Выберите подходящий пакет

Используйте @azure/app-configuration (эту библиотеку) для того, чтобы:

Управление параметрами конфигурации и моментальными снимками в Конфигурации приложений Azure
Выполнение детализированных операций чтения, которые выходят за рамки обычного потребления конфигурации

Большинство приложений должны начинаться с библиотеки @azure/app-configuration-provider , которая основана на этой низкоуровневой клиентской библиотеке и является рекомендуемым способом использования конфигурации во время выполнения. Он добавляет:

Гибкие шаблоны доступа с использованием конфигурации в виде карты «ключ-значение» или структурированного объекта JSON
Механизм запросов для декларативной компоновки конфигурации приложения
Обновление конфигурации во время выполнения
Высокая надежность благодаря кэшированию, обнаружению реплик, аварийному переключению и балансировке нагрузки
Разрешение ссылок Key Vault и автоматическое обновление
Интеграция флагов функций для библиотеки @microsoft/управления функциями

Для получения дополнительной информации перейдите в раздел Обзор поставщика конфигурации.

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

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

npm install @azure/app-configuration

Заметка: Для приложений, которым требуется только чтение значений конфигурации, рекомендуется использовать библиотеку @azure/app-configuration-provider .

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

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

import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

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

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

Чтобы пройти аутентификацию с ресурсом в суверенном облаке, вам потребуется задать audience параметры в конструкторе AppConfigurationClient .

import { AppConfigurationClient, KnownAppConfigAudience } from "@azure/app-configuration";
import { DefaultAzureCredential } from "@azure/identity";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.azure.cn";
// Create an AppConfigurationClient that will authenticate through AAD in the China cloud
const client = new AppConfigurationClient(endpoint, new DefaultAzureCredential(), {
  audience: KnownAppConfigAudience.AzureChina,
});

Примечание: Если audience свойство не определено, SDK по умолчанию будет использовать Azure Public Cloud.

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

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

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

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

import { AppConfigurationClient } from "@azure/app-configuration";

const connectionString = "Endpoint=https://example.azconfig.io;XXX=YYYY;YYY=ZZZZ";
const client = new AppConfigurationClient(connectionString);

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

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

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

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

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

import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

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

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

import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

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

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

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

Примеры

Заметка: Если приложению требуется только получение значений конфигурации и не требуется выполнение операций создания, обновления или удаления параметров конфигурации, рассмотрите возможность использования библиотеки @azure/app-configuration-provider . Библиотека поставщика предлагает упрощенный интерфейс для загрузки данных конфигурации во время выполнения и дополнительные функции. Множество примеров кода можно найти в документации по настройке приложений Azure в Microsoft Learn.

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

import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

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.
  // https://learn.microsoft.com/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);

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

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

import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

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

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

import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

const key = "testkey";
const value = "testvalue";
const label = "optional-label";

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

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

import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

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

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

import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

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

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

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

import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

const snapshots = await client.listSnapshots();

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

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

import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

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

import { setLogLevel } from "@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. Чтобы выполнить тесты, необходимо выполнить следующее:

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

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

Обратная связь

Была ли эта страница полезна?

Last updated on 2025-11-13