Azure App Configuration客户端库

Azure App Configuration是一种托管服务，帮助开发人员简单、安全地将应用程序配置集中管理。

现代程序，尤其是运行在云中的程序，通常有许多本质上分布式的组件。在应用程序部署过程中，将这些组件的配置设置分散可能导致难以调试的错误。使用App Configuration在同一个地方安全存储您应用程序的所有设置。

使用App Configuration客户端库创建和管理应用程序配置设置。

源代码 | 包（Pypi） | 包（Conda） | API参考文档 | 产品文档

入门

安装包

使用pip安装Python的Azure App Configuration客户端库

pip install azure-appconfiguration

先决条件

• 使用此包需要 Python 3.8 或更高版本。
• 您需要一个Azure 订阅以及一个配置存储。

要创建配置存储，您可以使用 Azure Portal 或Azure CLI。

之后，创建配置存储

az appconfig create --name <config-store-name> --resource-group <resource-group-name> --location eastus

客户端认证

为了与 App 配置服务交互，您需要创建AzureAppConfigurationClient类的实例。为此，您可以使用配置存储的连接字符串或使用 AAD 令牌。

使用连接字符串

获取凭证

使用以下Azure CLI片段从配置存储获取连接字符串。

az appconfig credential list --name <config-store-name>

或者，从 Azure Portal 获取连接字符串。

创建客户端

一旦您获取了连接字符串的值，您就可以创建 AzureAppConfigurationClient。

import os
from azure.appconfiguration import AzureAppConfigurationClient

CONNECTION_STRING = os.environ["APPCONFIGURATION_CONNECTION_STRING"]

# Create app config client
client = AzureAppConfigurationClient.from_connection_string(CONNECTION_STRING)

使用 AAD 令牌

这里演示了使用DefaultAzureCredential以服务主体身份进行认证。然而，AzureAppConfigurationClient接受任何azure-identity凭证。有关其他凭证的更多信息，请参阅azure-identity文档。

创建服务主体（可选）

以下Azure CLI片段显示了如何创建新的服务主体。在使用之前，将“your-application-name”替换为您服务主体的适当名称。

创建服务主体

az ad sp create-for-rbac --name http://my-application --skip-assignment

输出

{
    "appId": "generated app id",
    "displayName": "my-application",
    "name": "http://my-application",
    "password": "random password",
    "tenant": "tenant id"
}

使用输出设置环境变量 AZURE_CLIENT_ID（"appId" 上方）、AZURE_CLIENT_SECRET（"password" 上方）和 AZURE_TENANT_ID（"tenant" 上方）。以下示例显示了在 Bash 中执行此操作的方法

export AZURE_CLIENT_ID="generated app id"
export AZURE_CLIENT_SECRET="random password"
export AZURE_TENANT_ID="tenant id"

将适用App 配置角色之一分配给服务主体。

创建客户端

一旦设置了 AZURE_CLIENT_ID、AZURE_CLIENT_SECRET 和 AZURE_TENANT_ID 环境变量，DefaultAzureCredential 将能够认证 AzureAppConfigurationClient。

构造客户端还需要您的配置存储的 URL，您可以从 Azure CLI 或 Azure Portal 获取。在 Azure Portal 中，URL 可在服务 "端点" 列表中找到。

from azure.identity import DefaultAzureCredential
from azure.appconfiguration import AzureAppConfigurationClient

credential = DefaultAzureCredential()

client = AzureAppConfigurationClient(base_url="your_endpoint_url", credential=credential)

关键概念

配置设置

配置设置是配置存储中的基本资源。在其最简单的形式中，它是一个键和一个值。然而，还有其他属性，如可修改的内容类型和标签字段，允许以不同的方式解释或关联值。

配置设置的标签属性提供了一种将配置设置分离为不同维度的方法。这些维度由用户定义，可以采取任何形式。一些常用的标签维度示例包括区域、语义版本或环境。许多应用程序都需要一组配置密钥，这些密钥具有随应用程序在不同维度存在而变化的值。

例如，MaxRequests 可能是 "NorthAmerica" 中的 100，而在 "WestEurope" 中是 200。通过创建名为 MaxRequests 的配置设置，带有 "NorthAmerica" 标签，并在 "WestEurope" 标签中创建另一个只具有不同值的配置设置，应用程序可以在这两个维度上无缝检索配置设置。

