Aracılığıyla paylaş

Python yapılandırma sağlayıcısı

Python paketi

Azure Uygulama Yapılandırması, geliştiricilerin uygulama yapılandırmalarını basit ve güvenli bir biçimde merkezileştirmesine yardımcı olan, yönetilen bir hizmettir. Python yapılandırma sağlayıcısı kitaplığı, azure uygulama yapılandırma deposundan yapılandırmanın yönetilen bir şekilde yüklenmesini sağlar. Bu istemci kitaplığı, Python için Azure SDK'sının üzerine ek işlevler ekler.

Paketi yükle

Pip ile Azure Uygulama Yapılandırma Sağlayıcısı paketini yükleyin:

pip install azure-appconfiguration-provider

Microsoft Entra Kimliğini kullanmak için Azure Kimliği de gereklidir.

pip install azure-identity

Yapılandırmayı yükleme

load Paketteki azure-appconfiguration-provider işlev, Azure Uygulama Yapılandırması'ndan yapılandırmayı yüklemek için kullanılır. load işlevi, Microsoft Entra ID (önerilen) veya bir bağlantı dizesi kullanarak App Configuration deposuna bağlanmanıza olanak tanır.

Uyarı

azure-appconfiguration-provider hem zaman uyumlu from azure.appconfiguration.provider import load hem de zaman uyumsuz from azure.appconfiguration.provider.aio import load sürümlere sahiptir. Zaman uyumsuz sürümü kullanırken, zaman uyumsuz kimlik bilgilerinin from azure.identity.aio import DefaultAzureCredentialkullanılması gerekir.

DefaultAzureCredential öğesini Uygulama Yapılandırması deponuzda kimlik doğrulaması yapmak için kullanırsınız. Kimlik bilgilerinizi Uygulama Yapılandırması Veri Okuyucusu rolüne atamak için yönergeleri izleyin.

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 işlevi, Uygulama Yapılandırma Deposu'ndan yüklenen tüm yapılandırma değerlerini içeren AzureAppConfigurationProvider adlı, sözlük benzeri bir nesnenin bir örneğini döndürür. Varsayılan olarak sağlayıcı, mağazadan etiket içermeyen tüm yapılandırma değerlerini yükler.

JSON içerik türü işleme

Uygulama Yapılandırması'nda JSON anahtar değerleri oluşturabilirsiniz . Azure Uygulama Yapılandırması'ndan anahtar-değerleri yüklerken, yapılandırma sağlayıcısı geçerli JSON içerik türünün (uygulama/json gibi) anahtar değerlerini otomatik olarak seri durumdan çıkarılmış bir Python nesnesine dönüştürür.

{
    "key": "font",
    "label": null,
    "value": "{\r\n\t\"size\": 12,\r\n\t\"color\": \"red\"\r\n}",
    "content_type": "application/json"
}

Bu JSON içeriği anahtar değerinin olarak { size: 12, color: "red" }yüklenmesine neden olur.

appConfig = load(endpoint, credential)
size = appConfig["font"]["size"]
color = appConfig["font"]["color"]

Uyarı

2.2.0 sürümünden azure-appconfiguration-providerbaşlayarak, yapılandırma sağlayıcısı içerik türüne sahip anahtar değerlerinde (application/json) tanımlandığı gibi açıklamalara izin verir.

Seçicileri kullanarak belirli anahtar değerlerini yükleme

Varsayılan olarak, load yöntemi yapılandırma deposundan etiket içermeyen tüm yapılandırmaları yükler. yönteminin load davranışını, bir selects listesi olan SettingSelector isteğe bağlı parametresiyle yapılandırabilirsiniz.

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)

Uyarı

Anahtar-değerler, seçicilerin listelendiği sırayla yüklenir. Birden çok seçici aynı anahtara sahip anahtar-değerleri alırsa, sonuncudaki değer daha önce yüklenmiş olan tüm değerleri geçersiz kılar.

Etiket filtreleri

Etiket filtreleri parametresi, belirli etiketlere sahip anahtar-değerleri seçer. Anahtar-değer yalnızca filtrelerde belirtilen tüm etiketlere ve karşılık gelen değerlere sahipse yüklenir.

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)

Uyarı

