Поставщик конфигурации 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();

Эта конструкция предотвращает ненужные запросы на Конфигурация приложений при простое приложения. Необходимо включить 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 этот параметр включен и селектор не указан, поставщик конфигурации загружает все флаги компонентов без метки из хранилища Конфигурация приложений.

Это важно

Чтобы эффективно использовать флаги компонентов, загруженные из конфигурации приложений 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 fm = 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 так же, как и для других ключей, хранящихся в Конфигурация приложений. Так как клиент распознает ключи как ссылки на 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 App Configuration позволяет настраивать интервалы обновления секретных данных независимо от цикла обновления конфигурации. Это важно для безопасности, так как в то время как URI ссылки 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" }
        ]
    }
});

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

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

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

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

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

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

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

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

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

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

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

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

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

Last updated on 2025-08-20

Поделиться через

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

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

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

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

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

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

Обрезка префикса из ключей

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

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

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

Флаг функции

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

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

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

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

Снимок

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

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

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

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

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