Microsoft App Configuration Data Library for Python
Azure App Configuration is a managed service that helps developers centralize their application configurations simply and securely.
Modern programs, especially programs running in a cloud, generally have many components that are distributed in nature. Spreading configuration settings across these components can lead to hard-to-troubleshoot errors during an application deployment. Use App Configuration to securely store all the settings for your application in one place.
Use the client library for App Configuration to create and manage application configuration settings.
Source code | Package (Pypi) | Package (Conda) | API reference documentation | Product documentation
Azure SDK Python packages support for Python 2.7 has ended 01 January 2022. For more information and questions, please refer to https://github.com/Azure/azure-sdk-for-python/issues/20691 Python 3.7 or later is required to use this package. For more details, please refer to Azure SDK for Python version support policy.
Install the Azure App Configuration client library for Python with pip:
pip install azure-appconfiguration
To create a Configuration Store, you can use the Azure Portal or Azure CLI.
After that, create the Configuration Store:
az appconfig create --name <config-store-name> --resource-group <resource-group-name> --location eastus
In order to interact with the App Configuration service, you'll need to create an instance of the AzureAppConfigurationClient class. To make this possible, you can either use the connection string of the Configuration Store or use an AAD token.
Use the Azure CLI snippet below to get the connection string from the Configuration Store.
az appconfig credential list --name <config-store-name>
Alternatively, get the connection string from the Azure Portal.
Once you have the value of the connection string, you can create the 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)
Here we demonstrate using DefaultAzureCredential to authenticate as a service principal. However, AzureAppConfigurationClient accepts any azure-identity credential. See the azure-identity documentation for more information about other credentials.
This Azure CLI snippet shows how to create a new service principal. Before using it, replace "your-application-name" with the appropriate name for your service principal.
Create a service principal:
az ad sp create-for-rbac --name http://my-application --skip-assignment
Output:
{ "appId": "generated app id", "displayName": "my-application", "name": "http://my-application", "password": "random password", "tenant": "tenant id" }
Use the output to set AZURE_CLIENT_ID ("appId" above), AZURE_CLIENT_SECRET ("password" above) and AZURE_TENANT_ID ("tenant" above) environment variables. The following example shows a way to do this in Bash:
export AZURE_CLIENT_ID="generated app id"
export AZURE_CLIENT_SECRET="random password"
export AZURE_TENANT_ID="tenant id"
Assign one of the applicable App Configuration roles to the service principal.
Once the AZURE_CLIENT_ID, AZURE_CLIENT_SECRET and AZURE_TENANT_ID environment variables are set, DefaultAzureCredential will be able to authenticate the AzureAppConfigurationClient.
Constructing the client also requires your configuration store's URL, which you can get from the Azure CLI or the Azure Portal. In the Azure Portal, the URL can be found listed as the service "Endpoint"
from azure.identity import DefaultAzureCredential
from azure.appconfiguration import AzureAppConfigurationClient
credential = DefaultAzureCredential()
client = AzureAppConfigurationClient(base_url="your_endpoint_url", credential=credential)
A Configuration Setting is the fundamental resource within a Configuration Store. In its simplest form it is a key and a value. However, there are additional properties such as the modifiable content type and tags fields that allow the value to be interpreted or associated in different ways.
The Label property of a Configuration Setting provides a way to separate Configuration Settings into different dimensions. These dimensions are user defined and can take any form. Some common examples of dimensions to use for a label include regions, semantic versions, or environments. Many applications have a required set of configuration keys that have varying values as the application exists across different dimensions.
For example, MaxRequests may be 100 in "NorthAmerica", and 200 in "WestEurope". By creating a Configuration Setting named MaxRequests with a label of "NorthAmerica" and another, only with a different value, in the "WestEurope" label, an application can seamlessly retrieve Configuration Settings as it runs in these two dimensions.
Properties of a Configuration Setting:
key : str
label : str
content_type : str
value : str
last_modified : str
read_only : bool
tags : dict
etag : str
Azure App Configuration allows users to create a point-in-time snapshot of their configuration store, providing them with the ability to treat settings as one consistent version. This feature enables applications to hold a consistent view of configuration, ensuring that there are no version mismatches to individual settings due to reading as updates were made. Snapshots are immutable, ensuring that configuration can confidently be rolled back to a last-known-good configuration in the event of a problem.
The following sections provide several code snippets covering some of the most common Configuration Service tasks, including:
Create a Configuration Setting to be stored in the Configuration Store. There are two ways to store a 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)
added_config_setting.value = "new value"
added_config_setting.content_type = "new content type"
updated_config_setting = client.set_configuration_setting(added_config_setting)
Get a previously stored Configuration Setting.
fetched_config_setting = client.get_configuration_setting(key="MyKey", label="MyLabel")
Delete an existing Configuration Setting.
client.delete_configuration_setting(
key="MyKey",
label="MyLabel",
)
List all configuration settings filtered with label_filter and/or key_filter.
config_settings = client.list_configuration_settings(label_filter="MyLabel")
for item in config_settings:
print_configuration_setting(item)
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()
print_snapshot(created_snapshot)
received_snapshot = client.get_snapshot(name=snapshot_name)
archived_snapshot = client.archive_snapshot(name=snapshot_name)
print_snapshot(archived_snapshot)
recovered_snapshot = client.recover_snapshot(name=snapshot_name)
print_snapshot(recovered_snapshot)
for snapshot in client.list_snapshots():
print_snapshot(snapshot)
for config_setting in client.list_configuration_settings(snapshot_name=snapshot_name):
print_configuration_setting(config_setting)
Async client is supported. To use the async client library, import the AzureAppConfigurationClient from package azure.appconfiguration.aio instead of azure.appconfiguration
import os
from azure.appconfiguration.aio import AzureAppConfigurationClient
CONNECTION_STRING = os.environ["APPCONFIGURATION_CONNECTION_STRING"]
# Create app config client
client = AzureAppConfigurationClient.from_connection_string(CONNECTION_STRING)
This async AzureAppConfigurationClient has the same method signatures as the sync ones except that they're async. For instance, to retrieve a Configuration Setting asynchronously, async_client can be used:
fetched_config_setting = await client.get_configuration_setting(key="MyKey", label="MyLabel")
To use list_configuration_settings, call it synchronously and iterate over the returned async iterator asynchronously
config_settings = client.list_configuration_settings(label_filter="MyLabel")
async for item in config_settings:
print_configuration_setting(item)
from azure.appconfiguration import ConfigurationSettingsFilter
filters = [ConfigurationSettingsFilter(key="my_key1", label="my_label1")]
response = await client.begin_create_snapshot(name=snapshot_name, filters=filters)
created_snapshot = await response.result()
print_snapshot(created_snapshot)
received_snapshot = await client.get_snapshot(name=snapshot_name)
archived_snapshot = await client.archive_snapshot(name=snapshot_name)
print_snapshot(archived_snapshot)
recovered_snapshot = await client.recover_snapshot(name=snapshot_name)
print_snapshot(recovered_snapshot)
async for snapshot in client.list_snapshots():
print_snapshot(snapshot)
async for config_setting in client.list_configuration_settings(snapshot_name=snapshot_name):
print_configuration_setting(config_setting)
See the troubleshooting guide for details on how to diagnose various failure scenarios.
Several App Configuration client library samples are available to you in this GitHub repository. These include:
For more details see the samples README.
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.
When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
This project has adopted the Microsoft Open Source Code of Conduct. For more information, see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.
accept_datetime in get_snapshot_configuration_settings(), list_snapshot_configuration_settings() and list_revisions().azure-core to >=1.28.0.api_version to "2023-10-01".etag keyword documentation in set_read_only() as it's not in use.name in list_snapshot_configuration_settings() to snapshot_name.accept_datetime in list_snapshot_configuration_settings().list_snapshot_configuration_settings() to an overload of list_configuration_settings(), and moved the parameter snapshot_name to keyword.SnapshotStatus, and accepted the type for status parameter in list_snapshots() and status property in Snapshot model.Snapshot to ConfigurationSnapshot.ConfigurationSettingFilter to ConfigurationSettingsFilter.filters property is None.FeatureFlagConfigurationSetting from SDK but having an error in portal.(#31326)Snapshot CRUD operations.update_sync_token() to use async/await keywords.azure-core to >=1.25.0.api_version to "2022-11-01-preview".azure-core to >=1.24.0.AsyncioRequestsTransport to the one used in current azure-core (AioHttpTransport). (#26427)msrest requirement.isodate with version range >=0.6.0.Fixed the issue that data was persisted according to an incorrect schema/in an incorrect format (#20518)
SecretReferenceConfigurationSetting in 1.2.0 used "secret_uri" rather than "uri" as the schema keywords which
broken inter-operation of SecretReferenceConfigurationSetting between SDK and the portal.
Please:
SecretReferenceConfigurationSetting uses.SecretReferenceConfigurationSettings and set them back to correct the format.FeatureFlagConfigurationSetting and SecretReferenceConfigurationSetting modelsAzureAppConfigurationClient can now be used as a context manager.update_sync_token() to update sync tokens from Event Grid notifications.AzureAppConfigurationClients.FeatureFlagConfigurationSetting and SecretReferenceConfigurationSetting.update_sync_token() to include sync tokens from EventGrid notifications.SecretReferenceConfigurationSetting type to represent a configuration setting that references a KeyVault Secret.FeatureFlagConfigurationSetting type to represent a configuration setting that controls a feature flag.set_read_only() method. (#13276)list_configuration_settings() & list_revisions() now take string key/label filter instead of keys/labels list. (#9066)etag and match_condition of delete_configuration_setting() are now keyword argument only. (#8161)set_read_only() and clear_read_only() methods