Yıldız işareti (*), virgül (,) ve ters eğik çizgi (\) karakterleri ayrılmıştır ve etiket filtresinde kullanıldığında ters eğik çizgiyle kaçış karakteriyle kullanılmalıdır.

Anlık görüntülerden yapılandırma yükleme

anlık görüntülerden yapılandırma ayarlarını snapshot_name parametresini SettingSelector kullanarak yükleyebilirsiniz. Bir anlık görüntü adı belirttiğinizde, bu anlık görüntüden tüm yapılandırma ayarları yüklenir. snapshot_name parametresi , key_filterveya label_filterile tag_filterskullanılamaz.

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)

Uyarı

Paketin 2.3.0 veya sonraki bir azure-appconfiguration-provider sürümünü kullanıyorsanız anlık görüntü desteği sağlanır. Yapılandırma sağlayıcısı kullanılarak yalnızca oluşturma türü Key olan anlık görüntüler yüklenebilir.

Kesme tuşları

load işlevine, trim_prefixes parametresi aracılığıyla kırpılmış anahtar ön eklerinin bir listesini sağlayarak anahtarların ön eklerini kırpabilirsiniz.

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"

Yapılandırma ayarı eşlemesi

parametresi, configuration_mapper yapılandırma ayarlarını işlemeden ve sağlayıcıya eklenmeden önce dönüştürmenizi sağlar. Eşleyici işlevi her ConfigurationSetting nesneyi alır ve yerinde değiştirebilir.

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)

Eşleyici işlevi, mağazadan yüklenen her yapılandırma ayarı için çağrılır ve şunları yapmanızı sağlar:

  • Ayar değerlerini eklenmeden önce değiştirme
  • Değerleri dönüştürme veya şifresini çözme
  • Ayar anahtarına, etikete veya içerik türüne göre özel işleme gerçekleştirme

Uyarı

Anahtar kesme uygulanmadan önce mapper çağrılır. Eşleştirici işlevinizdeki koşulları denetlerken özgün anahtarı kullanın.

Zaman uyumsuz işlemler için bir asenkron eşleyici fonksiyonu sağlayın.

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)

Yapılandırma yenilemesi

Sağlayıcı, uygulamayı yeniden başlatmak zorunda kalmadan Uygulama Yapılandırma deposundan en son ayarları çekecek şekilde yapılandırılabilir. Bu davranışı etkinleştirmek için parametresini refresh_on kullanabilirsiniz. refresh_on parametresi, değişiklikler için izleyebileceğiniz bir veya daha fazla anahtarı/etiketi belirten bir List[WatchKey]'dir. Sunucuda seçilen anahtar-değerlerde herhangi bir değişiklik algılandığında yüklenen yapılandırma güncelleştirilir. Varsayılan olarak, 30 saniyelik bir yenileme aralığı kullanılır, ancak bunu parametresiyle refresh_interval geçersiz kılabilirsiniz.

on_refresh_success geri çağırma işlevi yalnızca bir değişiklik tespit edildiğinde ve herhangi bir hata meydana gelmediğinde çağrılır. Yenileme on_refresh_error başarısız olduğunda geri çağırma çağrılır.

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 tek başına ayarlamak yapılandırmayı otomatik olarak yenilemez. Yenilemeyi refresh tetiklemek için yöntemi tarafından AzureAppConfigurationProvider döndürülen örnekte yöntemini load çağırmanız gerekir.

config.refresh()

Bu tasarım, uygulamanız boşta olduğunda gereksiz isteklerin Uygulama Yapılandırması engeller. Çağrıyı refresh uygulama etkinliğinizin gerçekleştiği yere eklemeniz gerekir. Bu işlem etkinlik temelli yapılandırma yenilemesi olarak bilinir. Örneğin, gelen bir isteği işlerken veya karmaşık bir görev gerçekleştirdiğiniz bir yinelemenin içinde çağırabilirsiniz refresh . Eğer yenileme başarısız olursa, on_refresh_error sağlanmadıkça bir hata oluşturulacaktır. Yenileme refresh aralığı dolmadıysa yöntemi bir no-op. Ayrıca, bir seferde yalnızca bir yenileme denetimi gerçekleşebilir ve yenileme hâlihazırda devam ediyorsa herhangi bir işlem yapmadan geri döner.

Özellik bayrağı

