Поставщик конфигурации JavaScript

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

Конфигурация загрузки

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

Идентификатор Microsoft Entra
Строка соединения

Вы используете DefaultAzureCredential для проверки подлинности в хранилище конфигурации приложений. Следуйте инструкциям, чтобы назначить ваши учетные данные на роль Чтение данных конфигурации приложений.

const { load } = require("@azure/app-configuration-provider");
const { DefaultAzureCredential } = require("@azure/identity");
const endpoint = process.env.AZURE_APPCONFIG_ENDPOINT;
const credential = new DefaultAzureCredential(); // For more information, see https://learn.microsoft.com/azure/developer/javascript/sdk/credential-chains#use-defaultazurecredential-for-flexibility

async function run() {
    // Connect to Azure App Configuration using a token credential and load all key-values with no label.
    const appConfig = await load(endpoint, credential);
    console.log('appConfig.get("message"):', appConfig.get("message"));
}

run();

const { load } = require("@azure/app-configuration-provider");
const connectionString = process.env.AZURE_APPCONFIG_CONNECTION_STRING;

async function run() {
    // Connect to Azure App Configuration using a connection string and load all key-values with no label.
    const appConfig = await load(connectionString);
    console.log('appConfig.get("message"):', appConfig.get("message"));
}

run();

Метод load возвращает экземпляр AzureAppConfiguration типа, который определяется следующим образом:

type AzureAppConfiguration = {
    refresh(): Promise<void>;
    onRefresh(listener: () => any, thisArg?: any): Disposable;
} & IGettable & ReadonlyMap<string, any> & IConfigurationObject;

Дополнительные сведения о refresh параметрах и onRefresh методах см. в разделе "Обновление конфигурации".

Использование конфигурации

Тип AzureAppConfiguration расширяет следующие интерфейсы:

IGettable

interface IGettable {
    get<T>(key: string): T | undefined;
}

Интерфейс IGettable предоставляет get метод для получения значения по ключу из структуры данных в стиле Map.

const appConfig = await load(endpoint, credential);
const fontSize = appConfig.get("app:font:size"); // value of the key "app:font:size" from the App Configuration store

ReadonlyMap

Тип AzureAppConfiguration также расширяет интерфейс ReadonlyMap, предоставляя доступ только для чтения к парам «ключ-значение».
IConfigurationObject
```
interface IConfigurationObject {
    constructConfigurationObject(options?: ConfigurationObjectConstructionOptions): Record<string, any>;
}
```
Интерфейс IConfigurationObject предоставляет метод constructConfigurationObject для создания объекта конфигурации на основе структуры данных в стиле Map и иерархических ключей. Необязательный ConfigurationObjectConstructionOptions параметр можно использовать для указания разделителя для преобразования иерархических ключей в свойства объекта. По умолчанию разделитель имеет значение ".".
```
interface ConfigurationObjectConstructionOptions {
    separator?: "." | "," | ";" | "-" | "_" | "__" | "/" | ":"; // supported separators
}
```
В JavaScript объекты или карты обычно используются в качестве основных структур данных для представления конфигураций. Библиотека поставщиков конфигураций JavaScript поддерживает оба подхода к конфигурации, предоставляя разработчикам гибкость, чтобы выбрать вариант, который лучше всего соответствует их потребностям.
```
const appConfig = await load(endpoint, credential);
const settingsObj = appConfig.constructConfigurationObject({separator: ":"});
const fontSize1 = appConfig.get("app:font:size"); // map-style configuration representation
const fontSize2 = settingsObj.app.font.size; // object-style configuration representation
```

Обработка типов контента JSON

В конфигурации приложения можно создать значения ключей JSON . При загрузке значений ключей из конфигурации приложений Azure поставщик конфигурации автоматически преобразует значения ключей допустимого типа содержимого JSON (например, application/json) в объект.

{
    "key": "font",
    "label": null,
    "value": "{\r\n\t\"size\": 12,\r\n\t\"color\": \"red\"\r\n}",
    "content_type": "application/json"
}

Указанное выше значение ключа будет загружено как { size: 12, color: "red" }.

const appConfig = await load(endpoint, credential);
const { size, color } = appConfig.get("font");

Примечание.

Начиная с версии 2.2.0@azure/app-configuration-provider, поставщик конфигурации разрешает комментарии, как определено в (JSONC), в значениях ключей с типом application/json контента.

Загрузка определенных значений ключей с помощью селекторов

По умолчанию load метод загружает все конфигурации без метки из хранилища конфигураций. Поведение load метода можно настроить с помощью необязательного AzureAppConfigurationOptions параметра типа.

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

const appConfig = await load(endpoint, credential, {
    selectors: [
        { // load the subset of keys starting with "app1." prefix and "test" label
            keyFilter: "app1.*",
            labelFilter: "test"
        },
        { // load the subset of keys with "dev" label"
            keyFilter: "*",
            labelFilter: "dev"
        }
    ]
});

