Azure App Configuration은 개발자가 애플리케이션 구성을 간단하고 안전하게 중앙 집중화하도록 도와주는 관리형 서비스입니다. Python 구성 공급자 라이브러리를 사용하면 관리되는 방식으로 Azure App Configuration 저장소에서 구성을 로드할 수 있습니다. 이 클라이언트 라이브러리는 Python용 Azure SDK를 기반으로 추가 기능을 추가합니다.
패키지 설치
pip를 사용하여 Azure App Configuration Provider 패키지를 설치합니다.
pip install azure-appconfiguration-provider
Microsoft Entra ID를 사용하려면 Azure ID도 필요합니다.
pip install azure-identity
구성 로드
load 패키지의 azure-appconfiguration-provider 함수는 Azure App Configuration에서 구성을 로드하는 데 사용됩니다. 이 load 함수를 사용하면 Microsoft Entra ID(권장) 또는 연결 문자열을 사용하여 App Configuration 저장소에 연결할 수 있습니다.
비고
azure-appconfiguration-provider 에는 동기 from azure.appconfiguration.provider import load 버전과 비동기 버전이 from azure.appconfiguration.provider.aio import load 모두 있습니다. 비동기 버전을 사용하는 경우 비동기 자격 증명을 from azure.identity.aio import DefaultAzureCredential사용해야 합니다.
DefaultAzureCredential을(를) 사용하여 App Configuration 저장소에 인증합니다.
지침에 따라 자격 증명에 App Configuration Data Reader 역할을 할당합니다.
from azure.appconfiguration.provider import load
from azure.identity import DefaultAzureCredential
endpoint = "your-endpoint"
credential = DefaultAzureCredential()
# Connect to Azure App Configuration using a token credential and load all key-values with no label.
config = load(endpoint=endpoint, credential=credential)
print(config["message"]) # value of the key "message" from the App Configuration store
이 함수는 load 사전과 유사한 개체인 인스턴스 AzureAppConfigurationProvider를 반환하며 App Configuration 저장소에서 로드된 모든 구성 값을 포함합니다. 기본적으로 공급자는 저장소에서 레이블 없이 모든 구성 값을 로드합니다.
JSON 콘텐츠 형식 처리
App Configuration에서 JSON 키 값을 만들 수 있습니다. Azure App Configuration에서 키-값을 로드할 때 구성 공급자는 유효한 JSON 콘텐츠 형식(예: 애플리케이션/json)의 키-값을 역직렬화된 Python 개체로 자동으로 변환합니다.
{
"key": "font",
"label": null,
"value": "{\r\n\t\"size\": 12,\r\n\t\"color\": \"red\"\r\n}",
"content_type": "application/json"
}
이 JSON 콘텐츠는 키-값을 { size: 12, color: "red" }로 로드합니다.
appConfig = load(endpoint, credential)
size = appConfig["font"]["size"]
color = appConfig["font"]["color"]
비고
azure-appconfiguration-provider의 2.2.0 버전부터 구성 공급자는 application/json 콘텐츠 형식이 있는 키-값에서(JSONC)에 정의된 대로 메모를 허용합니다.
선택기를 사용하여 특정 키 값 로드
기본적으로 메서드는 load 구성 저장소에서 레이블이 없는 모든 구성을 로드합니다.
load의 선택적 매개변수인 selects를 통해 SettingSelector 목록으로 메서드의 동작을 구성할 수 있습니다.
from azure.appconfiguration.provider import load, SettingSelector
from azure.identity import DefaultAzureCredential
selects = [
SettingSelector(key_filter="*", label_filter="\0"), # Empty label
SettingSelector(key_filter="*", label_filter="dev") # 'dev' label
]
config = load(endpoint=endpoint, credential=DefaultAzureCredential(), selects=selects)
비고
키 값은 선택기가 나열되는 순서대로 로드됩니다. 여러 선택기가 동일한 키로 키 값을 검색할 때, 마지막 선택기의 값이 이전에 로드된 값을 대체합니다.
태그 필터
태그 필터 매개 변수는 특정 태그가 있는 키-값을 선택합니다. 키-값은 필터에 지정된 모든 태그와 해당 값이 있는 경우에만 로드됩니다.
from azure.appconfiguration.provider import load, SettingSelector
from azure.identity import DefaultAzureCredential
tag_filters = [{"env": "prod"}, {"region": "us"}]
selects = [SettingSelector(key_filter="*", label_filter="*", tag_filters=tag_filters)]
config = load(endpoint=endpoint, credential=DefaultAzureCredential(), selects=selects)
비고
문자 별표(*), 쉼표(,), 및 백슬래시(\)는 예약 문자이며, 태그 필터에서 사용할 때는 백슬래시로 이스케이프해야 합니다.
구성을 스냅샷에서 로드하기
에서 snapshot_name 매개변수를 사용하여 SettingSelector으로부터 구성 설정을 로드할 수 있습니다. 스냅샷 이름을 지정하면 해당 스냅샷의 모든 구성 설정이 로드됩니다. 매개 변수는 snapshot_name , key_filter또는 label_filter.와 함께 tag_filters사용할 수 없습니다.
from azure.appconfiguration.provider import load, SettingSelector
from azure.identity import DefaultAzureCredential
snapshot_selects = [SettingSelector(snapshot_name="SnapshotName")]
config = load(endpoint=endpoint, credential=DefaultAzureCredential(), selects=snapshot_selects)
비고
패키지 버전 2.3.0 이상을 azure-appconfiguration-provider 사용하는 경우 스냅샷 지원을 사용할 수 있습니다.
구성 공급자를 사용하여 컴퍼지션 형식 Key 으로 만든 스냅샷만 로드할 수 있습니다.
키 트리밍
키의 접두사를 제거하려면 매개 변수 load을 통해 자른 키 접두사 목록을 trim_prefixes 함수에 제공하면 됩니다.
from azure.appconfiguration.provider import load
from azure.identity import DefaultAzureCredential
trim_prefixes = ["App1/"]
config = load(endpoint=endpoint, credential=DefaultAzureCredential(), trim_prefixes=trim_prefixes)
print(config["message"]) # Access the key "message" instead of "/application/message"
구성 설정 매핑
매개 configuration_mapper 변수를 사용하면 구성 설정이 처리되고 공급자에 추가되기 전에 변환할 수 있습니다. 매퍼 함수는 각 ConfigurationSetting 개체를 수신하고 현재 위치에서 수정할 수 있습니다.
from azure.appconfiguration.provider import load
from azure.identity import DefaultAzureCredential
def my_mapper(setting):
if setting.key == "message":
setting.value = "transformed value"
config = load(endpoint=endpoint, credential=DefaultAzureCredential(), configuration_mapper=my_mapper)
매퍼 함수는 저장소에서 로드된 각 구성 설정에 대해 호출되므로 다음을 수행할 수 있습니다.
- 값을 추가하기 전에 설정 값 수정
- 값 변환 또는 암호 해독
- 설정 키, 레이블 또는 콘텐츠 형식에 따라 사용자 지정 처리 수행
비고
키 트리밍이 적용되기 전에 매퍼가 호출됩니다. 매퍼 함수에서 조건을 확인할 때 원래 키를 사용합니다.
비동기 작업의 경우 비동기 매퍼 함수를 제공합니다.
from azure.appconfiguration.provider.aio import load
from azure.identity.aio import DefaultAzureCredential
async def my_async_mapper(setting):
if setting.key == "secret_message":
setting.value = await decrypt_value(setting.value)
config = await load(endpoint=endpoint, credential=DefaultAzureCredential(), configuration_mapper=my_async_mapper)
구성 새로 고침
애플리케이션을 다시 시작하지 않고도 App Configuration 저장소에서 최신 설정을 가져오도록 공급자를 구성할 수 있습니다. 매개 변수를 refresh_on 사용하여 이 동작을 사용하도록 설정할 수 있습니다.
refresh_on 매개 변수는 List[WatchKey]로, 변경 사항을 모니터링할 하나 이상의 키/레이블을 지정합니다. 서버에서 선택한 키-값의 변경 내용이 검색되면 로드된 구성이 업데이트됩니다. 기본적으로 30초의 새로 고침 간격이 사용되지만 매개 변수를 사용하여 재정의 refresh_interval 할 수 있습니다.
on_refresh_success 변경 내용이 검색되고 오류가 발생하지 않는 경우에만 콜백이 호출됩니다.
on_refresh_error 새로 고침이 실패하면 콜백이 호출됩니다.
from azure.appconfiguration.provider import load, WatchKey
from azure.identity import DefaultAzureCredential
def my_callback_on_success():
# Do something on success
pass
def my_callback_on_fail(error):
# Do something on fail
pass
config = load(
endpoint=endpoint,
credential=DefaultAzureCredential(),
refresh_on=[WatchKey("Sentinel")],
refresh_interval=60,
on_refresh_success=my_callback_on_success,
on_refresh_error=my_callback_on_fail
)
단독으로 설정 refresh_on 해도 구성이 자동으로 새로 고쳐지지는 않습니다. 새로 고침을 트리거하려면 refresh 메서드에서 반환된 AzureAppConfigurationProvider 인스턴스에서 load 메서드를 호출해야 합니다.
config.refresh()
이 디자인은 애플리케이션이 유휴 상태일 때 App Configuration에 대한 불필요한 요청을 방지합니다. 애플리케이션 활동이 발생하는 refresh 호출을 포함해야 합니다. 이 프로세스를 활동 기반 구성 새로 고침이라고 합니다. 예를 들어 들어오는 요청을 처리할 때 또는 복잡한 작업을 수행하는 반복 내에서 refresh을(를) 호출할 수 있습니다. 새로 고침이 실패하면 on_refresh_error가 제공되지 않는 한 오류가 발생합니다. 새로 고침 간격이 경과하지 않은 경우, refresh 메서드는 아무 작업도 하지 않습니다. 또한 새로 고침 확인은 한 번에 하나만 수행될 수 있으며 새로 고침이 이미 진행 중인 경우 no-op으로 반환됩니다.
기능 플래그
Azure App Configuration에서 기능 플래그를 만들 수 있습니다. 기본적으로 구성 공급자는 기능 플래그를 로드하지 않습니다.
feature_flags_enabled 매개 변수를 통해 기능 플래그의 로드 및 새로 고침을 활성화할 수 있습니다.
config = load(endpoint=endpoint, credential=DefaultAzureCredential(), feature_flags_enabled=True)
alpha = config["feature_management"]["feature_flags"]["Alpha"]
print(alpha["enabled"])
기본적으로 feature_flags_enabled가 True로 설정된 경우, 레이블이 없는 모든 기능 플래그가 로드됩니다. 특정 레이블을 사용하여 기능 플래그를 로드하려면 매개 변수를 feature_flag_selectors 사용하여 개체 목록을 SettingSelector 가져오는 기능 플래그를 필터링할 수 있습니다.
from azure.appconfiguration.provider import load, SettingSelector
config = load(
endpoint=endpoint,
credential=DefaultAzureCredential(),
feature_flags_enabled=True,
feature_flag_selectors=[SettingSelector(key_filter="*", label_filter="dev")]
)
alpha = config["feature_management"]["feature_flags"]["Alpha"]
print(alpha["enabled"])
비고
Azure App Configuration에서 로드된 기능 플래그를 효과적으로 사용하고 관리하려면 라이브러리를 featuremanagement 설치하고 사용합니다. 이 라이브러리는 애플리케이션에서 기능 동작을 제어하는 구조화된 방법을 제공합니다.
기능 관리
기능 관리 라이브러리는 기능 플래그를 기반으로 애플리케이션 기능을 개발하고 노출하는 방법을 제공합니다. 기능 관리 라이브러리는 구성 공급자 라이브러리와 함께 작동하도록 설계되었습니다. 구성 공급자는 모든 선택한 기능 플래그를 feature_flags 섹션의 feature_management 목록 아래에 구성으로 로드합니다. 기능 관리 라이브러리는 애플리케이션에 대해 로드된 기능 플래그를 사용하고 관리합니다.
다음 예제에서는 기능 플래그의 featuremanagement 상태에 따라 Express 애플리케이션에서 API 접근성을 동적으로 제어하도록 라이브러리를 구성 공급자와 통합하는 Beta 방법을 보여 줍니다.
from azure.appconfiguration.provider import load
from featuremanagement import FeatureManager
config = load(endpoint=endpoint, credential=DefaultAzureCredential(), feature_flags_enabled=True)
feature_manager = FeatureManager(config)
print(f"Beta is: {feature_manager.is_enabled("Beta")}")
Python 기능 관리 라이브러리를 사용하는 방법에 대한 자세한 내용은 기능 플래그 빠른 시작을 참조하세요.
기능 플래그 원격 분석
기능 플래그 원격 분석을 사용하도록 설정하면 Azure App Configuration 공급자는 기능 플래그 원격 분석 데이터에 추가 속성을 삽입합니다. 이러한 속성은 기능 플래그 및 해당 평가에 대한 더 많은 컨텍스트를 제공합니다.
- AllocationID: 기능 플래그 할당의 상태를 나타내는 고유 식별자입니다.
- ETag: 기능 플래그의 현재 ETag입니다.
-
FeatureFlagReference: 기능 플래그 형식에 대한 참조입니다
<your_store_endpoint>kv/<feature_flag_key>. 레이블이 있으면 참조에 쿼리 매개 변수<your_store_endpoint>kv/<feature_flag_key>?label=<feature_flag_label>로 포함됩니다.
전체 스키마는 App Configuration 기능 평가 이벤트 스키마 정의에서 찾을 수 있습니다. 기능 플래그 원격 분석 사용법에 대한 자세한 내용은 기능 플래그에 대한 원격 분석 사용 활성화 안내문을 참조하세요.
기능 플래그 새로 고침
기능 플래그에 대해 새로 고침을 사용하도록 설정하려면 feature_flag_refresh_enabled=True을(를) 설정해야 합니다. 이 매개 변수를 사용하면 공급자가 구성을 새로 고치는 것과 동일한 방식으로 기능 플래그를 새로 고칠 수 있습니다. 구성과 달리 로드된 모든 기능 플래그는 변경 내용을 모니터링하고 새로 고침을 발생합니다. 구성 설정 및 기능 플래그 새로 고침은 서로 독립적입니다. 구성 설정과 기능 플래그는 모두 메서드에 의해 refresh 업데이트되지만 기능 플래그 변경으로 인해 구성이 새로 고쳐지지는 않으며 그 반대의 경우도 마찬가지입니다. 또한 구성 설정에 대한 새로 고침을 사용하도록 설정하지 않은 경우에도 기능 플래그를 새로 고칠 수 있습니다.
config = load(
endpoint=endpoint,
credential=DefaultAzureCredential(),
feature_flags_enabled=True,
feature_flag_refresh_enabled=True
)
# Later in your code
config.refresh()
Key Vault 참조
Azure App Configuration은 Azure Key Vault에 저장된 비밀 참조를 지원합니다. App Configuration에서 Key Vault에 저장된 비밀에 매핑되는 키를 만들 수 있습니다. 비밀은 Key Vault에 안전하게 저장되지만 로드된 다른 구성처럼 액세스할 수 있습니다.
구성 공급자 라이브러리는 App Configuration에 저장된 다른 키와 마찬가지로 Key Vault 참조를 검색합니다. 클라이언트는 키를 Key Vault 참조로 인식하므로 고유한 콘텐츠 형식을 가지며 클라이언트는 Key Vault에 연결하여 애플리케이션에 대한 값을 검색합니다. 자격 증명을 제공하거나 클라이언트를 제공하여 Key Vault에 연결하는 방법을 구성해야 합니다.
자격 증명이 있는 경우
자격 증명을 사용하여 인수 keyvault_credential 를 설정할 수 있으며, 모든 키 보관소 참조가 이를 통해 해결됩니다. 공급자는 제공된 자격 증명을 사용하여 참조된 모든 키 저장소에 연결을 시도합니다.
from azure.appconfiguration.provider import load, AzureAppConfigurationKeyVaultOptions
from azure.identity import DefaultAzureCredential
config = load(endpoint=endpoint, credential=DefaultAzureCredential(), keyvault_credential=DefaultAzureCredential())
클라이언트와 함께
클라이언트 구성 사전을 사용하여 인수 keyvault_client_configs 를 설정할 수 있습니다.
from azure.appconfiguration.provider import load
from azure.identity import DefaultAzureCredential
secret_clients = {
key_vault_uri: {
'credential': DefaultAzureCredential()
}
}
config = load(endpoint=endpoint, credential=DefaultAzureCredential(), keyvault_client_configs=secret_clients)
비고
제공된 모든 추가 속성은 SecretClient의 생성 과정에 전달됩니다.
비밀 해석기
자격 증명 또는 클라이언트가 제공되지 않으면 비밀 확인자를 사용할 수 있습니다. 비밀 리졸버는 키 볼트 참조에 원하는 값을 반환할 수 있도록 합니다.
from azure.appconfiguration.provider import load
from azure.identity import DefaultAzureCredential
def secret_resolver(uri):
return "From Secret Resolver"
config = load(endpoint=endpoint, credential=DefaultAzureCredential(), secret_resolver=secret_resolver)
Key Vault 비밀 새로 고침
Azure App Configuration을 사용하면 구성 새로 고침 주기와 독립적으로 비밀 새로 고침 간격을 구성할 수 있습니다. 이는 App Configuration의 Key Vault 참조 URI가 변경되지 않은 상태로 유지되지만 Key Vault의 기본 비밀이 보안 사례의 일부로 회전될 수 있기 때문에 보안에 매우 중요합니다.
애플리케이션에서 항상 최신 비밀 값을 사용하도록 하려면 키워드를 secret_refresh_interval 구성합니다 load. 이렇게 하면 다음과 같은 경우 공급자가 Key Vault에서 새 비밀 값을 검색합니다.
- 귀하의 애플리케이션이
refresh를 호출합니다 - 비밀에 대해 구성된 새로 고침 간격이 경과했습니다.
App Configuration 저장소에서 변경 내용이 검색되지 않더라도 이 메커니즘은 작동하므로 애플리케이션이 갱신된 비밀과 동기화됩니다.
from azure.appconfiguration.provider import load
from azure.identity import DefaultAzureCredential
config = load(
endpoint=endpoint,
credential=DefaultAzureCredential(),
keyvault_credential=DefaultAzureCredential(),
secret_refresh_interval=7200 # 2 hours
)
Geo-replication
Azure App Configuration Provider 라이브러리는 제공된 구성 저장소의 복제본을 자동으로 검색하고 문제가 발생하는 경우 복제본을 사용합니다. 자세한 내용은 지역 복제를 참조하세요.
복제본 검색은 기본적으로 사용하도록 설정됩니다. 사용하지 않으려면 replica_discovery_enabled을(를) False로 설정할 수 있습니다.
from azure.appconfiguration.provider import load
from azure.identity import DefaultAzureCredential
config = load(
endpoint=endpoint,
credential=DefaultAzureCredential(),
replica_discovery_enabled=False
)
다음 단계
Python 구성 공급자를 사용하는 방법을 알아보려면 다음 자습서를 계속 진행합니다.
웹 애플리케이션에서 공급자를 사용하는 방법을 보려면 Django 및 Flask 예제를 확인하세요.