Azure Uygulaması Yapılandırması'nda özellik bayrakları oluşturabilirsiniz. Varsayılan olarak, yapılandırma sağlayıcısı özellik bayraklarını yüklemez. Özellik bayraklarının yüklenmesini ve yenilenmesini parametresi aracılığıyla feature_flags_enabled etkinleştirebilirsiniz.

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

Varsayılan olarak, feature_flags_enabled ayarlandığında etiketi olmayan tüm özellik bayrakları yüklenirTrue. Özellik bayraklarını belirli bir etiketle yüklemek istiyorsanız, feature_flag_selectors nesne listesini alan SettingSelector parametresini kullanarak özellik bayraklarını filtreleyebilirsiniz.

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"])

Uyarı

Azure Uygulama Yapılandırması'ndan yüklenen özellik bayraklarını etkili bir şekilde kullanmak ve yönetmek için featuremanagement kitaplığını yükleyin ve kullanın. Bu kitaplık, uygulamanızdaki özellik davranışını denetlemek için yapılandırılmış bir yol sağlar.

Özellik yönetimi

Özellik yönetimi kitaplığı, özellik bayraklarını temel alarak uygulama işlevselliği geliştirmenin ve kullanıma sunmanın bir yolunu sağlar. Özellik yönetimi kitaplığı, yapılandırma sağlayıcısı kitaplığıyla birlikte çalışacak şekilde tasarlanmıştır. Yapılandırma sağlayıcısı, seçilen tüm özellik bayraklarını feature_flags bölümündeki feature_management listesinin altındaki yapılandırmaya yükler. Özellik yönetimi kitaplığı, uygulamanız için yüklenen özellik bayraklarını tüketir ve yönetir.

Aşağıdaki örnek, featuremanagement kütüphanesinin yapılandırma sağlayıcısıyla tümleştirerek, Express uygulamasında API erişilebilirliğini, özellik bayrağının Beta durumuna bağlı olarak dinamik olarak kontrol etmeyi göstermektedir.

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 özellik yönetimi kitaplığını kullanma hakkında daha fazla bilgi için özellik bayrağı hızlı başlangıç kılavuzuna gidin.

Özellik kontrol bayrağı telemetrisi

Özellik bayrağı telemetrisi etkinleştirildiğinde, Azure Uygulama Yapılandırması sağlayıcısı özellik bayrağı telemetri verilerine ek özellikler ekler. Bu özellikler özellik bayrağı ve değerlendirmesi hakkında daha fazla bağlam sağlar:

  • AllocationID: Özellik bayrağının ayırma durumunu temsil eden benzersiz tanımlayıcı.
  • ETag: Özellik bayrağı için geçerli ETag.
  • FeatureFlagReference: Özellik bayrağına biçiminde <your_store_endpoint>kv/<feature_flag_key> bir referans. Bir etiket mevcut olduğunda, başvuru bunu sorgu parametresi olarak içerir: <your_store_endpoint>kv/<feature_flag_key>?label=<feature_flag_label>.

Tam şema , Uygulama Yapılandırması Özellik Değerlendirme Olayı şema tanımında bulunabilir. Özellik bayrakları telemetrisini nasıl kullanacağınız hakkında daha fazla bilgi için özellik bayrakları için telemetriyi etkinleştirme kılavuzuna gidin.

Özellik işaretçilerini yenileme

Özellik bayrakları için yenilemeyi etkinleştirmek için ayarını yapmanız feature_flag_refresh_enabled=Truegerekir. Bu parametre, sağlayıcının özellik bayraklarını yapılandırmaları yenilediğinden aynı şekilde yenilemesine olanak tanır. Yapılandırmalardan farklı olarak, tüm yüklenen özellik bayrakları değişiklikler için izlenir ve yenilemeye neden olur. Yapılandırma ayarlarının ve özellik bayraklarının yenilenmesi birbirinden bağımsızdır. Hem yapılandırma ayarları hem de özellik bayrakları yöntemiyle refresh güncelleştirilir, ancak özellik bayrağının değiştirilmesi yapılandırmaların yenilenmesine neden olmaz ve tam tersi de geçerlidir. Ayrıca, yapılandırma ayarları için yenileme etkin değilse, özellik bayrakları yenileme için hala etkinleştirilebilir.

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

