Udostępnij za pośrednictwem

Dostawca konfiguracji języka Python

Pakiet języka Python

Usługa Azure App Configuration to usługa zarządzana, która pomaga deweloperom w prosty i bezpieczny sposób scentralizować konfigurację aplikacji. Biblioteka dostawcy konfiguracji języka Python umożliwia ładowanie konfiguracji z magazynu usługi Azure App Configuration w zarządzany sposób. Ta biblioteka klienta dodaje dodatkowe funkcje w oparciu o zestaw Azure SDK dla języka Python.

Instalowanie pakietu

Zainstaluj pakiet providera Azure App Configuration za pomocą narzędzia pip.

pip install azure-appconfiguration-provider

Aby korzystać z identyfikatora Entra firmy Microsoft, wymagana jest również tożsamość platformy Azure.

pip install azure-identity

Ładowanie konfiguracji

Funkcja load w pakiecie azure-appconfiguration-provider służy do ładowania konfiguracji z usługi Azure App Configuration. Funkcja load umożliwia użycie identyfikatora Entra firmy Microsoft (zalecane) lub parametrów połączenia w celu nawiązania połączenia z magazynem App Configuration.

Uwaga / Notatka

azure-appconfiguration-provider ma wersje synchroniczne from azure.appconfiguration.provider import load i asynchroniczne from azure.appconfiguration.provider.aio import load . W przypadku korzystania z wersji asynchronicznej należy użyć poświadczenia asynchronicznego, from azure.identity.aio import DefaultAzureCredential.

Aby się uwierzytelnić w sklepie App Configuration, używasz DefaultAzureCredential. Postępuj zgodnie z instrukcjami, aby przypisać swoje poświadczenie do roli Czytelnika danych konfiguracji aplikacji.

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

Funkcja load zwraca wystąpienie klasy AzureAppConfigurationProvider, które jest obiektem przypominającym słownik i zawiera wszystkie wartości konfiguracji załadowane ze sklepu App Configuration. Domyślnie dostawca ładuje wszystkie wartości konfiguracji bez etykiety ze sklepu.

Obsługa typów zawartości JSON

Możesz utworzyć wartości kluczy JSON w usłudze App Configuration. Podczas ładowania klucz-wartości z usługi Azure App Configuration dostawca konfiguracji automatycznie konwertuje klucz-wartości, które mają prawidłowy typ zawartości JSON (na przykład application/json), na obiekt deserializowany w języku Python.

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

Ta zawartość JSON powoduje załadowanie wartości klucza jako { size: 12, color: "red" }.

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

Uwaga / Notatka

Począwszy od wersji 2.2.0 programu azure-appconfiguration-provider, dostawca konfiguracji zezwala na komentarze zgodnie z definicją w formacie (JSONC) w wartościach klucza z typem application/json zawartości.

Ładowanie określonych klucz-wartości przy użyciu selektorów

Domyślnie metoda load ładuje z magazynu konfiguracji wszystkie konfiguracje bez etykiety. Zachowanie metody load można skonfigurować za pomocą opcjonalnego parametru selects, który jest listą 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)

Uwaga / Notatka

Wartości klucza są ładowane w kolejności, w której selektory są wyświetlane. Jeśli wiele selektorów pobiera wartości klucz-wartość z tym samym kluczem, wartość z ostatniego zastępuje dowolną wcześniej załadowaną wartość.

Filtry tagów

Parametr filtrów tagów wybiera wartości klucza z określonymi tagami. Wartość-klucz jest ładowana tylko wtedy, gdy zawiera wszystkie tagi i odpowiednie wartości określone w filtrach.

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)

Uwaga / Notatka

Znaki gwiazdki (*), przecinek (,) i ukośnik odwrotny (\) są zastrzeżone i muszą zostać uniknięte ukośnikiem odwrotnym, gdy są używane w filtrze tagu.

Wczytywanie konfiguracji z zrzutów

Ustawienia konfiguracji można załadować z migawek przy użyciu parametru snapshot_name w pliku SettingSelector. Po określeniu nazwy migawki zostaną załadowane wszystkie ustawienia konfiguracji z tej migawki. Nie można użyć parametru snapshot_name z parametrem key_filter, label_filterlub 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)

Uwaga / Notatka

Obsługa migawek jest dostępna, jeśli używasz wersji 2.3.0 lub nowszej azure-appconfiguration-provider pakietu. Za pomocą dostawcy konfiguracji można załadować tylko migawki utworzone z typem Key kompozycji.

Przycinanie kluczy

Prefiksy można usunąć z kluczy, podając listę prefiksów do usunięcia do funkcji load za pomocą parametru 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"

Mapowanie ustawień konfiguracji

Parametr configuration_mapper umożliwia przekształcenie ustawień konfiguracji przed ich przetworzeniem i dodaniu do dostawcy. Funkcja mapowania odbiera każdy ConfigurationSetting obiekt i może modyfikować go w miejscu.

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)

Funkcja mappera jest wywoływana dla każdego ustawienia konfiguracji załadowanego ze sklepu, co umożliwia:

  • Modyfikowanie wartości ustawień przed ich dodaniu
  • Przekształcanie lub odszyfrowywanie wartości
  • Wykonywanie przetwarzania niestandardowego na podstawie klucza ustawienia, etykiety lub typu zawartości

