共用方式為

適用於 JavaScript 的 應用程式組態 用戶端連結庫

  • 發行項

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

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

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

重要連結：

開始使用

安裝套件

npm install @azure/app-configuration

目前支援的環境

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

必要條件

建立 應用程式組態 資源

您可以使用 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 ，請參閱 這裡

Sovereign Clouds

若要向主權雲端中的資源進行驗證，您必須在認證選項或透過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"
  });

  let 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列出快照中的

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

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

列出服務中的所有快照集

let snapshots = await client.listSnapshots();

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

復原和封存快照集

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

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

疑難排解

記錄

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

const { setLogLevel } = require("@azure/logger");

setLogLevel("info");

如需如何啟用記錄的詳細指示，可參閱 @azure/logger 套件文件。

React Native支援

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

下一步

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

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

參與

如果您希望向此程式庫投稿，請參閱投稿指南，深入瞭解如何組建與測試程式碼。

本課程模組的測試是即時和單元測試的混合，需要您擁有 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.

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

曝光數