# Later in your code
config.refresh()

Key Vault başvurusu

Azure Uygulaması Yapılandırması, Azure Key Vault'ta depolanan gizli dizilere başvurmayı destekler. Uygulama Yapılandırması'da Key Vault'ta depolanan gizli dizilere eşleyen anahtarlar oluşturabilirsiniz. Gizli diziler Key Vault'ta güvenli bir şekilde depolanır, ancak yüklendikten sonra diğer yapılandırmalar gibi erişilebilir.

Yapılandırma sağlayıcısı kitaplığı, Uygulama Yapılandırması'de depolanan diğer anahtarlarda olduğu gibi Key Vault başvurularını da alır. İstemci anahtarları Key Vault başvuruları olarak tanıdığından, benzersiz bir içerik türüne sahiptir ve istemci, uygulamanızın değerlerini almak için Key Vault'a bağlanır. Kimlik bilgisi sağlayarak veya istemciler sağlayarak Key Vault'a bağlanmak için bir yol yapılandırmanız gerekir.

Kimlik bilgileriyle

Bağımsız değişkeni keyvault_credential bir kimlik bilgisiyle ayarlayabilirsiniz ve tüm anahtar kasası referansları bununla çözümlenir. Sağlayıcı, sağlanan kimlik bilgileriyle referans verilen herhangi bir anahtar kasasına bağlanmayı dener.

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


config = load(endpoint=endpoint, credential=DefaultAzureCredential(), keyvault_credential=DefaultAzureCredential())

Müşterilerle

Bağımsız değişkeni keyvault_client_configs istemci yapılandırmaları sözlüğüyle ayarlayabilirsiniz.

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)

Uyarı

Sağlanan ek özellikler oluşturma işlemine SecretClientgeçirilir.

Gizli çözücü

Hiçbir kimlik bilgisi veya istemci sağlanmazsa, gizli anahtar çözümleyici kullanılabilir. Gizli çözümleyici, anahtar kasası referansına istediğiniz değeri döndürmenin bir yolunu sağlar.

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 sırrı yenileme

Azure Uygulama Yapılandırması, gizli dizi yenileme aralıklarını yapılandırma yenileme döngünüzden bağımsız olarak yapılandırmanıza olanak tanır. Bu güvenlik açısından çok önemlidir çünkü Uygulama Yapılandırması'ndaki Key Vault başvuru URI'si değişmeden kalırken, Key Vault'taki temel gizli dizi güvenlik uygulamalarınızın bir parçası olarak döndürülebilir.

Uygulamanızın her zaman en güncel gizli anahtar değerlerini kullandığından emin olmak için secret_refresh_interval içindeki load anahtar sözcüğü yapılandırın. Bu, aşağıdaki durumlarda sağlayıcıyı Key Vault'tan yeni gizli anahtar değerlerini almaya zorlar:

  • Uygulamanız refresh çağrısı yapıyor
  • Gizli için yapılandırılan yenileme aralığının süresi doldu

Bu mekanizma, Uygulama Yapılandırma deponuzda hiçbir değişiklik algılanmadığında bile çalışır ve uygulamanızın döndürülen gizli dizilerle eşitlenmiş durumda kalmasını sağlar.

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
)

Coğrafi çoğaltma

Azure Uygulama Yapılandırma Sağlayıcısı kitaplığı, sağlanan yapılandırma deposunun replikalarını otomatik olarak bulur ve herhangi bir sorun meydana geldiğinde bu replikaları kullanır. Daha fazla bilgi için bkz. Coğrafi çoğaltma.

Replika keşfi varsayılan olarak etkindir. Devre dışı bırakmak isterseniz, replica_discovery_enabled öğesini False olarak ayarlayabilirsiniz.

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

config = load(
    endpoint=endpoint, 
    credential=DefaultAzureCredential(), 
    replica_discovery_enabled=False
)

Sonraki Adımlar

Python yapılandırma sağlayıcısını kullanmayı öğrenmek için aşağıdaki öğreticiye geçin.

Python'da dinamik yapılandırmayı kullanma

Sağlayıcıyı bir web uygulamasında nasıl kullanacağınızı görmek için Django ve Flask örneklerimize göz atın.

Django örneği

Flask örneği

  • Last updated on