配置设置的属性

key : str
label : str
content_type : str
value : str
last_modified : str
read_only : bool
tags : dict
etag : str

快照

Azure App Configuration 允许用户创建配置存储的某个时间点的快照，使他们能够将设置视为一个一致的版本。此功能使应用程序能够保持一致的配置视图，确保由于读取更新而不会出现单个设置的版本不匹配。快照是不可变的，确保在出现问题时可以自信地将配置回滚到最后已知的好配置。

示例

以下部分提供了一些代码片段，涵盖了配置服务的一些常见任务，包括

• 创建配置设置
• 获取配置设置
• 删除配置设置
• 列出配置设置
• 创建快照
• 获取快照
• 存档快照
• 恢复快照
• 列出快照
• 列出快照的配置设置
• 异步API

创建配置设置

创建要存储在配置存储中的配置设置。存储配置设置有两种方式

• add_configuration_setting仅在设置在存储中不存在时才创建设置。

config_setting = ConfigurationSetting(
    key="MyKey", label="MyLabel", value="my value", content_type="my content type", tags={"my tag": "my tag value"}
)
added_config_setting = client.add_configuration_setting(config_setting)

• set_configuration_setting如果设置不存在或覆盖现有设置，则创建设置。

added_config_setting.value = "new value"
added_config_setting.content_type = "new content type"
updated_config_setting = client.set_configuration_setting(added_config_setting)

设置和清除配置设置的只读属性。

• 将配置设置设置为只读。

read_only_config_setting = client.set_read_only(updated_config_setting)

• 清除配置设置的只读属性。

read_write_config_setting = client.set_read_only(updated_config_setting, False)

获取配置设置

获取先前存储的配置设置。

fetched_config_setting = client.get_configuration_setting(key="MyKey", label="MyLabel")

删除配置设置

删除现有配置设置。

client.delete_configuration_setting(key="MyKey", label="MyLabel")

列出配置设置

通过标签过滤器、键过滤器或标签过滤器过滤列出所有配置设置。

config_settings = client.list_configuration_settings(key_filter="MyKey*", tags_filter=["my tag1=my tag1 value"])
for config_setting in config_settings:
    print(config_setting)

列出修订记录

列出通过标签过滤器、键过滤器或标签过滤器过滤的配置设置的修订历史记录。

items = client.list_revisions(key_filter="MyKey", tags_filter=["my tag=my tag value"])
for item in items:
    print(item)

列出标签

列出所有配置设置的标签。

print("List all labels in resource")
config_settings = client.list_labels()
for config_setting in config_settings:
    print(config_setting)

print("List labels by exact match")
config_settings = client.list_labels(name="my label1")
for config_setting in config_settings:
    print(config_setting)

print("List labels by wildcard")
config_settings = client.list_labels(name="my label*")
for config_setting in config_settings:
    print(config_setting)

创建快照

from azure.appconfiguration import ConfigurationSettingsFilter

filters = [ConfigurationSettingsFilter(key="my_key1", label="my_label1")]
response = client.begin_create_snapshot(name=snapshot_name, filters=filters)
created_snapshot = response.result()

获取快照

received_snapshot = client.get_snapshot(name=snapshot_name)

存档快照

archived_snapshot = client.archive_snapshot(name=snapshot_name)

恢复快照

recovered_snapshot = client.recover_snapshot(name=snapshot_name)

列出快照

for snapshot in client.list_snapshots():
    print(snapshot)

列出快照的配置设置

for config_setting in client.list_configuration_settings(snapshot_name=snapshot_name):
    print(config_setting)

异步API

支持异步客户端。要使用异步客户端库，从包 azure.appconfiguration.aio 导入 AzureAppConfigurationClient，而不是 azure.appconfiguration。

import os
from azure.appconfiguration.aio import AzureAppConfigurationClient

CONNECTION_STRING = os.environ["APPCONFIGURATION_CONNECTION_STRING"]

# Create an app config client
client = AzureAppConfigurationClient.from_connection_string(CONNECTION_STRING)

此异步 AzureAppConfigurationClient 与同步的具有相同的函数签名，只是它们是异步的。
例如，异步检索配置设置

fetched_config_setting = await client.get_configuration_setting(key="MyKey", label="MyLabel")

要列出配置设置，同步调用 list_configuration_settings 操作，并异步迭代返回的异步迭代器

