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

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

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

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

Microsoft Entra ID

Вы используете 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 settings = await load(endpoint, credential);
    console.log('settings.get("message"):', settings.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 settings = await load(connectionString);
    console.log('settings.get("message"):', settings.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 settings = await load(endpoint, credential);
  const fontSize = settings.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 settings = await load(endpoint, credential);
  const settingsObj = settings.constructConfigurationObject({separator: ":"});
  const fontSize1 = settings.get("app:font:size"); // map-style configuration representation
  const fontSize2 = settingsObj.app.font.size; // object-style configuration representation
  

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

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

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

const settings = 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 starting with "dev" label"
            labelFilter: "dev*"
        }
    ]
});

Примечание.

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

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

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

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

Справочник по 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 settings = await load(endpoint, credential, {
    keyVaultOptions: {
        credential: credential
    }
});

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

const { SecretClient } = require("@azure/keyvault-secrets");

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

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

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

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

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

const settings = 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
settings.refresh();

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

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

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

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

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

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

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

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

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

Флаг функции

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

const settings = await load(endpoint, credential, {
    featureFlagOptions: {
        enabled: true,
        selectors: [ { keyFilter: "*", labelFilter: "Prod" } ],
        refresh: {
            enabled: true, // the refresh for feature flags need to be enbaled in addition to key-values
            refreshIntervalInMs: 10_000
        }
    }
});

Примечание.

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

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

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

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

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

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

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

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

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