Python-konfigurationsprovider

Azure App Configuration är en hanterad tjänst som hjälper utvecklare att centralisera sina programkonfigurationer enkelt och säkert. Python-konfigurationsproviderbiblioteket möjliggör inläsning av konfiguration från ett Azure App Configuration-arkiv på ett hanterat sätt. Det här klientbiblioteket lägger till ytterligare funktioner ovanpå Azure SDK för Python.

Installera paketet

Installera Azure App Configuration Provider-paketet med pip:

pip install azure-appconfiguration-provider

För att kunna använda Microsoft Entra-ID krävs även Azure Identity.

pip install azure-identity

Läs in konfiguration

Funktionen load i azure-appconfiguration-provider paketet används för att läsa in konfigurationen från Azure App Configuration. Med load funktionen kan du antingen använda Microsoft Entra-ID (rekommenderas) eller en anslutningssträng för att ansluta till App Configuration Store.

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

Funktionen load returnerar en instans av AzureAppConfigurationProvider, som är ett ordlisteliknande objekt, som innehåller alla konfigurationsvärden som läses in från App Configuration Store. Som standardinställning läser providern in alla konfigurationsvärden utan etikett från arkivet.

Hantering av JSON-innehållstyp

Du kan skapa JSON-nyckelvärden i App Configuration. När du läser in nyckelvärden från Azure App Configuration konverterar konfigurationsprovidern automatiskt nyckelvärdena för giltig JSON-innehållstyp (till exempel program/json) till ett deserialiserat Python-objekt.

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

Det här JSON-innehållet resulterar i nyckelvärdet som ska läsas in som { size: 12, color: "red" }.

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

Läs in specifika nyckelvärden med hjälp av väljare

Som standardinställning läser metoden in alla konfigurationer utan etikett från konfigurationsarkivet. Du kan konfigurera metodens load beteende via den valfria parametern selects, som är en lista över SettingSelectors.

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)

Filter för taggar

Parametern taggfilter väljer nyckelvärden med specifika taggar. Ett nyckelvärde läses bara in om alla taggar och motsvarande värden anges i filtren.

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)

Läs in konfiguration från snapshot-filer

Du kan läsa in konfigurationsinställningar från ögonblicksbilder med hjälp av parametern snapshot_name i SettingSelector. När du anger ett namn på ögonblicksbilden läses alla konfigurationsinställningar från ögonblicksbilden in. Parametern snapshot_name kan inte användas med key_filter, label_filtereller 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)

Trimma nycklar

Du kan trimma bort prefixet från nycklar genom att ange en lista över trimmade nyckelprefix till load funktionen via parametern 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"

Mappning av konfigurationsinställning

Med configuration_mapper parametern kan du transformera konfigurationsinställningarna innan de bearbetas och läggs till i providern. Mappningsfunktionen tar emot varje ConfigurationSetting objekt och kan ändra det på plats.

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)

Mapper-funktionen anropas för varje konfigurationsinställning som läses in från lagret, vilket gör att du kan:

• Ändra inställningsvärden innan de läggs till
• Transformera eller dekryptera värden
• Utföra anpassad bearbetning baserat på inställningsnyckel, etikett eller innehållstyp

För asynkrona åtgärder anger du en asynkron mappningsfunktion:

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)

Uppdatering av konfiguration

Providern kan konfigureras för att hämta de senaste inställningarna från App Configuration Store utan att behöva starta om programmet. Du kan använda parametern refresh_on för att aktivera det här beteendet. Parametern refresh_on är en List[WatchKey], som anger en eller flera nyckel/etiketter för att hålla utkik efter ändringar. Den inlästa konfigurationen uppdateras när alla ändringar av valda nyckelvärden identifieras på servern. Som standard används ett uppdateringsintervall på 30 sekunder, men du kan åsidosätta det med parametern refresh_interval .

Återanropet on_refresh_success anropas endast om en ändring identifieras och inget fel inträffar. Återanropet on_refresh_error anropas när en uppdatering misslyckas.

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
)

Konfigurationen uppdateras inte automatiskt bara för att refresh_on är konfigurerad. Du måste anropa metoden på refresh den AzureAppConfigurationProvider instans som returneras av load metoden för att utlösa en uppdatering.

config.refresh()

Den här designen förhindrar onödiga begäranden till App Configuration när programmet är inaktivt. Du bör inkludera anropet där programaktiviteten refresh inträffar. Den här processen kallas aktivitetsdriven konfigurationsuppdatering. Du kan till exempel anropa refresh när du bearbetar en inkommande begäran eller inuti en iteration där du utför en komplex uppgift. Om uppdateringen misslyckas genereras ett fel, såvida inte ett on_refresh_error anges. Metoden refresh är en no-op om uppdateringsintervallet inte har förflutit. Dessutom kan endast en uppdateringskontroll ske i taget och returneras som en no-op om en uppdatering redan pågår.

Funktionsflagga

Du kan skapa funktionsflaggor i Azure App Configuration. Konfigurationsprovidern läser som standard inte in funktionsflaggor. Du kan aktivera inläsning och uppdatering av funktionsflaggor via parametern feature_flags_enabled .

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

Som standardinställning läses alla funktionsflaggor utan etikett in när feature_flags_enabled är inställt på True. Om du vill läsa in funktionsflaggor med en specifik etikett kan du använda parametern feature_flag_selectors för att filtrera funktionsflaggor, som tar in en lista med SettingSelector objekt.

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

