JavaScript 構成プロバイダー

2025-06-09

Azure App Configuration は、開発者がアプリケーション構成を単純かつ安全に一元化するのに役立つマネージドサービスです。 JavaScript 構成プロバイダーライブラリを使用すると、管理された方法で Azure App Configuration ストアから構成を読み込めます。このクライアントライブラリは、Azure SDK for JavaScript の上に追加機能を追加します。

構成の読み込み

load パッケージにエクスポートされた @azure/app-configuration-provider メソッドは、Azure App Configuration から構成を読み込むために使用されます。 load メソッドを使用すると、Microsoft Entra ID または接続文字列を使用して App Configuration ストアに接続できます。

Microsoft Entra ID
接続文字列

DefaultAzureCredential を使って、App Configuration ストアに対する認証を行います。手順に従い、あなたの資格情報にApp Configuration データリーダー役割を割り当ててください。

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 メソッドを提供します。

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 メソッドを提供します。省略可能な 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 コンテンツタイプの処理

App Configuration で JSON キー値を作成できます。 Azure App Configuration からキー値を読み込むと、構成プロバイダーは有効な JSON コンテンツタイプ (アプリケーション/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");

セレクターを使用して特定のキー値を読み込む

既定では、load メソッドは、構成ストアからラベルのないすべての構成を読み込みます。 load 型の省略可能なパラメーターを使用して、 AzureAppConfigurationOptions メソッドの動作構成できます。

App Configuration ストアから読み込まれた構成を調整または展開するには、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 starting with "dev" label"
            labelFilter: "dev*"
        }
    ]
});

注

キー値は、セレクターが一覧表示される順序で読み込まれます。複数のセレクターが同じキーを持つキー値を取得する場合、最後のセレクターの値は、以前に読み込まれた値をオーバーライドします。

キーからプレフィックスをトリミングする

トリミングされたキープレフィックスの一覧を AzureAppConfigurationOptions.trimKeyPrefixes プロパティに指定して、キーのプレフィックスをトリミングできます。

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

構成の更新

構成の動的更新を使用すると、アプリケーションを再起動しなくても、App Configuration ストアから最新の値をプルできます。 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();
})

何らかの理由で更新呼び出しが失敗した場合でも、アプリケーションはキャッシュされた構成を使い続けます。構成されている更新間隔が経過し、アプリケーションのアクティビティによって更新呼び出しがトリガーされると、もう 1 回試行されます。構成されている更新間隔が経過するまでは、refresh を呼び出しても何も行われないので、頻繁に呼び出された場合でも、パフォーマンスへの影響は最小限です。

カスタム更新コールバック

onRefresh メソッドを使用すると、ローカル構成が Azure App Configuration ストアからの変更で正常に更新されるたびに呼び出されるカスタムコールバック関数を使用できます。これは、登録済みのコールバックを削除するために使用できる破棄可能なオブジェクトを返します

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 App Configuration で機能フラグを作成できます。既定では、機能フラグは構成プロバイダーによって読み込まれません。 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 App Configuration から読み込まれた機能フラグを効果的に使用して管理するには、 @microsoft/feature-management パッケージをインストールして使用します。このライブラリは、アプリケーションの機能動作を制御するための構造化された方法を提供します。

機能の管理

機能管理ライブラリでは、機能フラグに基づいてアプリケーション機能を開発および公開する方法が提供されます。機能管理ライブラリは、構成プロバイダーライブラリと組み合わせて動作するように設計されています。構成プロバイダーは、選択したすべての機能フラグを、feature_flags セクションの feature_management 一覧の下の構成に読み込みます。機能管理ライブラリは、アプリケーションに読み込まれた機能フラグを使用して管理します。

次の例では、 @microsoft/feature-management ライブラリを構成プロバイダーと統合し、 Beta 機能フラグの状態に基づいて Express アプリケーションの API アクセシビリティを動的に制御する方法を示します。

// 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 App Configuration は、Azure Key Vault に格納されているシークレットの参照をサポートします。 App Configuration では、Key Vault に格納されているシークレットにマップされるキーを作成できます。シークレットは Key Vault に安全に格納されますが、読み込まれた他の構成と同様にアクセスできます。

構成プロバイダーライブラリは、App Configuration に格納されている他のキーの場合と同様に、Key Vault 参照を取得します。クライアントはキーを Key Vault 参照として認識するため、一意のコンテンツタイプを持ち、クライアントは Key Vault に接続してアプリケーションの値を取得します。構成プロバイダーが Azure Key Vault に接続できるようにするには、適切な資格情報で AzureAppConfigurationOptions.KeyVaultOptions プロパティを構成する必要があります。

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 には、1 つの要求で複数のシークレットを取得するためのバッチ 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を構成できます。

スナップショット

スナップショットは、App Configuration ストアのキー値の名前付き不変サブセットです。スナップショットを構成する Key-Value は、作成時にキーフィルターとラベルフィルターを使用して選択されます。スナップショットが作成されると、その中の Key-Value は変更されないことが保証されます。

スナップショットセレクターを使用して、スナップショットからキー値または機能フラグを読み込むことができます。

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 App Configuration プロバイダーは、初期構成の読み込み中に堅牢な再試行メカニズムを実装します。これにより、起動の成功を妨げる可能性がある一時的なネットワークの問題からアプリケーションを保護できます。

この動作は、 AzureAppConfigurationOptions.startupOptionsを使用してカスタマイズできます。

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

geo レプリケーション

geo レプリケーションの使用については、「geo レプリケーションを有効にする」を参照してください。

次のステップ

JavaScript 構成プロバイダーの使用方法については、次のチュートリアルに進んでください。

JavaScript で動的構成を使用する

JavaScript 機能管理ライブラリの使用方法については、次のドキュメントに進んでください。

JavaScript 機能管理