Python-configuratieprovider

Azure App Configuration is een beheerde service waarmee ontwikkelaars hun toepassingsconfiguraties eenvoudig en veilig kunnen centraliseren. Met de Python-configuratieproviderbibliotheek kunt u op een beheerde manier configuratie laden vanuit een Azure App Configuration-store. Deze clientbibliotheek voegt extra functionaliteit toe boven op de Azure SDK voor Python.

Installeer het pakket

Installeer het Azure App Configuration Provider-pakket met pip.

pip install azure-appconfiguration-provider

Als u Microsoft Entra ID wilt gebruiken, is Azure Identity ook nodig.

pip install azure-identity

Configuratie laden

De load functie in het pakket wordt gebruikt voor het azure-appconfiguration-provider laden van de configuratie vanuit Azure App Configuration. Met load kunt u Microsoft Entra ID (aanbevolen) of een verbindingsreeks gebruiken om verbinding te maken met de 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

De load functie retourneert een exemplaar van AzureAppConfigurationProvider, een woordenlijstachtig object, bevat alle configuratiewaarden die zijn geladen vanuit het App Configuration-archief. De provider laadt standaard alle configuratiewaarden zonder label uit de opslag.

Verwerking van JSON-inhoudstypen

U kunt JSON-sleutelwaarden maken in App Configuration. Bij het laden van sleutelwaarden uit Azure App Configuration converteert de configuratieprovider automatisch de sleutelwaarden van het geldige JSON-inhoudstype (bijvoorbeeld toepassing/json) naar een gedeserialiseerd Python-object.

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

Deze JSON-inhoud resulteert in dat de sleutelwaarde wordt geladen als { size: 12, color: "red" }.

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

Specifieke sleutelwaarden laden met behulp van selectors

Standaard laadt de methode load alle configuraties zonder label uit het configuratiearchief. U kunt het gedrag van de load methode configureren via de optionele parameter van selects, een lijst met 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)

Tagfilters

De parameter tagfilters selecteert sleutelwaarden met specifieke tags. Een sleutelwaarde wordt alleen geladen als deze alle tags en bijbehorende waarden bevat die zijn opgegeven in de filters.

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)

Configuratie laden vanuit momentopnamen

U kunt configuratie-instellingen laden vanuit momentopnamen met behulp van de snapshot_name parameter in SettingSelector. Wanneer u een naam voor een momentopname opgeeft, worden alle configuratie-instellingen van die momentopname geladen. De snapshot_name parameter kan niet worden gebruikt met key_filter, label_filterof 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)

Verwijzing naar momentopname

Een momentopnameverwijzing is een configuratie-instelling die verwijst naar een momentopname in hetzelfde App Configuration-archief. Wanneer deze is geladen, wordt deze door de provider omgezet en worden alle sleutelwaarden uit die momentopname toegevoegd. Met behulp van momentopnameverwijzingen schakelt u tijdens runtime tussen momentopnamen, in tegenstelling tot het toevoegen van een momentopnamekiezer, waarvoor codewijzigingen en/of opnieuw moeten worden opgestart om over te schakelen naar een nieuwe momentopname.

Ga naar het concept voor momentopnamereferenties voor meer informatie over het maken van een momentopnamereferentie.

Bijsnijden van sleutels

U kunt het voorvoegsel van sleutels knippen door een lijst met bijgesneden sleutelvoorvoegsels op te geven voor de load functie, via de trim_prefixes parameter.

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"

Toewijzing van configuratie-instellingen

configuration_mapper Met de parameter kunt u configuratie-instellingen transformeren voordat ze worden verwerkt en toegevoegd aan de provider. De mapper-functie ontvangt elk ConfigurationSetting object en kan het ter plaatse wijzigen.

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)

De mapper-functie wordt aangeroepen voor elke configuratie-instelling die uit de opslag wordt geladen, waardoor u het volgende kunt doen:

• Instellingswaarden wijzigen voordat ze worden toegevoegd
• Waarden transformeren of ontsleutelen
• Aangepaste verwerking uitvoeren op basis van de instellingssleutel, het label of het inhoudstype

Geef voor asynchrone bewerkingen een asynchrone mapper-functie op:

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)

Configuratie vernieuwen

De provider kan worden geconfigureerd om de meest recente instellingen op te halen uit het App Configuration-archief zonder dat de toepassing opnieuw hoeft te worden opgestart. Als u de instellingen wilt vernieuwen, zorg er dan voor dat refresh_enabled is ingesteld op True en roep de refresh-methode aan op het AzureAppConfigurationProvider-exemplaar dat wordt geretourneerd door de load-methode.

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()