Примечание.

Значения ключей загружаются в том порядке, в котором перечислены селекторы. Если несколько селекторов извлекают значения с одинаковым ключом, то значение из последнего заменит любое ранее загруженное значение.

Фильтры тегов

Параметр фильтра тегов выбирает значения ключей с определенными тегами. Значение ключа загружается только в том случае, если он содержит все теги и соответствующие значения, указанные в фильтрах.

const appConfig = await load(endpoint, credential, {
    selectors: [
        { // load the subset of keys with "test" label" and three tags
            keyFilter: "*",
            labelFilter: "test",
            tagFilters: [
                "emptyTag=",
                "nullTag=\0",
                "tag1=value1"
            ]
        }
    ]
});

Примечание.

Символы звездочка (*), запятая (,) и обратная косая черта (\) зарезервированы и должны быть экранированы с помощью обратной косой черты при использовании в фильтре тегов.

Удалить префикс из ключей

Вы можете удалить префикс из ключей, предоставив список удаляемых префиксов ключей свойству AzureAppConfigurationOptions.trimKeyPrefixes.

const appConfig = await load(endpoint, credential, {
    selectors: [{
        keyFilter: "app.*"
    }],
    trimKeyPrefixes: ["app."]
});

Обновление конфигурации

Поставщика можно настроить для извлечения последних настроек из хранилища конфигурации приложений без перезагрузки приложения. Вы можете включить функцию обновления AzureAppConfigurationOptions.refreshOptions и настроить параметры обновления. Загруженная конфигурация будет обновлена при обнаружении на сервере любого изменения выбранных значений ключей. По умолчанию используется интервал обновления в 30 секунд, но его можно переопределить с refreshIntervalInMs помощью свойства.

const appConfig = await load(endpoint, credential, {
    refreshOptions: {
        enabled: true,
        refreshIntervalInMs: 15_000
    }
});

Настройка refreshOptions сама по себе не будет автоматически обновлять конфигурацию. Чтобы запустить обновление, необходимо вызвать метод refresh на экземпляре AzureAppConfiguration, который возвращается методом load.

// this call is not blocking, the configuration will be updated asynchronously
appConfig.refresh();

Данный дизайн предотвращает ненужные запросы к App Configuration, когда приложение простаивает. Вы должны включить вызов refresh там, где происходит действие вашего приложения. Это называется обновлением конфигурации, управляемым действиями. Например, можно вызвать refresh при обработке входящего запроса или внутри итерации, в которой выполняется сложная задача.

const server = express();
// Use an express middleware to refresh configuration whenever a request comes in
server.use((req, res, next) => {
    appConfig.refresh();
    next();
})

Даже если вызов обновления завершается сбоем по какой-либо причине, приложение продолжит использовать кэшированную конфигурацию. Другая попытка будет предпринята, когда настроенный интервал обновления прошел, и вызов обновления активируется действием приложения. Вызов refresh — это no-op до истечения заданного интервала обновления, поэтому его влияние на производительность минимально, даже если оно часто вызывается.

Настраиваемый обратный вызов для обновления

Метод onRefresh позволяет задавать пользовательские функции обратного вызова, которые будут вызываться каждый раз при успешном обновлении локальной конфигурации с изменениями из хранилища конфигураций приложений Azure. Он возвращает объект Disposable, с помощью которого можно удалить зарегистрированный обратный вызов.

const appConfig = await load(endpoint, credential, {
    refreshOptions: {
        enabled: true
    }
});
const disposer = appConfig.onRefresh(() => {
    console.log("Config refreshed.");
});

appConfig.refresh();
// Once the refresh is successful, the callback function you registered will be executed.
// In this example, the message "Config refreshed" will be printed.

disposer.dispose();

Обновление ключа "сторож"

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

const appConfig = await load(endpoint, credential, {
    refreshOptions: {
        enabled: true,
        watchedSettings: [
            { key: "sentinel" }
        ]
    }
});

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

Флаг функции

Флаги компонентов можно создать в Конфигурация приложений Azure. По умолчанию флаги компонентов не загружаются поставщиком конфигурации. При вызове AzureAppConfigurationOptions.featureFlagOptions метода можно включить загрузку и обновление флагов компонентов с помощью load свойства.

const appConfig = await load(endpoint, credential, {
    featureFlagOptions: {
        enabled: true, // enable loading feature flags
        selectors: [ { keyFilter: "*", labelFilter: "Prod" } ],
        refresh: {
            enabled: true, // enable refreshing feature flags
            refreshIntervalInMs: 60_000
        }
    }
});

Примечание.

Если featureFlagOptions включен и селектор не указан, поставщик конфигурации загружает все флаги функций без метки из хранилища App Configuration.

