Package: azure-appconfiguration
Azure App Configuration client library for PythonAzure 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 documentationDisclaimerAzure SDK Python packages support for Python 2.7 has ended 01 January 2022. For more information and questions, please refer tohttps://github.com/Azure/azure-sdk-for-python/issues/20691Python 3.7 or later is required to use this package. For more details, please refer toAzure SDK for Python version support policy.Getting startedInstall the packageInstall the Azure App Configuration client library for Python with pip:pip install azure-appconfigurationPrerequisitesPython 3.7 or later is required to use this package.You need anAzure subscription, and aConfiguration Storeto use this package.To create a Configuration Store, you can use the Azure Portal orAzure CLI.After that, create the Configuration Store:azappconfigcreate--name<config-store-name>--resource-group<resource-group-name>--locationeastusAuthenticate the clientIn order to interact with the App Configuration service, you'll need to create an instance of theAzureAppConfigurationClientclass. To make this possible,
you can either use the connection string of the Configuration Store or use an AAD token.Use connection stringGet credentialsUse theAzure CLIsnippet below to get the connection string from the Configuration Store.azappconfigcredentiallist--name<config-store-name>Alternatively, get the connection string from the Azure Portal.Create clientOnce you have the value of the connection string, you can create the AzureAppConfigurationClient:importosfromazure.appconfigurationimportAzureAppConfigurationClientCONNECTION_STRING=os.environ["APPCONFIGURATION_CONNECTION_STRING"]# Create app config clientclient=AzureAppConfigurationClient.from_connection_string(CONNECTION_STRING)Use AAD tokenHere we demonstrate usingDefaultAzureCredentialto authenticate as a service principal. However,AzureAppConfigurationClientaccepts anyazure-identitycredential. See theazure-identitydocumentation for more information about other
credentials.Create a service principal (optional)ThisAzure CLIsnippet 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:azadspcreate-for-rbac--namehttp://my-application--skip-assignmentOutput:{"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:exportAZURE_CLIENT_ID="generated app id"exportAZURE_CLIENT_SECRET="random password"exportAZURE_TENANT_ID="tenant id"Assign one of the applicableApp Configuration rolesto the service principal.Create a clientOnce theAZURE_CLIENT_ID,AZURE_CLIENT_SECRETandAZURE_TENANT_IDenvironment variables are set,DefaultAzureCredentialwill be able to authenticate theAzureAppConfigurationClient.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"fromazure.identityimportDefaultAzureCredentialfromazure.appconfigurationimportAzureAppConfigurationClientcredential=DefaultAzureCredential()client=AzureAppConfigurationClient(base_url="your_endpoint_url",credential=credential)Key conceptsConfiguration SettingA 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.TheLabelproperty 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:strSnapshotAzure 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.ExamplesThe following sections provide several code snippets covering some of the most common Configuration Service tasks, including:Create a Configuration SettingGet a Configuration SettingDelete a Configuration SettingList Configuration SettingsCreate a SnapshotGet a SnapshotArchive a SnapshotRecover a SnapshotList SnapshotsList Configuration Settings of a SnapshotAsync APIsCreate a Configuration SettingCreate 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)Get a Configuration SettingGet a previously stored Configuration Setting.fetched_config_setting=client.get_configuration_setting(key="MyKey",label="MyLabel")Delete a Configuration SettingDelete an existing Configuration Setting.client.delete_configuration_setting(key="MyKey",label="MyLabel",)List Configuration SettingsList all configuration settings filtered with label_filter and/or key_filter.config_settings=client.list_configuration_settings(label_filter="MyLabel")foriteminconfig_settings:print_configuration_setting(item)Create a Snapshotfromazure.appconfigurationimportConfigurationSettingsFilterfilters=[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)Get a Snapshotreceived_snapshot=client.get_snapshot(name=snapshot_name)Archive a Snapshotarchived_snapshot=client.archive_snapshot(name=snapshot_name)print_snapshot(archived_snapshot)Recover a Snapshotrecovered_snapshot=client.recover_snapshot(name=snapshot_name)print_snapshot(recovered_snapshot)List Snapshotsforsnapshotinclient.list_snapshots():print_snapshot(snapshot)List Configuration Settings of a Snapshotforconfig_settinginclient.list_configuration_settings(snapshot_name=snapshot_name):print_configuration_setting(config_setting)Async APIsAsync client is supported.
To use the async client library, import the AzureAppConfigurationClient from package azure.appconfiguration.aio instead of azure.appconfigurationimportosfromazure.appconfiguration.aioimportAzureAppConfigurationClientCONNECTION_STRING=os.environ["APPCONFIGURATION_CONNECTION_STRING"]# Create 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, to retrieve a Configuration Setting asynchronously, async_client can be used:fetched_config_setting=awaitclient.get_configuration_setting(key="MyKey",label="MyLabel")To use list_configuration_settings, call it synchronously and iterate over the returned async iterator asynchronouslyconfig_settings=client.list_configuration_settings(label_filter="MyLabel")asyncforiteminconfig_settings:print_configuration_setting(item)fromazure.appconfigurationimportConfigurationSettingsFilterfilters=[ConfigurationSettingsFilter(key="my_key1",label="my_label1")]response=awaitclient.begin_create_snapshot(name=snapshot_name,filters=filters)created_snapshot=awaitresponse.result()print_snapshot(created_snapshot)received_snapshot=awaitclient.get_snapshot(name=snapshot_name)archived_snapshot=awaitclient.archive_snapshot(name=snapshot_name)print_snapshot(archived_snapshot)recovered_snapshot=awaitclient.recover_snapshot(name=snapshot_name)print_snapshot(recovered_snapshot)asyncforsnapshotinclient.list_snapshots():print_snapshot(snapshot)asyncforconfig_settinginclient.list_configuration_settings(snapshot_name=snapshot_name):print_configuration_setting(config_setting)TroubleshootingSee thetroubleshooting guidefor details on how to diagnose various failure scenarios.Next stepsMore sample codeSeveral App Configuration client library samples are available to you in this GitHub repository.  These include:Hello world/Async versionHello world with labels/Async versionMake a configuration setting readonly/Async versionRead revision history/Async versionGet a setting if changed/Async versionCreate, retrieve and update status of a configuration settings snapshot/Async versionFor more details see thesamples README.ContributingThis 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, visithttps://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 theMicrosoft Open Source Code of Conduct. For more information,
see theCode of Conduct FAQor contactopencode@microsoft.comwith any
additional questions or comments.Release History1.5.0 (2023-11-09)Other ChangesSupported datetime type for keyword argumentaccept_datetimeinget_snapshot_configuration_settings(),list_snapshot_configuration_settings()andlist_revisions().Bumped minimum dependency onazure-coreto>=1.28.0.Updated the defaultapi_versionto "2023-10-01".Removedetagkeyword documentation inset_read_only()as it's not in use.1.5.0b3 (2023-10-10)Breaking ChangesRenamed parameternameinlist_snapshot_configuration_settings()tosnapshot_name.Removed keyword argumentaccept_datetimeinlist_snapshot_configuration_settings().Moved operationlist_snapshot_configuration_settings()to an overload oflist_configuration_settings(), and moved the parametersnapshot_nameto keyword.Published enumSnapshotStatus, and accepted the type forstatusparameter inlist_snapshots()andstatusproperty inSnapshotmodel.Renamed modelSnapshottoConfigurationSnapshot.Renamed modelConfigurationSettingFiltertoConfigurationSettingsFilter.1.5.0b2 (2023-08-02)Bugs FixedFixed a bug in deserializing and serializing Snapshot whenfiltersproperty isNone.Fixed a bug when creatingFeatureFlagConfigurationSettingfrom SDK but having an error in portal.(#31326)1.5.0b1 (2023-07-11)Features AddedAdded support forSnapshotCRUD operations.Bugs FixedFixed asyncupdate_sync_token()to use async/await keywords.Other ChangesBumped minimum dependency onazure-coreto>=1.25.0.Updated the defaultapi_versionto "2022-11-01-preview".1.4.0 (2022-02-13)Other ChangesPython 2.7 is no longer supported. Please use Python version 3.7 or later.Bumped minimum dependency onazure-coreto>=1.24.0.Changed the default async transport fromAsyncioRequestsTransportto the one used in currentazure-core(AioHttpTransport). (#26427)Droppedmsrestrequirement.Added dependencyisodatewith version range>=0.6.0.1.3.0 (2021-11-10)Bugs FixedFixed the issue that data was persisted according to an incorrect schema/in an incorrect format (#20518)SecretReferenceConfigurationSettingin 1.2.0 used "secret_uri" rather than "uri" as the schema keywords which
broken inter-operation ofSecretReferenceConfigurationSettingbetween SDK and the portal.Please:Use 1.3.0+ for anySecretReferenceConfigurationSettinguses.Call a get method for existingSecretReferenceConfigurationSettings and set them back to correct the format.1.2.0 (2021-07-06)Features AddedAddedFeatureFlagConfigurationSettingandSecretReferenceConfigurationSettingmodelsAzureAppConfigurationClientcan now be used as a context manager.Addedupdate_sync_token()to update sync tokens from Event Grid notifications.1.2.0b2 (2021-06-08)FeaturesAdded context manager functionality to the sync and asyncAzureAppConfigurationClients.FixesFixed a deserialization bug forFeatureFlagConfigurationSettingandSecretReferenceConfigurationSetting.1.2.0b1 (2021-04-06)FeaturesAdded methodupdate_sync_token()to include sync tokens from EventGrid notifications.AddedSecretReferenceConfigurationSettingtype to represent a configuration setting that references a KeyVault Secret.AddedFeatureFlagConfigurationSettingtype to represent a configuration setting that controls a feature flag.1.1.1 (2020-10-05)FeaturesImproved error message if Connection string secret has incorrect padding. (#14140)1.1.0 (2020-09-08)FeaturesAdded match condition support forset_read_only()method. (#13276)1.0.1 (2020-08-10)FixesDoc & Sample fixes1.0.0 (2020-01-06)FeaturesAdded AAD auth support. (#8924)Breaking changeslist_configuration_settings()&list_revisions()now take string key/label filter instead of keys/labels list. (#9066)1.0.0b6 (2019-12-03)FeaturesAdded sync-token support. (#8418)Breaking changesCombined set_read_only & clear_read_only to be set_read_only(True/False). (#8453)1.0.0b5 (2019-10-30)Breaking changesetagandmatch_conditionofdelete_configuration_setting()are now keyword argument only. (#8161)1.0.0b4 (2019-10-07)Added conditional operation supportAddedset_read_only()andclear_read_only()methods1.0.0b3 (2019-09-09)New azure app configuration