Standaard wordt een vernieuwingsinterval van 30 seconden gebruikt, maar u kunt dit overschrijven met de refresh_interval parameter. De provider bewaakt alle geladen sleutelwaarden voor wijzigingen.

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

Dit ontwerp voorkomt onnodige aanvragen voor App Configuration wanneer uw toepassing niet actief is. Neem de aanroep refresh op op de plaats waar de activiteit van uw toepassing plaatsvindt. Dit proces wordt ook wel activiteitgestuurde configuratievernieuwing genoemd. U kunt bijvoorbeeld aanroepen refresh bij het verwerken van een binnenkomende aanvraag of binnen een iteratie waarin u een complexe taak uitvoert.

Zelfs als de vernieuwingsoproep om welke reden dan ook mislukt, blijft uw toepassing de configuratie in de cache gebruiken. Er wordt nog een poging gedaan wanneer het geconfigureerde vernieuwingsinterval is verstreken en de vernieuwingsoproep wordt geactiveerd door uw toepassingsactiviteit. Het aanroepen van refresh is geen operationele handeling voordat het geconfigureerde vernieuwingsinterval voorbij is, dus de invloed op de prestaties is minimaal, zelfs als het vaak wordt aangeroepen.

Aangepaste vernieuwingscallback

De on_refresh_success callback wordt alleen aangeroepen als er een wijziging wordt gedetecteerd en er geen fout optreedt. De on_refresh_error callback wordt aangeroepen wanneer een vernieuwing mislukt.

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
)

Vernieuwen wanneer specifieke sleutels worden gewijzigd

U kunt de refresh_on parameter gebruiken om de provider te configureren voor het bewaken van specifieke controlesleutels voor wijzigingen in plaats van alle geladen sleutelwaarden te bewaken. De parameter refresh_on is een List[WatchKey], waarmee een of meer sleutels/labels worden opgegeven om te monitoren op wijzigingen. Wanneer een wijziging wordt gedetecteerd in een van de gevolgde sleutels, worden alle configuratiewaarden vernieuwd.

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

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

Functievlag

U kunt functievlagmen maken in Azure App Configuration. De configuratieprovider laadt standaard geen functievlagmen. U kunt het laden en vernieuwen van functievlagmen inschakelen via de feature_flag_enabled parameter.

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

Standaard worden alle functievlagmen zonder label geladen wanneer u deze instelt feature_flag_enabled op True. Als u functievlagmen met een specifiek label wilt laden, gebruikt u de feature_flag_selectors parameter om de functievlagmen te filteren. Deze parameter gebruikt een lijst met SettingSelector objecten.

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

Functiebeheer

De bibliotheek voor functiebeheer biedt een manier om toepassingsfunctionaliteit te ontwikkelen en beschikbaar te maken op basis van functievlagmen. De bibliotheek voor functiebeheer is ontworpen om samen te werken met de configuratieproviderbibliotheek. De configuratieprovider laadt alle geselecteerde functievlagmen in de configuratie onder de feature_flags lijst van de feature_management sectie. De bibliotheek voor functiebeheer gebruikt en beheert de geladen functievlagmen voor uw toepassing.

In het volgende voorbeeld ziet u hoe u de featuremanagement bibliotheek integreert met de configuratieprovider om de API-toegankelijkheid in een Express-toepassing dynamisch te beheren op basis van de status van de Beta functievlag.

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

Ga voor meer informatie over het gebruik van de Python functiebeheerbibliotheek naar de functievlag quickstart.

Functievlagtelemetrie

Wanneer telemetrie van functies is ingeschakeld, injecteert de Azure App Configuration provider aanvullende eigenschappen aan de telemetriegegevens van functies. Deze eigenschappen bieden meer context over de functievlag en de bijbehorende evaluatie:

• AllocationID: een unieke id die de status van de toewijzing van de functievlag aangeeft.
• ETag: de huidige ETag voor de functievlag.
• FeatureFlagReference: een verwijzing naar de functievlag in de indeling van <AppConfigurationEndpoint>kv/<FeatureFlagKey>. Wanneer een label aanwezig is, bevat de verwijzing deze als een queryparameter: <AppConfigurationEndpoint>kv/<FeatureFlagKey>?label=<FeatureFlagLabel>.

Het volledige schema vindt u in de definitie van het gebeurtenisschema voor de evaluatie van de functie van de app-configuratiefunctie. Ga voor meer informatie over het gebruik van de telemetrie voor functie-vlaggen naar de telemetrie inschakelen voor functie-vlaggen handleiding.

Functievlag bijwerken

