Azure App Configuration TypeScript SDK

azure-appconfiguration-ts

分类通用

作者Agentic Awesome Skills 社区

许可MIT

评分4.30/5

使用2.8K

Azure App Configuration TypeScript SDK

支持功能标志和动态刷新的集中式配置管理。

安装

bash

# 低级 CRUD SDK
npm install @azure/app-configuration @azure/identity
高级提供程序 (推荐用于应用程序)
npm install @azure/app-configuration-provider @azure/identity
功能标志管理
npm install @microsoft/feature-management

环境变量

bash

AZURE_APPCONFIG_ENDPOINT=https://<your-resource>.azconfig.io
或者
AZURE_APPCONFIG_CONNECTION_STRING=Endpoint=https://...;Id=...;Secret=...

身份验证

typescript

import { AppConfigurationClient } from "@azure/app-configuration";
import { DefaultAzureCredential } from "@azure/identity";
// DefaultAzureCredential (推荐)
const client = new AppConfigurationClient(
  process.env.AZURE_APPCONFIG_ENDPOINT!,
  new DefaultAzureCredential()
);
// 连接字符串
const client2 = new AppConfigurationClient(
  process.env.AZURE_APPCONFIG_CONNECTION_STRING!
);

CRUD 操作

创建/更新设置

typescript

// 添加新设置 (如果已存在则失败)
await client.addConfigurationSetting({
  key: "app:settings:message",
  value: "Hello World",
  label: "production",
  contentType: "text/plain",
  tags: { environment: "prod" },
});
// 设置 (创建或更新)
await client.setConfigurationSetting({
  key: "app:settings:message",
  value: "Updated value",
  label: "production",
});
// 使用乐观并发更新
const existing = await client.getConfigurationSetting({ key: "myKey" });
existing.value = "new value";
await client.setConfigurationSetting(existing, { onlyIfUnchanged: true });

读取设置

typescript

// 获取单个设置
const setting = await client.getConfigurationSetting({
  key: "app:settings:message",
  label: "production",  // 可选
});
console.log(setting.value);
// 带过滤条件的列表
const settings = client.listConfigurationSettings({
  keyFilter: "app:*",
  labelFilter: "production",
});
for await (const setting of settings) {
  console.log(${setting.key}: ${setting.value});
}

删除设置

typescript

await client.deleteConfigurationSetting({
  key: "app:settings:message",
  label: "production",
});

锁定/解锁 (只读)

typescript

// 锁定
await client.setReadOnly({ key: "myKey", label: "prod" }, true);
// 解锁
await client.setReadOnly({ key: "myKey", label: "prod" }, false);

App Configuration 提供程序

加载配置

typescript

import { load } from "@azure/app-configuration-provider";
import { DefaultAzureCredential } from "@azure/identity";
const appConfig = await load(
  process.env.AZURE_APPCONFIG_ENDPOINT!,
  new DefaultAzureCredential(),
  {
    selectors: [
      { keyFilter: "app:*", labelFilter: "production" },
    ],
    trimKeyPrefixes: ["app:"],
  }
);
// Map 风格访问
const value = appConfig.get("settings:message");
// 对象风格访问
const config = appConfig.constructConfigurationObject({ separator: ":" });
console.log(config.settings.message);

动态刷新

typescript

const appConfig = await load(endpoint, credential, {
  selectors: [{ keyFilter: "app:*" }],
  refreshOptions: {
    enabled: true,
    refreshIntervalInMs: 30_000,  // 30 秒
  },
});
// 触发刷新

h (非阻塞)
appConfig.refresh();

// 监听刷新事件
const disposer = appConfig.onRefresh(() => {
console.log("配置已刷新！");
});

// Express 中间件模式
app.use((req, res, next) => {
appConfig.refresh();
next();
});

code

### Key Vault 引用

typescript
const appConfig = await load(endpoint, credential, {
selectors: [{ keyFilter: "app:*" }],
keyVaultOptions: {
credential: new DefaultAzureCredential(),
secretRefreshIntervalInMs: 7200_000, // 2 小时
},
});

// 机密会自动解析
const dbPassword = appConfig.get("database:password");

code

## 功能标志 (Feature Flags)
创建功能标志 (低级 API)

typescript import { featureFlagPrefix, featureFlagContentType, FeatureFlagValue, ConfigurationSetting, } from "@azure/app-configuration";

