適用於 JavaScript 的 Azure App Configuration 用戶端程式庫 - 1.10.0 版

Azure 應用程式組態是一項受控服務，可協助開發人員簡單且安全地集中處理其應用程式和功能設定。

主要連結：

選擇合適的套餐

使用 @azure/app-configuration （此程式庫）來：

在 Azure 應用程式設定中管理組態設定和快照集
執行在正常組態取用範圍之外運作的精細讀取

大部分的應用程式都應從 @azure/app-configuration-provider 程式庫開始，該程式庫以這個低階用戶端程式庫為基礎，是在執行階段取用設定的建議方式。它補充說：

使用組態作為索引鍵/值對應或結構化 JSON 物件的彈性存取模式
以宣告方式撰寫應用程式設定的查詢機制
執行階段期間的組態重新整理
快取、複本探索、容錯移轉和負載平衡的高可靠性
金鑰保存庫參考解析和自動重新整理
@microsoft/功能管理程式庫的功能旗標整合

如需詳細資訊，請移至組態提供者概觀。

開始

安裝套件

npm install @azure/app-configuration

便條： 對於 只需要讀取設定值的應用程式，建議改用 @azure/app-configuration-provider 程式庫。

目前支持的環境

LTS 版本的 Node.js
最新版的 Safari、Chrome、Edge 和 Firefox。

如需詳細資訊，請參閱我們的支持原則。

先決條件

Azure 訂用帳戶
應用程式組態資源

建立應用程式組態資源

您可以使用 Azure 入口網站或 Azure CLI 來建立 Azure 應用程式組態資源。

範例（Azure CLI）：

az appconfig create --name <app-configuration-resource-name> --resource-group <resource-group-name> --location eastus

驗證用戶端

AppConfigurationClient 可以使用服務主體或使用連接字串進行驗證。

使用服務主體進行驗證

透過服務主體進行驗證的方式如下：

使用 @azure/identity 套件建立認證。
在您的 AppConfiguration 資源上設定適當的 RBAC 規則。如需應用程式組態角色的詳細資訊，請參閱這裡。

使用 DefaultAzureCredential

import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

如需 @azure/identity 的詳細資訊，請參閱這裡

主權雲端

若要使用主權雲端中的資源進行驗證，您必須在建構函式選項中audience設定。AppConfigurationClient

import { AppConfigurationClient, KnownAppConfigAudience } from "@azure/app-configuration";
import { DefaultAzureCredential } from "@azure/identity";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.azure.cn";
// Create an AppConfigurationClient that will authenticate through AAD in the China cloud
const client = new AppConfigurationClient(endpoint, new DefaultAzureCredential(), {
  audience: KnownAppConfigAudience.AzureChina,
});

附註：如果未定義屬性，SDK audience 會預設為 Azure 公用雲端。

使用連接字串進行驗證

若要取得應用程式組態資源的主要 連接字串，您可以使用此 Azure CLI 命令：

az appconfig credential list -g <resource-group-name> -n <app-configuration-resource-name> --query "([?name=='Primary'].connectionString)[0]"

在程式代碼中，您現在可以使用您從 Azure CLI 取得連接字串來建立應用程式組態用戶端：

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

const connectionString = "Endpoint=https://example.azconfig.io;XXX=YYYY;YYY=ZZZZ";
const client = new AppConfigurationClient(connectionString);

重要概念

AppConfigurationClient 入口網站中的應用程式組態有一些術語變更。

索引鍵/值組會以 ConfigurationSetting 物件表示
鎖定和解除鎖定設定會顯示在 [isReadOnly] 字段中，您可以使用 setReadOnly切換。
快照集會以 ConfigurationSnapshot 物件表示。

用戶端遵循簡單的設計方法 - ConfigurationSetting 可以傳遞至採用 ConfigurationSettingParam 或 ConfigurationSettingId的任何方法。

這表示此模式可運作：

import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

const setting = await client.getConfigurationSetting({
  key: "hello",
});

setting.value = "new value!";
await client.setConfigurationSetting(setting);

// fields unrelated to just identifying the setting are simply
// ignored (for instance, the `value` field)
await client.setReadOnly(setting, true);

// delete just needs to identify the setting so other fields are
// just ignored
await client.deleteConfigurationSetting(setting);

或者，例如，重新取得設定：

import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

let setting = await client.getConfigurationSetting({
  key: "hello",
});

// re-get the setting
setting = await client.getConfigurationSetting(setting);

2022-11-01-preview API 版本支援設定快照集：設定存放區不可變的時間點複本。您可以使用篩選條件來建立快照集，以判斷快照集內包含哪些索引鍵/值組、建立不可變、組合的組態存放區檢視。這項功能可讓應用程式保留一致的組態檢視，確保因為讀取更新而與個別設定沒有版本不符。例如，這項功能可用來在應用程式組態內建立「發行組態快照集」。請參閱下列範例中的 建立和取得快照集 一節。

例子