Als u verversen voor functievlaggen wilt inschakelen, moet u feature_flag_refresh_enabled=True instellen. Met deze parameter kan de provider functievlagmen vernieuwen op dezelfde manier als configuraties worden vernieuwd. In tegenstelling tot configuraties worden alle geladen functievlaggen gecontroleerd op wijzigingen en veroorzaken een verversing. Vernieuwen van configuratie-instellingen en functievlagmen zijn onafhankelijk van elkaar. Zowel configuratie-instellingen als functievlagmen worden bijgewerkt door de refresh methode, maar het wijzigen van een functievlag veroorzaakt geen vernieuwing van configuraties en omgekeerd. Als het vernieuwen van configuratie-instellingen niet is ingeschakeld, kunnen functievlaggen nog steeds worden ingeschakeld voor vernieuwing.

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

# Later in your code
config.refresh()

Naslaginformatie voor Key Vault

Azure-app Configuration ondersteunt het verwijzen naar geheimen die zijn opgeslagen in Azure Key Vault. In App Configuration kunt u sleutels maken die zijn toegewezen aan geheimen die zijn opgeslagen in Key Vault. De geheimen worden veilig opgeslagen in Key Vault, maar kunnen net als elke andere configuratie worden geopend nadat ze zijn geladen.

De bibliotheek van de configuratieprovider haalt key Vault-verwijzingen op, net zoals voor andere sleutels die zijn opgeslagen in App Configuration. Omdat de client de sleutels herkent als Key Vault-verwijzingen, hebben ze een uniek inhoudstype en maakt de client verbinding met Key Vault om hun waarden voor uw toepassing op te halen. U moet een manier configureren om verbinding te maken met de Key Vault, hetzij door een referentie op te geven of door clients op te geven.

Met authenticatiegegevens

U kunt het argument keyvault_credential instellen met een credential, en daarmee worden alle verwijzingen naar sleutelkasten opgelost. De provider probeert verbinding te maken met een Key Vault waarnaar wordt verwezen met de opgegeven referentie.

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


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

Met klanten

U kunt het argument keyvault_client_configs instellen met een woordenlijst met clientconfiguraties.

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)

Geheime resolver

Als er geen referenties of clients worden opgegeven, kan een geheime resolver worden gebruikt. Geheime resolver biedt een manier om elke gewenste waarde te retourneren naar een sleutelkluisverwijzing.

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 geheim verversen

Met Azure App Configuration kunt u geheime vernieuwingsintervallen onafhankelijk van uw configuratievernieuwingscyclus configureren. Dit is van cruciaal belang voor beveiliging, omdat de Key Vault-referentie-URI in App Configuration ongewijzigd blijft, het onderliggende geheim in Key Vault mogelijk wordt geroteerd als onderdeel van uw beveiligingsprocedures.

Om ervoor te zorgen dat uw toepassing altijd de meest recente geheime waarden gebruikt, configureert u het secret_refresh_interval sleutelwoord in load. Dit dwingt de provider om nieuwe geheime waarden op te halen uit Key Vault wanneer:

• Uw toepassingsoproepen refresh
• Het geconfigureerde vernieuwingsinterval voor het geheim is verstreken

Dit mechanisme werkt zelfs wanneer er geen wijzigingen worden gedetecteerd in uw App Configuration-winkel, zodat uw toepassing gesynchroniseerd blijft met gewisselde geheimen.

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
)

Opnieuw opstarten

Het laden van de configuratie is een kritieke padbewerking tijdens het opstarten van de toepassing. Om de betrouwbaarheid te garanderen, implementeert de Azure App Configuration-provider een robuust mechanisme voor opnieuw proberen tijdens de eerste configuratiebelasting. Dit helpt uw toepassing te beschermen tegen tijdelijke netwerkproblemen die anders kunnen voorkomen dat het opstarten is geslaagd.

U kunt dit gedrag aanpassen door de startup_timeout parameter in te stellen, waarmee de hoeveelheid tijd in seconden wordt opgegeven die is toegestaan om gegevens te laden van Azure App Configuration bij het opstarten. De standaardwaarde is 100 seconden.

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

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

Geo-replicatie

De Azure App Configuration Provider-bibliotheek detecteert automatisch de replica's van het opgegeven configuratiearchief en gebruikt de replica's als er een probleem optreedt. Zie geo-replicatie voor meer informatie.

Replicadetectie is standaard ingeschakeld. Als u het wilt uitschakelen, kunt u instellen replica_discovery_enabled op False.

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

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

Volgende stappen

Als u wilt weten hoe u de Python-configuratieprovider gebruikt, gaat u verder met de volgende zelfstudie.

Bekijk onze Django- en Flask-voorbeelden om te zien hoe u de provider gebruikt in een webtoepassing.