Funktionshantering

Funktionshanteringsbiblioteket är ett sätt att utveckla och exponera programfunktioner baserat på funktionsflaggor. Funktionshanteringsbiblioteket är utformat för att fungera tillsammans med konfigurationsproviderbiblioteket. Konfigurationsleverantören laddar alla valda funktionsflaggor in i konfigurationen under feature_flags-listan i feature_management-avsnittet. Funktionshanteringsbiblioteket använder och hanterar de inlästa funktionsflaggorna för ditt program.

I följande exempel visas hur du integrerar featuremanagement biblioteket med konfigurationsleverantören för att dynamiskt kontrollera API-tillgänglighet i en Express-applikation baserat på status för funktionsflaggan 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")}")

Mer information om hur du använder Python-funktionshanteringsbiblioteket finns i snabbstarten för funktionsflaggan.

Telemetri för funktionalitetsflaggor

När telemetri för funktionsflagga är aktiverad matar Azure App Configuration-providern in ytterligare egenskaper till telemetridata för funktionsflagga. De här egenskaperna ger mer kontext om funktionsflaggan och dess utvärdering:

• AllocationID: En unik identifierare som representerar tillståndet för funktionsflaggans allokering.
• ETag: Aktuell ETag för funktionsflaggan.
• FeatureFlagReference: En referens till funktionsflaggan i formatet <your_store_endpoint>kv/<feature_flag_key>. När en etikett finns innehåller referensen den som en frågeparameter: <your_store_endpoint>kv/<feature_flag_key>?label=<feature_flag_label>.

Det fullständiga schemat finns i schemadefinitionen för händelseschema för appkonfigurationsfunktionsutvärdering. Mer information om hur du använder telemetri för funktionsflaggan finns i genomgången aktivera telemetri för funktionsflaggor .

Uppdatering av funktionsflagga

Om du vill aktivera uppdatering för funktionsflaggor måste du ange feature_flag_refresh_enabled=True. Med den här parametern kan providern uppdatera funktionsflaggor på samma sätt som den uppdaterar konfigurationerna. Till skillnad från konfigurationer övervakas alla inlästa funktionsflaggor för ändringar och initierar en uppdatering. Uppdatering av konfigurationsinställningar och funktionsflaggor är oberoende av varandra. Både konfigurationsinställningar och funktionsflaggor uppdateras med refresh metoden, men en ändring av funktionsflaggan orsakar inte en uppdatering av konfigurationer och vice versa. Om uppdatering för konfigurationsinställningar inte är aktiverad kan funktionsflaggor fortfarande aktiveras för uppdatering.

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

# Later in your code
config.refresh()

Key Vault-referens

Azure App Configuration har stöd för att referera till hemligheter som lagras i Azure Key Vault. I App Configuration kan du skapa nycklar som mappar till hemligheter som lagras i Key Vault. Hemligheterna lagras säkert i Key Vault, men kan nås som alla andra konfigurationer när de har lästs in.

Konfigurationsproviderbiblioteket hämtar Key Vault-referenser, precis som för andra nycklar som lagras i App Configuration. Eftersom klienten identifierar nycklarna som Key Vault-referenser har de en unik innehållstyp och klienten ansluter till Key Vault för att hämta sina värden för ditt program. Du måste konfigurera ett sätt att ansluta till Key Vault, antingen genom att ange en autentiseringsuppgift eller genom att tillhandahålla klienter.

Med autentiseringsuppgifter

Du kan ange argumentet keyvault_credential med en legitimation, och alla key vault-referenser löses med det. Providern försöker ansluta till alla nyckelvalv som refereras till med de angivna autentiseringsuppgifterna.

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


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

Med klienter

Du kan ange argumentet keyvault_client_configs med en ordlista med klientkonfigurationer.

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)

Hemlig lösning

Om inga autentiseringsuppgifter eller klienter anges kan en hemlig lösning användas. Hemlighetslösare ger ett sätt att returnera alla värden som du vill till en key vault-referens.

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)

Hemlig uppdatering av Key Vault

Med Azure App Configuration kan du konfigurera hemliga uppdateringsintervall oberoende av konfigurationsuppdateringscykeln. Detta är viktigt för säkerheten eftersom även om Key Vault-referens-URI:n i App Configuration förblir oförändrad, kan den underliggande hemligheten i Key Vault roteras som en del av dina säkerhetsrutiner.

För att säkerställa att ditt program alltid använder de senaste hemliga värdena konfigurerar du nyckelordet secret_refresh_interval i load. Detta tvingar providern att hämta nya hemliga värden från Key Vault när:

• Programmet anropar refresh
• Det konfigurerade uppdateringsintervallet för hemligheten har förflutit

Den här mekanismen fungerar även när inga ändringar identifieras i appkonfigurationsarkivet, vilket säkerställer att programmet förblir synkroniserat med roterade hemligheter.

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-biblioteket identifierar automatiskt det angivna konfigurationsarkivets repliker och använder replikerna om något problem uppstår. Mer information finns i geo-replikering.

Replikidentifiering är aktiverat som standard. Om du vill inaktivera det kan du ange replica_discovery_enabled till False.

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

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

Nästa steg

För att lära dig hur man använder Python-konfigurationsprovidern, fortsätt till följande handledning.

Om du vill se hur du använder providern i ett webbprogram kan du läsa våra Django- och Flask-exempel.