config_settings = client.list_configuration_settings(key_filter="MyKey*", tags_filter=["my tag1=my tag1 value"])
async for config_setting in config_settings:
    print(config_setting)

故障排除

有关如何诊断各种故障场景的详细信息，请参阅故障排除指南。

下一步

更多示例代码

此GitHub存储库中提供了几个App Configuration客户端库示例。这包括

• Hello world / 异步版本
• 列出配置设置 / 异步版本
• 将配置设置设置为只读 / 异步版本
• 读取修订历史记录 / 异步版本
• 获取已更改的设置 / 异步版本
• 创建、检索和更新配置设置快照的状态 / 异步版本
• 发送自定义HTTP请求 / 异步版本
• 更新AzureAppConfigurationClient sync_token / 异步版本

有关更多详细信息，请参阅示例README。

贡献

本项目欢迎贡献和建议。大多数贡献都需要您同意贡献者许可协议（CLA），声明您有权，并且实际上确实授予我们使用您贡献的权利。有关详细信息，请访问https://cla.microsoft.com。

当您提交拉取请求时，CLA机器人将自动确定您是否需要提供CLA，并适当地装饰PR（例如，标签，注释）。只需按照机器人提供的说明操作。您在整个使用我们的CLA的仓库中只需这样做一次。

本项目采用了Microsoft开源代码行为准则。有关更多信息，请参阅代码行为准则常见问题解答或通过opencode@microsoft.com联系以提出任何其他问题或意见。

发布历史

1.7.1 (2024-08-22)

已修复的错误

• 修复了在ConfigurationSnapshot中序列化/反序列化标签筛选器的错误。

1.7.0 (2024-08-15)

新增功能

• 添加了列出配置设置标签的list_labels()操作。
• 在list_configuration_settings()和list_revisions()中支持按配置设置标签进行筛选。
• 在ConfigurationSettingsFilter中添加了新的属性tags，以支持使用标签筛选器筛选快照中的设置。

已修复的错误

• 修复了FeatureFlagConfigurationSetting的feature_id与客户字段id不同的问题，如果与FeatureFlagConfigurationSetting键后缀不同，可能会覆盖原始客户定义的值。

其他更改

• 将默认的api_version更新为"2023-11-01"。
• 发布了枚举LabelFields和模型ConfigurationSettingLabel。
• 发布了枚举SnapshotFields，并接受get_snapshot()和list_snapshots()中的fields参数的类型。
• 发布了枚举ConfigurationSettingFields，并接受list_configuration_settings()和list_revisions()中fields参数的类型。
• 发布了枚举SnapshotComposition，并接受ConfigurationSnapshot属性composition_type和begion_create_snapshot()关键字参数composition_type的类型。

1.6.0 (2024-04-09)

新增功能

• 在客户端中暴露了send_request()方法，以便使用客户端现有的管道发送自定义请求。
• 在按页迭代list_configuration_setting()结果时支持获取页ETag。

已修复的错误

• 修复了在同步操作set_configuration_setting()中消耗"etag"值时的错误。
• 将FeatureFlagConfigurationSetting中属性enabled的无效默认值None更改为False。
• 修复了在反序列化FeatureFlagConfigurationSetting对象时缺失description、display_name和其他客户字段的问题。

1.6.0b2 (2024-03-21)

已修复的错误

• 将FeatureFlagConfigurationSetting中属性enabled的无效默认值None更改为False。
• 修复了在反序列化FeatureFlagConfigurationSetting对象时缺失description、display_name和其他客户字段的问题。

1.6.0b1 (2024-03-14)

新增功能

• 在客户端中暴露了send_request()方法，以便使用客户端现有的管道发送自定义请求。
• 在按页迭代list_configuration_setting()结果时支持获取页ETag。

已修复的错误

• 修复了在同步操作set_configuration_setting()中消耗"etag"值时的错误。

1.5.0 (2023-11-09)

其他更改

• 支持在get_snapshot_configuration_settings()、list_snapshot_configuration_settings()和list_revisions()中使用关键字参数accept_datetime的datetime类型。
• 将azure-core的最小依赖项提升到>=1.28.0。
• 将默认的api_version更新为"2023-10-01"。
• 在set_read_only()中删除了etag关键字文档，因为它不再使用。
• 添加了对Python 3.12的支持。
• Python 3.7不再受支持。请使用Python版本3.8或更高版本。

