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

Getting started

Install the package

Install the Azure App Configuration client library for Python with pip:

pip install azure-appconfiguration

Prerequisites

• Python 3.8 or later is required to use this package.
• You need anAzure subscription, and aConfiguration Store to use this package.

To create a Configuration Store, you can use the Azure Portal orAzure CLI.

After that, create the Configuration Store:

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

Authenticate the client

In order to interact with the App Configuration service, you'll need to create an instance of theAzureAppConfigurationClient class. To make this possible,you can either use the connection string of the Configuration Store or use an AAD token.

Use connection string

Get credentials

Use theAzure 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.

Create client

Once you have the value of the connection string, you can create the AzureAppConfigurationClient:

import osfrom azure.appconfiguration import AzureAppConfigurationClientCONNECTION_STRING = os.environ["APPCONFIGURATION_CONNECTION_STRING"]# Create app config clientclient = AzureAppConfigurationClient.from_connection_string(CONNECTION_STRING)

Use AAD token

Here we demonstrate usingDefaultAzureCredentialto authenticate as a service principal. However,AzureAppConfigurationClientaccepts anyazure-identity credential. See theazure-identity documentation for more information about othercredentials.

Create a service principal (optional)

ThisAzure CLI snippet shows how to create anew service principal. Before using it, replace "your-application-name" withthe 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 setAZURE_CLIENT_ID ("appId" above),AZURE_CLIENT_SECRET("password" above) andAZURE_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 applicableApp Configuration roles to the service principal.

Create a client

Once theAZURE_CLIENT_ID,AZURE_CLIENT_SECRET andAZURE_TENANT_ID environment variables are set,DefaultAzureCredential will be able to authenticate theAzureAppConfigurationClient.

Constructing the client also requires your configuration store's URL, which you canget 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 DefaultAzureCredentialfrom azure.appconfiguration import AzureAppConfigurationClientcredential = DefaultAzureCredential()client = AzureAppConfigurationClient(base_url="your_endpoint_url", credential=credential)

Key concepts

Configuration Setting

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.

TheLabel 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 : strlabel : strcontent_type : strvalue : strlast_modified : strread_only : booltags : dictetag : str

Snapshot

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.

Examples

The following sections provide several code snippets covering some of the most common Configuration Service tasks, including:

• Create a Configuration Setting
• Get a Configuration Setting
• Delete a Configuration Setting
• List Configuration Settings
• Create a Snapshot
• Get a Snapshot
• Archive a Snapshot
• Recover a Snapshot
• List Snapshots
• List Configuration Settings of a Snapshot
• Async APIs

Create a Configuration Setting

Create a Configuration Setting to be stored in the Configuration Store.There are two ways to store a Configuration Setting:

• add_configuration_setting creates a setting only if the setting does not already exist in the store.

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 creates a setting if it doesn't exist or overrides an existing 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)

Set and clear read-only for a configuration setting.

• Set a configuration setting to be read-only.

read_only_config_setting = client.set_read_only(updated_config_setting)

• Clear read-only for a configuration setting.

read_write_config_setting = client.set_read_only(updated_config_setting, False)

Get a Configuration Setting

Get a previously stored Configuration Setting.

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

Delete a Configuration Setting

Delete an existing Configuration Setting.

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

List Configuration Settings

List all configuration settings filtered with label_filter and/or key_filter and/or tags_filter.

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)

List revisions

List revision history of configuration settings filtered with label_filter and/or key_filter and/or tags_filter.

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

List labels

List labels of all configuration settings.

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)

Create a Snapshot

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

Get a Snapshot

received_snapshot = client.get_snapshot(name=snapshot_name)

Archive a Snapshot

archived_snapshot = client.archive_snapshot(name=snapshot_name)

Recover a Snapshot

recovered_snapshot = client.recover_snapshot(name=snapshot_name)

List Snapshots

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

List Configuration Settings of a Snapshot

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

Async APIs

Async client is supported.To use the async client library, import the AzureAppConfigurationClient from package azure.appconfiguration.aio instead of azure.appconfiguration.

import osfrom azure.appconfiguration.aio import AzureAppConfigurationClientCONNECTION_STRING = os.environ["APPCONFIGURATION_CONNECTION_STRING"]# Create an app config clientclient = 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, retrieve a Configuration Setting asynchronously:

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

To list configuration settings, calllist_configuration_settings operation synchronously and iterate over the returned async iterator asynchronously:

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)

Troubleshooting

See thetroubleshooting guide for details on how to diagnose various failure scenarios.

Next steps

More sample code

Several App Configuration client library samples are available to you in this GitHub repository. These include:

• Hello world /Async version
• List configuration settings /Async version
• Make a configuration setting readonly /Async version
• Read revision history /Async version
• Get a setting if changed /Async version
• Create, retrieve and update status of a configuration settings snapshot /Async version
• Send custom HTTP requests /Async version
• Update AzureAppConfigurationClient sync_token /Async version

For more details see thesamples README.

Contributing

This project welcomes contributions and suggestions. Most contributions requireyou to agree to a Contributor License Agreement (CLA) declaring that you havethe right to, and actually do, grant us the rights to use your contribution.For details, visithttps://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whetheryou need to provide a CLA and decorate the PR appropriately (e.g., label,comment). Simply follow the instructions provided by the bot. You will onlyneed to do this once across all repos using our CLA.

This project has adopted theMicrosoft Open Source Code of Conduct. For more information,see theCode of Conduct FAQ or contactopencode@microsoft.com with anyadditional questions or comments.