Python 組態提供者

Python 套件

Azure 應用程式組態是一項受控服務，可協助開發人員簡單且安全地集中管理其應用程式組態。 Python 組態提供者程式庫可讓您以受控方式從 Azure 應用程式組態存放區載入組態。此用戶端程式庫會在適用於 Python 的 Azure SDK 之上新增其他功能。

安裝套件

使用 pip 安裝 Azure 應用程式組態提供者套件：

pip install azure-appconfiguration-provider

若要使用 Microsoft Entra ID，也需要 Azure 身分識別。

pip install azure-identity

載入設定

load套件中的azure-appconfiguration-provider函式可用來從 Azure 應用程式設定載入組態。 load 函式可讓您使用 Microsoft Entra ID (建議) 或連接字串來連線到應用程式組態存放區。

備註

azure-appconfiguration-provider 具有同步 from azure.appconfiguration.provider import load 和非同步 from azure.appconfiguration.provider.aio import load 版本。使用非同步版本時，需要使用非同步憑證。 from azure.identity.aio import DefaultAzureCredential

Microsoft Entra 身份識別
連接字串

您可以使用 DefaultAzureCredential 來向應用程式組態存放區進行驗證。請依照指示將您的憑證指派為 應用程式設定數據讀取者 角色。

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

from azure.appconfiguration.provider import load

connection_string = "your-connection-string"

# Connect to Azure App Configuration using a connection string and load all key-values with no label.
config = load(connection_string=connection_string)
print(config["message"]) # value of the key "message" from the App Configuration store

函 load 式會傳回的 AzureAppConfigurationProvider實例，這是一個類似字典的物件，包含從 App Configuration 存放區載入的所有組態值。依預設，提供者會從存放區載入所有沒有標籤的組態值。

JSON 內容類型處理

您可以在應用程式組態中建立 JSON 索引鍵/值。從 Azure 應用程式設定載入索引鍵/值時，設定提供者會自動將有效 JSON 內容類型（例如 application/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 版開始，組態提供者允許在具有內容類型的索引鍵/值中撰寫註解，如 (application/json) 中定義。

使用選取器載入特定索引鍵/值

依預設，此 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 建立的快照才能透過設定提供者載入。

快照參考

快照參考是參考相同應用程式組態存放區中快照的組態設定。載入時，提供者會解析它，並新增該快照集中的所有索引鍵/值。使用快照參考可以在執行時切換快照，與新增快照選擇器不同，後者需要修改程式碼和/或重新啟動才能切換到新的快照。

欲了解更多關於建立快照參考的資訊，請參考快照參考概念。

備註

若要使用快照參考，請使用套件的 2.4.0 或更新 azure-appconfiguration-provider 版本。

修剪金鑰

您可以通過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_enabled 設為 True，並對 refresh 方法傳回的 AzureAppConfigurationProvider 執行個體呼叫 load 方法。

from azure.appconfiguration.provider import load
from azure.identity import DefaultAzureCredential

config = load(
    endpoint=endpoint,
    credential=DefaultAzureCredential(),
    refresh_enabled=True
)

# Later in your code, when application activity occurs
config.refresh()

根據預設，會使用 30 秒的重新整理間隔，但您可以使用 refresh_interval 參數來覆寫它。提供者會監控所有已載入的鍵值是否有變動。

config = load(
    endpoint=endpoint,
    credential=DefaultAzureCredential(),
    refresh_enabled=True,
    refresh_interval=60
)

此設計可防止應用程式閒置時，應用程式組態的不必要要求。您應該包含應用程式活動發生所在的 refresh 呼叫。此流程稱為 活動驅動配置重新整理。例如，您可以在處理傳入要求時或在執行複雜工作的反覆項目內呼叫 refresh。

即使重新整理呼叫因任何原因而導致失敗，您的應用程式仍會繼續使用快取設定。當設定的刷新間隔結束，且由應用程式活動觸發刷新呼叫時，會再嘗試一次。在設定的重新整理的間隔過去之前，呼叫 refresh 是不可操作的，因此即使頻繁呼叫，其對效能的影響也是最小的。

自訂重新整理回呼

on_refresh_success僅在偵測到變更且未發生錯誤時，才會呼叫回調函數。 on_refresh_error回呼函數會在重新整理失敗時被呼叫。

from azure.appconfiguration.provider import load
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_enabled=True,
    on_refresh_success=my_callback_on_success,
    on_refresh_error=my_callback_on_fail
)

特定鍵變更時重新整理

你可以使用 refresh_on 參數，將提供者設定為監視特定監看鍵的變更，而非監視所有已載入的鍵值。該 refresh_on 參數是一個 List[WatchKey]，用於指定一個或多個需要監控變更的鍵/標籤。當偵測到任何被監控鍵的變更時，所有設定值都會被刷新。

from azure.appconfiguration.provider import load, WatchKey
from azure.identity import DefaultAzureCredential

config = load(
    endpoint=endpoint,
    credential=DefaultAzureCredential(),
    refresh_on=[WatchKey("Sentinel")]
)

備註

當設定 refresh_on 時，refresh_enabled 會自動預設為 True。您可以將refresh_enabled設定為False，以實現即使已設定refresh_on，也能停用重新整理。

功能旗標

您可以在 Azure 應用程式組態中建立功能旗標。根據預設，組態提供者不會載入功能旗標。您可以透過 feature_flag_enabled 參數啟用載入和重新整理功能標誌。

config = load(endpoint=endpoint, credential=DefaultAzureCredential(), feature_flag_enabled=True)
alpha = config["feature_management"]["feature_flags"]["Alpha"]
print(alpha["enabled"])

