JavaScript 組態提供者

Azure 應用程式組態是一項受控服務，可協助開發人員簡單且安全地集中管理其應用程式組態。 JavaScript 組態提供者程式庫會以受控方式，從 Azure 應用程式組態存放區載入組態。此客戶端連結庫會在 Azure SDK for JavaScript 上方新增其他功能。

載入設定

load 套件中匯出的 @azure/app-configuration-provider 方法可用來從 Azure 應用程式組態載入組態。 load 方法可讓您使用 Microsoft Entra ID 或連接字串連線到應用程式組態存放區。

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 方法，從對應樣式資料結構擷取索引鍵/值的值。

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 內容類型處理

您可以在應用程式組態中建立 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");

附註

從 @azure/app-configuration-provider 的 2.2.0 版開始，組態提供者允許在具有 application/json 內容類型的索引鍵/值中撰寫註解，如 (JSONC) 中定義。

使用選取器載入特定索引鍵/值

根據預設，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 是不可操作的，因此即使頻繁呼叫，其對效能的影響也是最小的。

自訂重新整理回呼

onRefresh 方法可讓您自訂回呼函式，每次使用 Azure 應用程式組態存放區的變更成功更新本機組態時，就會叫用該函式。它會傳回可處置物件，您可以使用此物件來移除已註冊的回呼

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 索引鍵是您完成所有其他索引鍵變更之後才更新的索引鍵。組態提供者會監視 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 庫與組態提供者整合，以根據 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 應用程式組態支援參考儲存在 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，用來連線至沒有已註冊 SecretClient 的 Azure Key Vault。

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 應用程式組態可讓您設定與設定重新整理周期無關的秘密重新整理間隔。這對安全性至關重要，因為雖然應用程式組態中的 Key Vault 參考 URI 保持不變，但 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-09-11