JavaScript 的 Azure App 配置客户端库
Azure App 配置 是一种管理服务,帮助开发人员简单地和安全地集中其应用程序和功能设置.
密钥链接 :
选择正确的软件包
使用 @ azure/ app- 配置 (本图书馆)改为:
- 在 Azure App 配置中管理配置设置和快照
- 执行正常配置消耗范围以外的颗粒读取
大多数应用程序应该从 @ azure/ app- configration- 提供者 库,它基于这个低级客户端库,是运行时消费配置的建议方式. 它补充说:
- 使用配置作为密钥/ 值图或结构化 JSON 对象的灵活访问模式
- 解析应用程序配置的查询机制
- 运行时刷新配置
- 具有高可靠性的缓存、复制发现、故障和负载平衡
- 密钥库参考解析和自动更新
- 特性旗集成 @ 微软/ 地貌管理 图书馆
欲了解更多信息,请前往 配置提供者概览。 。 。 .
开始
安装软件包
npm install @azure/app-configuration
说明: 对于申请 只需要读取配置值我们建议使用 @ azure/ app- configration- 提供者 图书馆.
目前得到支持的环境
- 节点.js的LTS版本
- Safari,Chrome,Edge,和Firefox的最新版本.
看我们的 支助政策 更多细节.
先决条件
创建 App 配置资源
你可以用这个 Azure 门户 或 阿苏尔CLI 创建 Azure App 配置资源.
示例(Azure CLI):
az appconfig create --name <app-configuration-resource-name> --resource-group <resource-group-name> --location eastus
认证客户端
AppConfigation 客户端可以使用 服务本金 或使用 连接字符串。 。 。 .
使用服务本金认证
通过服务本金进行认证的方式如下:
- 使用
@azure/identity软件包. - 在您的配置资源上设定相应的 RBAC 规则 . 关于 App 配置角色的更多信息可以找到 这里。 。 。 .
使用 默认标记
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 可见 这里
主权云
用资源认证 a 主权云,您需要设置 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 Public Cloud .
正在使用连接字符串认证
要得到小学 连接字符串 对于 App 配置资源, 您可以使用此 Azure CLI 命令 :
az appconfig credential list -g <resource-group-name> -n <app-configuration-resource-name> --query "([?name=='Primary'].connectionString)[0]"
您可以在代码中创建您的 App 配置客户端 连接字符串 你从AzureCLI得到:
import { AppConfigurationClient } from "@azure/app-configuration";
const connectionString = "Endpoint=https://example.azconfig.io;XXX=YYYY;YYY=ZZZZ";
const client = new AppConfigurationClient(connectionString);
关键概念
这个 AppConfigurationClient 从门户网站的 App 配置中有一些术语变化 .
- 键/等值对表示为
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版本支持配置快照:不可变,即时复制一个配置商店. 可使用确定快照中包含哪些密钥值对的过滤器来创建快照,从而创建一个由配置库构成的不可改变的视图. 这个特性使应用程序能够持有一致的配置视图,确保不会因为更新时的读取而使版本不匹配到单个设置. 例如,这个功能可用于在App配置中创建"释放配置快照". 见 页:1 创建并获得快照 节 以下文为例.
实例
说明: 如果您的应用程序仅需要检索配置值而不需要执行配置设置上的创建、更新或删除操作,请考虑使用 @ azure/ app- configration- 提供者 图书馆。 提供者库为在运行时加载配置数据提供了简化的经验 其他特性您可以在 Azure App 配置文档中找到许多代码样本 微软学习。 。 。 .
创建并获得一个设置
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/ logger 包文件。 。 。 .
反应原生支持
React Introduct不支持这个SDK库使用的一些JavaScript API,所以需要为他们提供多填充. 请看我们的 以 Expo 反应原生样本 更多细节.
今后的步骤
下列样本显示您可以与 App 配置交互的各种方式 :
helloworld.ts- 获取、设定和删除配置值.helloworldWithLabels.ts- 使用标签在设置中添加额外的维度,以适应 beta vs 生产等情况.optimisticConcurrencyViaEtag.ts- 使用etags设定值,以防止意外覆盖.setReadOnlySample.ts- 标记设置为只读,以防止修改.getSettingOnlyIfChanged.ts- 得到一个设定,除非它改变 从上次你得到它.listRevisions.ts- 列出一个密钥的修订, 允许您看到以前的值和设定时的值 .secretReference.ts- 秘密参考 代表一个配置设置, 引用为 KeyVault 密钥 .snapshot.ts- 创建、列表配置设置和归档快照.featureFlag.ts- 特性标记是遵循特定 JSON 值的设置.
更深入的例子可见于本报告 样本 gitHub 上的文件夹.
捐款
如果您想为图书馆捐钱 请读一下 贡献指南 学习如何构建和测试密码.
这个模块的测试是现场测试和单元测试的混合,这需要您有一个Azure App配置实例. 执行测试需要运行:
pnpm installpnpm build --filter @azure/app-configuration...- 创建 .env 文件,其中包含这些内容
sdk\appconfiguration\app-configuration文件夹 :APPCONFIG_CONNECTION_STRING=connection string for your App Configuration instance cd sdk\appconfiguration\app-configurationnpm run test。 。 。 .
查看我们的 测试 详细文件夹.