1.5.0b3 (2023-10-10)

破坏性更改

• 将list_snapshot_configuration_settings()中的参数name重命名为snapshot_name。
• 从list_snapshot_configuration_settings()中删除了关键字参数accept_datetime。
• 将操作list_snapshot_configuration_settings()移动到list_configuration_settings()的重载中，并将参数snapshot_name移动到关键字参数。
• 发布了枚举SnapshotStatus，并在list_snapshots()中的status参数和Snapshot模型中的status属性中接受了类型。
• 将模型Snapshot重命名为ConfigurationSnapshot。
• 将模型ConfigurationSettingFilter重命名为ConfigurationSettingsFilter。

1.5.0b2（2023-08-02）

已修复的错误

• 修复了在filters属性为None时反序列化和序列化Snapshot的bug。
• 修复了从SDK创建FeatureFlagConfigurationSetting但门户中存在错误的bug。（#31326）

1.5.0b1（2023-07-11）

新增功能

• 添加了对Snapshot CRUD操作的支持。

已修复的错误

• 修复了异步update_sync_token()以使用async/await关键字。

其他更改

• 将azure-core的最低依赖项提升到>=1.25.0。
• 将默认的api_version更新为"2022-11-01-preview"。

1.4.0 (2022-02-13)

其他更改

• Python 2.7不再受支持。请使用Python版本3.7或更高版本。
• 将azure-core的最低依赖项提升到>=1.24.0。
• 将默认的异步传输从AsyncioRequestsTransport更改为当前azure-core中使用的传输（AioHttpTransport）。（#26427）
• 删除了msrest的要求。
• 添加了依赖项isodate，版本范围为>=0.6.0。

1.3.0 (2021-11-10)

已修复的错误

• 修复了根据不正确的模式/格式持久化数据的bug（#20518）

  在1.2.0中，SecretReferenceConfigurationSetting使用"secret_uri"而不是"uri"作为模式关键字，这破坏了SDK和门户之间SecretReferenceConfigurationSetting的交互。

  请

  • 使用1.3.0+进行任何SecretReferenceConfigurationSetting的使用。
  • 对现有的SecretReferenceConfigurationSetting调用获取方法，并将它们设置回正确的格式。

1.2.0 (2021-07-06)

新增功能

• 添加了FeatureFlagConfigurationSetting和SecretReferenceConfigurationSetting模型
• AzureAppConfigurationClient现在可以用作上下文管理器。
• 添加了update_sync_token()以从Event Grid通知中更新同步令牌。

1.2.0b2（2021-06-08）

功能

• 将同步和异步的AzureAppConfigurationClient添加了上下文管理器功能。

修复

• 修复了FeatureFlagConfigurationSetting和SecretReferenceConfigurationSetting的反序列化bug。

1.2.0b1（2021-04-06）

功能

• 添加了方法update_sync_token()以包括来自EventGrid通知的同步令牌。
• 添加了SecretReferenceConfigurationSetting类型，用于表示引用KeyVault密钥的配置设置。
• 添加了FeatureFlagConfigurationSetting类型，用于表示控制功能标志的配置设置。

1.1.1 (2020-10-05)

功能

• 如果连接字符串密钥有错误的填充，则改进了错误消息。（#14140）

1.1.0 (2020-09-08)

功能

• 为set_read_only()方法添加了匹配条件支持。（#13276）

1.0.1 (2020-08-10)

修复

• 文档和示例修复

1.0.0 (2020-01-06)

功能

• 添加了AAD身份验证支持。（#8924）

破坏性更改

• list_configuration_settings()和list_revisions()现在接受字符串键/标签过滤器，而不是键/标签列表。（#9066）

1.0.0b6（2019-12-03）

功能

• 添加了同步令牌支持。（#8418）

破坏性更改

• 合并了set_read_only和clear_read_only以使用set_read_only(True/False)。 （#8453）

1.0.0b5（2019-10-30）

破坏性更改

• delete_configuration_setting()的etag和match_condition现在是仅关键字参数。 （#8161）

1.0.0b4（2019-10-07）

• 添加了条件操作支持
• 添加了set_read_only()和clear_read_only()方法

1.0.0b3（2019-09-09）

• 新的Azure应用程序配置