Uwaga / Notatka

Funkcja mapująca jest wywoływana przed zastosowaniem usuwania niepotrzebnych znaków z klucza. Użyj oryginalnego klucza podczas sprawdzania warunków w funkcji mapowania.

W przypadku operacji asynchronicznych podaj funkcję mapowania asynchronicznego:

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)

Odświeżanie konfiguracji

Można skonfigurować dostawcę w celu ściągnięcia najnowszych ustawień ze sklepu App Configuration bez konieczności ponownego uruchamiania aplikacji. Możesz użyć parametru refresh_on , aby włączyć to zachowanie. Parametr refresh_on jest parametrem List[WatchKey], który określa jeden lub więcej kluczy/etykiet, które mają być obserwowane pod kątem zmian. Załadowana konfiguracja jest aktualizowana po wykryciu dowolnej zmiany wybranych wartości kluczy na serwerze. Domyślnie jest używany interwał odświeżania wynoszący 30 sekund, ale można go zastąpić parametrem refresh_interval .

Callback on_refresh_success jest wywoływany tylko wtedy, gdy zostanie wykryta zmiana i nie wystąpi błąd. Callback on_refresh_error jest wywoływany, gdy odświeżanie się nie powiedzie.

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
)

Samo skonfigurowanie refresh_on nie powoduje automatycznego odświeżania konfiguracji. Aby wyzwolić odświeżanie, należy wywołać metodę refresh w AzureAppConfigurationProvider wystąpieniu load zwróconą przez metodę .

config.refresh()

Ten projekt uniemożliwia niepotrzebne żądania do usługi App Configuration, gdy aplikacja jest bezczynna. Należy dołączyć refresh wywołanie, w którym występuje działanie aplikacji. Ten proces jest znany jako odświeżanie konfiguracji opartej na działaniach. Można na przykład wywołać refresh metodę przetwarzania żądania przychodzącego lub wewnątrz iteracji, w której wykonujesz złożone zadanie. Jeśli odświeżanie zakończy się niepowodzeniem, zostanie zgłoszony błąd, chyba że zostanie podany element on_refresh_error. Metoda refresh nie wykonuje żadnej operacji, jeśli nie upłynął czas odświeżania. Ponadto w danym momencie może wystąpić tylko jedno sprawdzanie odświeżania, zwracając je jako no-op, jeśli odświeżanie jest już w toku.

Flaga funkcji

Flagi funkcji można tworzyć w konfiguracji aplikacja systemu Azure. Domyślnie dostawca konfiguracji nie ładuje flag funkcji. Flagi funkcji ładowania i odświeżania można włączyć za pomocą parametru feature_flags_enabled .

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

Domyślnie wszystkie flagi funkcji, które nie mają etykiety, są ładowane, gdy feature_flags_enabled jest ustawiona na True. Jeśli chcesz załadować flagi funkcji z określoną etykietą, możesz użyć parametru feature_flag_selectors , aby filtrować flagi funkcji, które pobierają listę SettingSelector obiektów.

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

Uwaga / Notatka

Aby efektywnie korzystać z flag funkcji załadowanych z usługi Azure App Configuration i nimi zarządzać, zainstaluj bibliotekę featuremanagement i korzystaj z niej. Ta biblioteka zapewnia ustrukturyzowany sposób kontrolowania zachowania funkcji w aplikacji.

Zarządzanie funkcjami

Biblioteka zarządzania funkcjami umożliwia opracowywanie i uwidacznianie funkcji na podstawie flag funkcji. Biblioteka zarządzania funkcjami jest przeznaczona do współpracy z biblioteką dostawcy konfiguracji. Dostawca konfiguracji ładuje wszystkie wybrane flagi cech do konfiguracji w liście feature_flags sekcji feature_management. Biblioteka zarządzania flagami funkcji korzysta z załadowanych flag funkcji i nimi zarządza.

W poniższym przykładzie pokazano, jak zintegrować bibliotekę featuremanagement z dostawcą konfiguracji w celu dynamicznego kontrolowania dostępu do API w aplikacji Express na podstawie stanu flag funkcji 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")}")

Aby uzyskać więcej informacji na temat korzystania z biblioteki zarządzania funkcjami języka Python, przejdź do przewodnika Szybki start flagi funkcji.

Telemetria flagi funkcji

Po włączeniu telemetrii flag funkcji, dostawca usługi Azure App Configuration wprowadza dodatkowe właściwości do danych telemetrycznych flag funkcji. Te właściwości dostarczają więcej kontekstu na temat flagi funkcji oraz jej oceny.

  • AllocationID: unikatowy identyfikator reprezentujący stan alokacji flagi funkcji.
  • ETag: bieżący element ETag flagi funkcji.
  • FeatureFlagReference: odwołanie do flagi funkcji w formacie <your_store_endpoint>kv/<feature_flag_key>. Gdy etykieta jest obecna, odwołanie zawiera go jako parametr zapytania: <your_store_endpoint>kv/<feature_flag_key>?label=<feature_flag_label>.