便條： 如果您的應用程式只需要擷取組態值，而不需要對組態設定執行建立、更新或刪除作業，請考慮改用 @azure/app-configuration-provider 程式庫。提供者程式庫提供簡化的體驗，可在執行階段載入組態資料和其他功能。您可以在 Microsoft Learn 的 Azure 應用程式設定檔中找到許多程式碼範例。

建立並取得設定

import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

await client.setConfigurationSetting({
  key: "testkey",
  value: "testvalue",
  // Labels allow you to create variants of a key tailored
  // for specific use-cases like supporting multiple environments.
  // https://learn.microsoft.com/azure/azure-app-configuration/concept-key-value#label-keys
  label: "optional-label",
});

const retrievedSetting = await client.getConfigurationSetting({
  key: "testkey",
  label: "optional-label",
});

console.log("Retrieved value:", retrievedSetting.value);

建立快照集

beginCreateSnapshot 提供輪詢器來輪詢快照集建立。

import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

const key = "testkey";
const value = "testvalue";
const label = "optional-label";

await client.addConfigurationSetting({
  key,
  value,
  label,
});

const poller = await client.beginCreateSnapshot({
  name: "testsnapshot",
  retentionPeriod: 2592000,
  filters: [{ keyFilter: key, labelFilter: label }],
});
const snapshot = await poller.pollUntilDone();

您也可以使用 beginCreateSnapshotAndWait，在輪詢完成後直接建立結果。

import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

const key = "testkey";
const value = "testvalue";
const label = "optional-label";

const snapshot = await client.beginCreateSnapshotAndWait({
  name: "testsnapshot",
  retentionPeriod: 2592000,
  filters: [{ keyFilter: key, labelFilter: label }],
});

取得快照集

import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

const retrievedSnapshot = await client.getSnapshot("testsnapshot");
console.log("Retrieved snapshot:", retrievedSnapshot);

列出快照集中的 `ConfigurationSetting`

import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

const retrievedSnapshotSettings = await client.listConfigurationSettingsForSnapshot("testsnapshot");

for await (const setting of retrievedSnapshotSettings) {
  console.log(`Found key: ${setting.key}, label: ${setting.label}`);
}

列出服務中的所有快照集

import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

const snapshots = await client.listSnapshots();

for await (const snapshot of snapshots) {
  console.log(`Found snapshot: ${snapshot.name}`);
}

復原和封存快照集

import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

// Snapshot is in ready status
const archivedSnapshot = await client.archiveSnapshot("testsnapshot");
console.log("Snapshot updated status is:", archivedSnapshot.status);

// Snapshot is in archive status
const recoverSnapshot = await client.recoverSnapshot("testsnapshot");
console.log("Snapshot updated status is:", recoverSnapshot.status);

故障排除

伐木

啟用記錄可能有助於找出有關失敗的實用資訊。若要查看 HTTP 要求和回應的記錄，請將 AZURE_LOG_LEVEL 環境變數設定為 info。或者，您可以在運行時間啟用記錄，方法是在 setLogLevel中呼叫 @azure/logger：

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

如需如何啟用記錄的詳細指示，請參閱@azure/記錄器套件檔。

React 原生支援

React Native 不支援此 SDK 連結庫所使用的一些 JavaScript API，因此您需要為它們提供 polyfill。如需詳細資訊，請參閱我們的 React Native 範例與 Expo。

後續步驟

下列範例示範與應用程式組態互動的各種方式：

helloworld.ts - 取得、設定和刪除組態值。
helloworldWithLabels.ts - 使用標籤將其他維度新增至您的設定，例如 Beta 與生產環境。
optimisticConcurrencyViaEtag.ts - 使用 etag 設定值以防止意外覆寫。
setReadOnlySample.ts - 將設定標示為唯讀，以防止修改。
getSettingOnlyIfChanged.ts - 只有在上次取得設定變更時，才會取得設定。
listRevisions.ts - 列出索引鍵的修訂，讓您查看先前的值和設定時機。
secretReference.ts - SecretReference 代表參考為 KeyVault 秘密的組態設定。
snapshot.ts - 建立、列出組態設定和封存快照集。
featureFlag.ts - 功能旗標是值遵循特定 JSON 架構的設定。

您可以在 GitHub 上範例資料夾中找到更深入的範例。

貢獻

如果您想要參與此連結庫，請閱讀參與指南，以深入瞭解如何建置和測試程序代碼。

本課程模組的測試是即時和單元測試的混合，需要您擁有 Azure 應用程式組態實例。若要執行測試，您必須執行：

pnpm install
pnpm build --filter @azure/app-configuration...
在 [sdk\appconfiguration\app-configuration] 資料夾中建立具有這些內容的 .env 檔案：APPCONFIG_CONNECTION_STRING=connection string for your App Configuration instance
cd sdk\appconfiguration\app-configuration
npm run test。

如需詳細資訊，請檢視我們的測試資料夾。

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-11-13