適用於 JavaScript 的應用程式設定用戶端連結庫

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

使用應用程式群組態的用戶端連結庫來：

• 建立彈性索引鍵表示法和對應
• 使用標籤索引鍵
• 從任何時間點重新執行設定
• 管理應用程式設定的快照集

主要連結：

• 原始程式碼
• 套件 （NPM）
• API 參考檔
• 產品檔
• 範例

開始

安裝套件

npm install @azure/app-configuration

目前支持的環境

• 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

const azureIdentity = require("@azure/identity");
const appConfig = require("@azure/app-configuration");

const credential = new azureIdentity.DefaultAzureCredential();
const client = new appConfig.AppConfigurationClient(
  endpoint, // ex: <https://<your appconfig resource>.azconfig.io>
  credential
);

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

主權雲端

若要向 主權雲端中的資源進行驗證，您必須在認證選項中或透過 AZURE_AUTHORITY_HOST 環境變數來設定 authorityHost。

const { AppConfigurationClient } = require("@azure/app-configuration");
const { DefaultAzureCredential, AzureAuthorityHosts } = require("@azure/identity");

// Create an AppConfigurationClient that will authenticate through AAD in the China cloud
const client = new AppConfigurationClient(
  endpoint, // ex: <https://<your appconfig resource>.azconfig.azure.cn>
  new DefaultAzureCredential({ authorityHost: AzureAuthorityHosts.AzureChina })
);

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

使用連接字串進行驗證

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

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

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

const client = new AppConfigurationClient("<connection string>");

重要概念

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

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

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

這表示此模式可運作：

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);

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

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

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

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

例子

建立並取得設定

const appConfig = require("@azure/app-configuration");

const client = new appConfig.AppConfigurationClient(
  "<App Configuration connection string goes here>"
);

async function run() {
  const newSetting = 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.
    // /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);
}

run().catch((err) => console.log("ERROR:", err));

建立快照集

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

const { AppConfigurationClient } = require("@azure/app-configuration");

const client = new AppConfigurationClient(
  "<App Configuration connection string goes here>"
);


async function run() {
  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();
}

run().catch((err) => console.log("ERROR:", err));

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

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

取得快照集

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

列出快照集中的 ConfigurationSetting

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

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

列出服務中的所有快照集

const snapshots = await client.listSnapshots();

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

復原和封存快照集

// 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：

const { setLogLevel } = require("@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 應用程式組態實例。 若要執行測試，您必須執行：

1. rush update
2. rush build -t @azure/app-configuration
3. 在 [sdk\appconfiguration\app-configuration] 資料夾中建立具有這些內容的 .env 檔案：APPCONFIG_CONNECTION_STRING=connection string for your App Configuration instance
4. cd sdk\appconfiguration\app-configuration
5. npm run test.

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

相關專案

• Microsoft Azure SDK for JavaScript
• Azure 應用程式組態