你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

适用于 JavaScript 的 Azure 应用配置客户端库 - 版本 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);

可在此处找到有关的详细信息

主权云

要使用 Sovereign Cloud 中的资源进行身份验证，您需要在构造函数选项中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,
});

注意：如果未定义属性，则 audience SDK 将默认为 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 Native 支持

React Native 不支持此 SDK 库使用的一些 JavaScript API，因此你需要为它们提供填充。有关详细信息，请参阅我们的 React Native 示例和 Expo。

后续步骤

以下示例演示了与应用配置交互的各种方式：

helloworld.ts - 获取、设置和删除配置值。
helloworldWithLabels.ts - 使用标签为测试版与生产等方案设置添加其他维度。
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