Это важно

Чтобы эффективно использовать флаги компонентов, загруженные из конфигурации приложений Azure, установите и используйте @microsoft/feature-management пакет. Эта библиотека предоставляет структурированный способ управления поведением функций в приложении.

Управление функциями

Библиотека управления функциями предоставляет способ разработки и предоставления функциональных возможностей приложений на основе флагов компонентов. Библиотека управления функциями предназначена для работы в сочетании с библиотекой поставщика конфигурации. Поставщик конфигурации загружает все выбранные флаги функций в конфигурацию в списке feature_flags раздела feature_management. Библиотека управления функциями будет использовать и управлять загруженными флагами функций вашего приложения.

В следующем примере показано, как интегрировать библиотеку @microsoft/feature-management с поставщиком конфигурации для динамического управления доступом к API в приложении Express на основе состояния флага функции Beta.

// Load feature flags from Azure App Configuration
import { load } from "@azure/app-configuration-provider";
const appConfig = await load(endpoint, credential, {
    featureFlagOptions: {
        enabled: true, // enable loading feature flags
        refresh: {
            enabled: true // enable refreshing feature flags
        }
    }
});

import { ConfigurationMapFeatureFlagProvider, FeatureManager } from "@microsoft/feature-management";
// Create a feature flag provider which uses the configuration provider as feature flag source
const ffProvider = new ConfigurationMapFeatureFlagProvider(appConfig);
// Create a feature manager which will evaluate the feature flag
const featureManager = new FeatureManager(ffProvider);

import express from "express";
const server = express();

// Use a middleware to achieve request-driven configuration refresh
server.use((req, res, next) => {
    // this call is not blocking, the configuration will be updated asynchronously
    appConfig.refresh();
    next();
});

server.get("/Beta", async (req, res) => {
    if (await featureManager.isEnabled("Beta")) {
        res.send("Welcome to the Beta page!");
    } else {
        res.status(404).send("Page not found");
    }
});

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

Справочник по Key Vault

Конфигурация приложений Azure поддерживает ссылки на секреты, хранящиеся в Azure Key Vault. В конфигурации приложений можно создать ключи, которые сопоставляют секреты, хранящиеся в "Key Vault". Секреты безопасно хранятся в Key Vault, но доступ к ним можно получить как к любой другой конфигурации после загрузки.

Библиотека поставщика конфигурации извлекает ссылки на Key Vault так же, как и для других ключей, хранящихся в App Configuration. Так как клиент распознает ключи как ссылки на Key Vault, у него есть уникальный тип контента, и клиент подключится к Key Vault, чтобы получить их значения для приложения. Необходимо настроить AzureAppConfigurationOptions.KeyVaultOptions свойство с соответствующими учетными данными, чтобы разрешить поставщику конфигурации подключаться к Azure Key Vault.

const credential = new DefaultAzureCredential();
const appConfig = await load(endpoint, credential, {
    keyVaultOptions: {
        credential: credential
    }
});

Вы также можете непосредственно предоставить экземпляр SecretClient в KeyVaultOptions. Таким образом, при создании SecretClientможно настроить параметры.

import { SecretClient } from "@azure/keyvault-secrets";

const credential = new DefaultAzureCredential();
const secretClient = new SecretClient(keyVaultUrl, credential, {
    serviceVersion: "7.0",
});
const appConfig = await load(endpoint, credential, {
    keyVaultOptions: {
        secretClients: [ secretClient ]
    }
});

Вы также можете задать secretResolver свойство для локального разрешения секретов, которые не связаны с Key Vault.

const resolveSecret = (url) => "From Secret Resolver";
const appConfig = await load(endpoint, credential, {
    keyVaultOptions: {
        secretResolver: resolveSecret
    }
});

Вы также можете задать свойство clientOptions для настройки SecretClientOptions, используемой для подключения к Azure Key Vault, который не имеет зарегистрированного SecretClient.

const credential = new DefaultAzureCredential();
const appConfig = await load(endpoint, credential, {
    keyVaultOptions: {
        credential: credential,
        clientOptions: { // configure a custom SecretClientOptions
            retryOptions: { 
                maxRetries: 3, 
                maxRetryDelayInMs: 1000 
            }
        }
    }
});

Параллельное секретное разрешение

Azure Key Vault не предоставляет пакетный API для получения нескольких секретов в одном запросе. Когда вашему приложению нужно загрузить множество ссылок на Key Vault, можно повысить производительность, включив параллельное разрешение секретов, используя свойство parallelSecretResolutionEnabled в KeyVaultOptions. Это позволяет поставщику параллельно получить несколько секретов, а не последовательно:

const credential = new DefaultAzureCredential();
const appConfig = await load(endpoint, credential, {
    keyVaultOptions: {
        credential: credential,
        parallelSecretResolutionEnabled: true
    }
});