預設情況下，當你設定 feature_flag_enabled 為 True時，所有沒有標籤的功能旗標都會被載入。如果你想載入帶有特定標籤的功能旗標，可以使用 feature_flag_selectors 參數來篩選功能旗標。此參數會取一個物件清單 SettingSelector 。

from azure.appconfiguration.provider import load, SettingSelector

config = load(
    endpoint=endpoint, 
    credential=DefaultAzureCredential(), 
    feature_flag_enabled=True, 
    feature_flag_selectors=[SettingSelector(key_filter="*", label_filter="dev")]
)
alpha = config["feature_management"]["feature_flags"]["Alpha"]
print(alpha["enabled"])

備註

若要有效地取用和管理從 Azure 應用程式設定載入的功能旗標，請安裝並使用 featuremanagement 程式庫。此程式庫提供了一種結構化的方式來控制應用程式的功能行為。

功能管理

功能管理連結庫提供一種方式，可根據功能旗標來開發和公開應用程式功能。功能管理程式庫設計為與組態提供者程式庫搭配使用。組態提供者會將所有選取的功能旗標載入 feature_flags 區段的 feature_management 清單下的組態。功能管理程式庫會取用並管理應用程式載入的功能旗標。

下列範例示範如何將 featuremanagement 庫與組態提供者整合，以根據 Beta 功能標記的狀態動態控制 Express 應用程式中的 API 存取。

from azure.appconfiguration.provider import load
from featuremanagement import FeatureManager


config = load(endpoint=endpoint, credential=DefaultAzureCredential(), feature_flag_enabled=True)
feature_manager = FeatureManager(config)

print(f"Beta is: {feature_manager.is_enabled("Beta")}")

如需如何使用 Python 功能管理程式庫的詳細資訊，請移至功能旗標快速入門。

功能旗標遙測

當啟用功能旗標遙測時，Azure 應用程式設定提供者會注入額外的屬性以增加功能旗標遙測資料。以下屬性提供了關於特徵旗標及其評估的更多背景：

AllocationID：代表特徵旗標配置狀態的唯一識別碼。
ETag：目前功能標誌的 ETag。
FeatureFlagReference：指向功能標記的參考，格式為<AppConfigurationEndpoint>kv/<FeatureFlagKey>。當存在標籤時，會將其作為查詢參數包含在參考中：<AppConfigurationEndpoint>kv/<FeatureFlagKey>?label=<FeatureFlagLabel>。

完整架構可在應用程式配置功能評估事件架構定義中找到。欲了解更多如何使用特徵旗幟遙測的資訊，請前往「啟用功能標誌遙測」的操作步驟。

功能旗標重新整理

若要啟用功能旗標的重新整理，您需要將 feature_flag_refresh_enabled=True設定。此參數可讓提供者重新整理功能旗標，就像重新整理設定一樣。與組態不同，系統會監視所有載入的功能旗標是否有變更，並導致重新整理。組態設定和功能旗標的刷新是彼此獨立的。組態設定和功能旗標都會由方法 refresh 更新，但功能旗標變更不會導致重新整理組態，反之亦然。此外，如果未啟用組態設定的重新整理，仍可啟用功能旗標以重新整理。

config = load(
    endpoint=endpoint, 
    credential=DefaultAzureCredential(), 
    feature_flag_enabled=True, 
    feature_flag_refresh_enabled=True
)

# Later in your code
config.refresh()

金鑰保存庫參考

Azure 應用程式組態支援參考儲存在 Azure 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)

金鑰保存庫祕密重新整理

Azure 應用程式組態可讓您設定與設定重新整理周期無關的秘密重新整理間隔。這對安全性至關重要，因為雖然應用程式組態中的金鑰保存庫參考 URI 保持不變，但金鑰保存庫中的基礎秘密可能會輪替作為安全性做法的一部分。

為了確保你的應用程式總是使用最新的密鑰值，請在secret_refresh_interval中設定load關鍵字。這會強制提供者在下列情況下從金鑰保存庫擷取新的秘密值：

您的應用程式會呼叫 refresh。
該機密的設定重新整理間隔已經過期

即使在您的應用程式組態存放區中未偵測到任何變更，此機制仍可運作，確保您的應用程式能與輪替的祕密保持同步。

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
)

啟動重試

組態載入是應用程式啟動期間的重要路徑作業。為了確保可靠性，Azure 應用程式組態提供者會在初始設定負載期間實作強固的重試機制。這有助於保護您的應用程式免於暫時性網路問題，否則可能會防止成功啟動。

你可以透過設定startup_timeout參數來自訂這個行為，該參數會指定啟動時從 Azure 應用程式組態載入資料所需的秒數時間。預設值為 100 秒。

from azure.appconfiguration.provider import load
from azure.identity import DefaultAzureCredential

config = load(
    endpoint=endpoint,
    credential=DefaultAzureCredential(),
    startup_timeout=300
)

地理複製

Azure 應用程式組態提供者程式庫會自動探索所提供組態存放區的複本，並在發生任何問題時使用複本。如需詳細資訊，請參閱異地複寫。

預設情況下會啟用副本探索。如果要停用它，可以設定 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 組態提供者，請繼續執行下列教學課程。

在 Python 中使用動態配置

要了解如何在 Web 應用程式中使用提供者，請查看我們的 Django 和 Flask 範例。

Django 範例

Flask 範例

意見反應

此頁面對您有幫助嗎？

上次更新時間： 2026-06-30