const flag: ConfigurationSetting<FeatureFlagValue> = {
key: ${featureFlagPrefix}Beta,
contentType: featureFlagContentType,
value: {
id: "Beta",
enabled: true,
description: "Beta 功能",
conditions: {
clientFilters: [
{
name: "Microsoft.Targeting",
parameters: {
Audience: {
Users: ["[email protected]"],
Groups: [{ Name: "beta-testers", RolloutPercentage: 50 }],
DefaultRolloutPercentage: 0,
},
},
},
],
},
},
};

await client.addConfigurationSetting(flag);

code

### 加载并评估功能标志

typescript
import { load } from "@azure/app-configuration-provider";
import {
ConfigurationMapFeatureFlagProvider,
FeatureManager,
} from "@microsoft/feature-management";

const appConfig = await load(endpoint, credential, {
featureFlagOptions: {
enabled: true,
selectors: [{ keyFilter: "*" }],
refresh: {
enabled: true,
refreshIntervalInMs: 30_000,
},
},
});

const featureProvider = new ConfigurationMapFeatureFlagProvider(appConfig);
const featureManager = new FeatureManager(featureProvider);

// 简单检查
const isEnabled = await featureManager.isEnabled("Beta");

// 带有目标上下文的检查
const isEnabledForUser = await featureManager.isEnabled("Beta", {
userId: "[email protected]",
groups: ["beta-testers"],
});

code

## 快照 (Snapshots)

typescript
// 创建快照
const snapshot = await client.beginCreateSnapshotAndWait({
name: "release-v1.0",
retentionPeriod: 2592000, // 30 天
filters: [{ keyFilter: "app:*", labelFilter: "production" }],
});

// 获取快照
const snap = await client.getSnapshot("release-v1.0");

// 列出快照中的设置
const settings = client.listConfigurationSettingsForSnapshot("release-v1.0");
for await (const setting of settings) {
console.log(${setting.key}: ${setting.value});
}

// 归档/恢复
await client.archiveSnapshot("release-v1.0");
await client.recoverSnapshot("release-v1.0");

// 从快照加载 (provider)
const config = await load(endpoint, credential, {
selectors: [{ snapshotName: "release-v1.0" }],
});

code

## 标签 (Labels)

typescript
// 创建带有标签的设置
await client.setConfigurationSetting({
key: "database:host",
value: "dev-db.example.com",
label: "development",
});

await client.setConfigurationSetting({
key: "database:host",
value: "prod-db.example.com",
label: "production",
});

// 按标签过滤
const prodSettings = client.listConfigurationSettings({
keyFilter: "*",
labelFilter: "production",
});

// 无标签 (null 标签)
const noLabelSettings = cli

typescript

ent.listConfigurationSettings({
  labelFilter: "\0",
});
// 列出可用标签
for await (const label of client.listLabels()) {
  console.log(label.name);
}

关键类型

typescript

import {
  AppConfigurationClient,
  ConfigurationSetting,
  FeatureFlagValue,
  SecretReferenceValue,
  featureFlagPrefix,
  featureFlagContentType,
  secretReferenceContentType,
  ListConfigurationSettingsOptions,
} from "@azure/app-configuration";
import { load } from "@azure/app-configuration-provider";
import {
  FeatureManager,
  ConfigurationMapFeatureFlagProvider,
} from "@microsoft/feature-management";

最佳实践

1. 应用端使用 provider - 运行时配置请使用 @azure/app-configuration-provider
2. 管理端使用低级 SDK - CRUD 操作请使用 @azure/app-configuration
3. 启用刷新 - 用于动态配置更新
4. 使用标签 (Labels) - 按环境隔离配置
5. 使用快照 (Snapshots) - 用于不可变的发布配置
6. 哨兵模式 (Sentinel pattern) - 使用哨兵键触发全量刷新
7. RBAC 角色 - 只读访问请使用 App Configuration Data Reader

适用场景

本技能适用于执行概览中所描述的工作流或操作。

局限性

仅在任务明确符合上述范围时使用此技能。

不要将输出结果视为针对特定环境的验证、测试或专家评审的替代方案。

如果缺失必要的输入、权限、安全边界或成功标准，请停止操作并请求澄清。

Azure App Configuration TypeScript SDK

Azure App Configuration TypeScript SDK

安装

高级提供程序 (推荐用于应用程序)

功能标志管理

环境变量

或者

身份验证

CRUD 操作

创建/更新设置

读取设置

删除设置

锁定/解锁 (只读)

App Configuration 提供程序

加载配置

动态刷新

`创建功能标志 (低级 API)`

关键类型

最佳实践

适用场景

局限性

扫码进交流群