Pełny schemat można znaleźć w definicji schematu zdarzenia oceny funkcji konfiguracji aplikacji. Aby uzyskać więcej informacji na temat korzystania z telemetrii dla flag funkcji, przejdź do przewodnika wyłączania telemetrii dla flag funkcji.

Odświeżanie przełącznika funkcji

Aby włączyć odświeżanie flag funkcji, należy ustawić wartość feature_flag_refresh_enabled=True. Ten parametr umożliwia dostawcy odświeżanie flag funkcji w taki sam sposób, jak odświeżanie konfiguracji. W przeciwieństwie do konfiguracji wszystkie załadowane flagi funkcji są monitorowane pod kątem zmian i powodują odświeżenie. Odświeżanie ustawień konfiguracji i odświeżanie flag funkcji są niezależne od siebie. Zarówno ustawienia konfiguracji, jak i flagi funkcji są aktualizowane przez metodę refresh , ale zmiana flagi funkcji nie powoduje odświeżenia konfiguracji i odwrotnie. Ponadto jeśli odświeżanie ustawień konfiguracji nie jest włączone, flagi funkcji można nadal włączać na potrzeby odświeżania.

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

# Later in your code
config.refresh()

Dokumentacja usługi Key Vault

aplikacja systemu Azure Configuration obsługuje odwoływanie się do wpisów tajnych przechowywanych w usłudze Azure Key Vault. W usłudze App Configuration można tworzyć klucze mapowane na wpisy tajne przechowywane w usłudze Key Vault. Wpisy tajne są bezpiecznie przechowywane w usłudze Key Vault, ale można uzyskać dostęp do dowolnej innej konfiguracji po załadowaniu.

Biblioteka dostawcy konfiguracji pobiera odwołania do usługi Key Vault, podobnie jak w przypadku innych kluczy przechowywanych w usłudze App Configuration. Ponieważ klient rozpoznaje klucze jako odwołania do usługi Key Vault, klucze te mają unikatowy typ zawartości, a klient nawiązuje połączenie z usługą Key Vault, aby pobrać ich wartości dla aplikacji. Należy skonfigurować sposób nawiązywania połączenia z usługą Key Vault przez podanie poświadczeń lub udostępnienie klientów.

Przy użyciu poświadczeń

Można ustawić argument keyvault_credential używając poświadczeń, dzięki czemu wszystkie odwołania do magazynu kluczy zostaną rozpoznane. Dostawca próbuje nawiązać połączenie z wszelkimi magazynami kluczy, do których odwołuje się udostępnione poświadczenie.

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


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

Z klientami

Argument można ustawić keyvault_client_configs za pomocą słownika konfiguracji klienta.

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)

Uwaga / Notatka

Wszystkie dodatkowe podane właściwości są przekazywane do tworzenia obiektu SecretClient.

Rozwiązywacz tajemnic

Jeśli nie podano poświadczeń ani klientów, można użyć mechanizmu rozpoznawania tajnych danych. Mechanizm rozpoznawania tajnych wartości umożliwia zwrócenie dowolnej wartości, do której chcesz się odwołać w odniesieniu do magazynu kluczy.

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)

Odświeżanie sekretów Key Vault

Usługa Azure App Configuration umożliwia konfigurowanie interwałów odświeżania tajnych danych niezależnie od cyklu odświeżania konfiguracji. Ma to kluczowe znaczenie dla bezpieczeństwa, ponieważ identyfikator URI odwołania do Key Vault w App Configuration pozostaje niezmieniony, podczas gdy ukryty sekret w Key Vault może być rotowany w ramach praktyk bezpieczeństwa.

Aby upewnić się, że aplikacja zawsze używa najbardziej aktualnych wartości tajnych, skonfiguruj słowo kluczowe secret_refresh_interval w load. To zmusza dostawcę do pobierania aktualnych wartości tajnych z usługi Key Vault, gdy:

  • Twoja aplikacja wywołuje refresh
  • Skonfigurowany interwał odświeżania wpisu tajnego upłynął

Ten mechanizm działa nawet wtedy, gdy w magazynie App Configuration nie zostaną wykryte żadne zmiany, zapewniając, że aplikacja pozostaje zsynchronizowana z aktualizowanymi sekretami.

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

Biblioteka dostawcy usługi Azure App Configuration automatycznie odnajduje repliki dostarczonego magazynu konfiguracji i używa replik, jeśli wystąpi jakikolwiek problem. Aby uzyskać więcej informacji, zobacz Replikacja geograficzna.

Odnajdywanie replik jest domyślnie włączone. Jeśli chcesz go wyłączyć, możesz ustawić wartość replica_discovery_enabledFalse.

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

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

Dalsze kroki

Aby dowiedzieć się, jak używać dostawcy konfiguracji języka Python, przejdź do następującego samouczka.

Używanie konfiguracji dynamicznej w języku Python

Aby zobaczyć, jak używać dostawcy w aplikacji internetowej, zapoznaj się z naszymi przykładami Django i Flask.

Przykład Django

Przykład platformy Flask

  • Last updated on