Примечание.

При параллельном разрешении секрета можно столкнуться с ограничением службы Azure Key Vault. Чтобы эффективно обрабатывать регулирование, реализуйте рекомендации по регулированию на стороне клиента , настроив соответствующие параметры повторных попыток для параметра SecretClient. Вы можете зарегистрировать пользовательские SecretClient экземпляры или настроить clientOptions с помощью AzureAppConfigurationOptions.keyVaultOptions.

Обновление секрета Key Vault

Служба Конфигурация приложений Azure позволяет настраивать интервалы обновления секретных данных независимо от цикла обновления конфигурации. Это важно для безопасности, так как в то время как URI ссылки Key Vault в конфигурации приложений остается неизменным, базовый секрет в Key Vault может быть изменен в рамках ваших методик безопасности.

Примечание.

Обновление секрета использует минимальный интервал в одну минуту. Это предотвращает чрезмерную перезагрузку секретов, которая может вызвать ограничения Key Vault.

Чтобы приложение всегда использовало самые текущие значения секретов, настройте secretRefreshIntervalInMs свойство в KeyVaultOptions. Это заставляет поставщика получать новые значения секретов из Key Vault, когда:

Ваша программа вызывает AzureAppConfiguration.refresh
Настроенный интервал обновления для секрета истек

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

const credential = new DefaultAzureCredential();
const appConfig = await load(endpoint, credential, {
    keyVaultOptions: {
        credential: credential,
        secretRefreshIntervalInMs: 7200_000 // 2 hours
    }
});

Снимок

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

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

const appConfig = await load(endpoint, credential, {
    selectors: [
        { snapshotName: "MySnapshot" }, // load key-values from snapshot
        { keyFilter: "test*", labelFilter: "test" }
    ],
    featureFlagOptions: {
        enabled: true,
        selectors: [
            { snapshotName: "MySnapshot" }, // load feature flags from snapshot
            { keyFilter: "*", labelFilter: "test" }
        ]
    }
});

Справочник по моментальным снимкам

Ссылка на моментальный снимок — это параметр конфигурации, ссылающийся на моментальный снимок в том же хранилище конфигурации приложений. При загрузке поставщик разрешает его и добавляет все значения ключей из этого моментального снимка. Использование ссылок на моментальные снимки позволяет переключаться между моментальными снимками во время выполнения, в отличие от добавления селектора моментальных снимков, который требует изменения кода и (или) перезапуска для переключения на новый моментальный снимок.

Для получения дополнительной информации о создании ссылки на моментальный снимок перейдите к понятию ссылки на моментальный снимок.

Примечание.

Чтобы использовать ссылки на моментальные снимки, используйте версию 2.3.0 или более позднюю версию @azure/app-configuration-provider.

Повторная попытка запуска

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

Это поведение можно настроить с помощью AzureAppConfigurationOptions.startupOptions:

const appConfig = await load(endpoint, credential, { 
    startupOptions: { 
        timeoutInMs: 300_000
    }
});

Георепликация

Сведения об использовании георепликации см. в описании включения георепликации.

Подключение к Azure Front Door

Интеграция Azure Front Door позволяет клиентским приложениям получать конфигурацию из пограничных кэшированных конечных точек, а не напрямую из конфигурации приложений. Эта архитектура обеспечивает безопасный масштабируемый доступ к конфигурации с преимуществами производительности глобального распространения CDN.

В следующем примере показано, как загрузить параметры конфигурации из Azure Front Door:

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

const appConfig = await loadFromAzureFrontDoor("{YOUR-AFD-ENDPOINT}", {
    selectors: [{
        keyFilter: "app.*"
    }],
    refreshOptions: {
        enabled: true,
        refreshIntervalInMs: 60_000
    }
});

const message = appConfig.get("app.message");

Дополнительные сведения о Azure Front Door см. в разделе "Загрузка конфигурации" из Azure Front Door в клиентских приложениях.

Следующие шаги

Чтобы узнать, как использовать поставщик конфигурации JavaScript, перейдите к данному руководству.

Использование динамической конфигурации в JavaScript

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

Управление функциями JavaScript

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

Были ли сведения на этой странице полезными?

Last updated on 2025-08-20

Поставщик конфигурации JavaScript

Конфигурация загрузки

Использование конфигурации

Обработка типов контента JSON

Загрузка определенных значений ключей с помощью селекторов

Фильтры тегов

Удалить префикс из ключей

Обновление конфигурации

Настраиваемый обратный вызов для обновления

Обновление ключа "сторож"

Флаг функции

Управление функциями

Справочник по Key Vault

Параллельное секретное разрешение

Обновление секрета Key Vault

Снимок

Справочник по моментальным снимкам

Повторная попытка запуска

Георепликация

Подключение к Azure Front Door

Следующие шаги

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

Дополнительные ресурсы