Partilhar via

Provedor de configuração Python

Pacote Python

A Configuração da Aplicação Azure é um serviço gerido que ajuda os programadores a centralizar as respetivas configurações de aplicações de forma simples e segura. A biblioteca do provedor de configuração Python permite carregar a configuração de um repositório de Configuração de Aplicativo do Azure de forma gerenciada. Esta biblioteca de cliente adiciona funcionalidade adicional ao SDK do Azure para Python.

Instale o pacote

Instale o pacote do Provedor de Configuração de Aplicativo do Azure com pip:

pip install azure-appconfiguration-provider

Para usar o Microsoft Entra ID, a Identidade do Azure também é necessária.

pip install azure-identity

Configuração de carga

A função load no pacote azure-appconfiguration-provider é usada para carregar a configuração do Azure App Configuration. A load função permite que você use o ID do Microsoft Entra (recomendado) ou uma cadeia de conexão para se conectar à App Configuration Store.

Observação

azure-appconfiguration-provider tem versões síncronas from azure.appconfiguration.provider import load e assíncronas from azure.appconfiguration.provider.aio import load . Ao usar a versão assíncrona, a credencial assíncrona, from azure.identity.aio import DefaultAzureCredential, precisa ser usada.

Você usa o DefaultAzureCredential para autenticar na sua loja de configuração de aplicativos. Siga as instruções para atribuir à sua credencial a função de Leitor de Dados de Configuração do Aplicativo.

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

A função load retorna uma instância de AzureAppConfigurationProvider, que é um objeto semelhante a um dicionário e contém todos os valores de configuração carregados do repositório de Configuração da Aplicação. Por predefinição, o provedor carrega do armazém todos os valores de configuração sem rótulo.

Tratamento de tipo de conteúdo JSON

Você pode criar valores-chave JSON na Configuração do aplicativo. Ao carregar valores-chave da Configuração de Aplicativo do Azure, o provedor de configuração converte automaticamente os valores-chave do tipo de conteúdo JSON válido (por exemplo, application/json) em um objeto Python desserializado.

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

Esse conteúdo JSON resulta no valor-chave a ser carregado como { size: 12, color: "red" }.

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

Observação

A partir da versão 2.2.0 do azure-appconfiguration-provider, o fornecedor de configuração permite comentários, conforme definido em (JSONC), em pares chave-valor com um tipo de conteúdo application/json.

Carregue valores-chave específicos usando seletores

Por padrão, o load método carrega todas as configurações sem rótulo do repositório de configuração. Você pode configurar o comportamento do método load através do parâmetro opcional de selects, que é uma lista de 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)

Observação

Os valores-chave são carregados na ordem em que os seletores são listados. Se vários seletores recuperarem valores-chave com a mesma chave, o valor do último substituirá qualquer valor carregado anteriormente.

Filtros de tags

O parâmetro tag filters seleciona valores-chave com tags específicas. Um valor-chave só é carregado se tiver todas as tags e valores correspondentes especificados nos filtros.

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)

Observação

Os caracteres asterisco (*), vírgula (,) e barra inversa (\) são reservados e devem ser escapados com uma barra inversa quando usados num filtro de etiqueta.

Carregar configuração a partir de instantâneos

Pode carregar as definições de configuração de snapshots usando o snapshot_name parâmetro em SettingSelector. Quando especificas o nome de um snapshot, todas as definições de configuração desse snapshot são carregadas. O snapshot_name parâmetro não pode ser usado com key_filter, label_filter, ou 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)

Observação

O suporte para snapshots está disponível se usar a versão 2.3.0 ou posterior do azure-appconfiguration-provider pacote. Apenas snapshots criados com o tipo Key de composição podem ser carregados usando o fornecedor de configuração.

Teclas de corte

Você pode remover o prefixo das chaves fornecendo uma lista de prefixos de chaves removidos para a load função, através do trim_prefixes parâmetro.

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"

Mapeamento de definições de configuração

O configuration_mapper parâmetro permite transformar as definições de configuração antes de serem processadas e adicionadas ao fornecedor. A função mapper recebe cada ConfigurationSetting objeto e pode modificá-lo no local.

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)

A função mapper é chamada para cada configuração carregada do repositório, o que lhe permite:

  • Modificar os valores das definições antes de serem adicionados
  • Transformar ou desencriptar valores
  • Realizar processamento personalizado com base na chave de definição, etiqueta ou tipo de conteúdo

Observação

O mapeador é invocado antes de ser aplicado o corte de chaves. Use a chave original ao verificar as condições na sua função de mapeamento.

Para operações assíncronas, forneça uma função de mapeamento assíncrono:

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)

Atualização de configuração

O provedor pode ser configurado para extrair as configurações mais recentes da App Configuration Store sem ter que reiniciar o aplicativo. Você pode usar o refresh_on parâmetro para habilitar esse comportamento. O refresh_on parâmetro é um List[WatchKey], especificando uma ou mais chaves/etiquetas a serem observadas para alterações. A configuração carregada é atualizada quando qualquer alteração de valores-chave selecionados é detetada no servidor. Por padrão, um intervalo de atualização de 30 segundos é usado, mas você pode substituí-lo pelo refresh_interval parâmetro.

O on_refresh_success callback é chamado somente se uma alteração for detetada e nenhum erro ocorrer. O on_refresh_error callback é acionado quando uma atualização falha.

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
)

A configuração refresh_on sozinha não atualiza automaticamente a configuração. Você precisa chamar o refresh método na AzureAppConfigurationProvider instância retornada load pelo método para disparar uma atualização.

config.refresh()

Esse design evita solicitações desnecessárias à Configuração do Aplicativo quando seu aplicativo está ocioso. Você deve incluir a chamada onde a atividade do refresh aplicativo ocorre. Esse processo é conhecido como atualização de configuração orientada por atividade. Por exemplo, você pode chamar refresh ao processar uma solicitação de entrada ou dentro de uma iteração onde você executa uma tarefa complexa. Se a atualização falhar, um erro será gerado, a menos que um on_refresh_error seja providenciado. O método refresh não executa nenhuma operação se o intervalo de atualização não tiver decorrido. Além disso, apenas uma verificação de atualização pode acontecer de cada vez, retornando como um no-op se uma atualização já estiver em andamento.

Sinalizador de recurso

Você pode criar sinalizadores de recursos na Configuração do Aplicativo do Azure. Por predefinição, o fornecedor de configuração não carrega as flags de funcionalidades. Você pode habilitar o carregamento e a atualização de sinalizadores de recursos por meio do feature_flags_enabled parâmetro.

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

Por padrão, todos os sinalizadores de recursos sem rótulo são carregados quando feature_flags_enabled está definido para True. Se quiser carregar sinalizadores de funcionalidades com um rótulo específico, pode usar o parâmetro feature_flag_selectors para filtrar os sinalizadores de funcionalidades, que incluirá uma lista de objetos SettingSelector.

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

Observação

Para consumir e gerir efetivamente as flags de funcionalidades carregadas a partir da Configuração de Aplicações do Azure, instale e utilize a biblioteca featuremanagement. Essa biblioteca fornece uma maneira estruturada de controlar o comportamento do recurso em seu aplicativo.

Gestão de funcionalidades

A biblioteca de gerenciamento de recursos fornece uma maneira de desenvolver e expor a funcionalidade do aplicativo com base em sinalizadores de recursos. A biblioteca de gerenciamento de recursos foi projetada para trabalhar em conjunto com a biblioteca do provedor de configuração. O provedor de configuração carrega todos os sinalizadores de recursos selecionados na configuração sobre a lista feature_flags da seção feature_management. A biblioteca de gerenciamento de recursos consome e gerencia os sinalizadores de recursos carregados para seu aplicativo.

O exemplo a seguir demonstra como integrar a biblioteca featuremanagement com o provedor de configuração para gerir dinamicamente a acessibilidade da API numa aplicação Express, dependendo do estado do sinalizador de funcionalidade 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")}")

Para obter mais informações sobre como usar a biblioteca de gerenciamento de recursos do Python, vá para o início rápido do sinalizador de recursos.

Telemetria da bandeira de funcionalidades

Quando a telemetria de feature flag está ativada, o provedor Azure App Configuration injeta propriedades adicionais nos dados de telemetria de feature flag. Estas propriedades fornecem mais contexto sobre a feature flag e a sua avaliação:

  • AllocationID: Um identificador único que representa o estado da alocação da feature flag.
  • ETag: O ETag atual para o sinalizador de funcionalidade.
  • FeatureFlagReference: Uma referência à feature flag no formato de <your_store_endpoint>kv/<feature_flag_key>. Quando uma etiqueta está presente, a referência inclui-a como parâmetro de consulta: <your_store_endpoint>kv/<feature_flag_key>?label=<feature_flag_label>.

O esquema completo pode ser encontrado na definição do esquema App Configuration Feature Evaluation Event. Para mais informações sobre como usar a telemetria de feature flags, consulte a orientação prática de ativação da telemetria para feature flags.

Atualização do sinalizador de recursos

Para habilitar a atualização para sinalizadores de recursos, você precisa definir feature_flag_refresh_enabled=True. Esse parâmetro permite que o provedor atualize sinalizadores de recursos da mesma forma que atualiza as configurações. Ao contrário das configurações, todos os flags de funcionalidade carregados são monitorados quanto a alterações e resultam numa atualização. A atualização das definições de configuração e os sinalizadores de recursos são independentes uns dos outros. As definições de configuração e os sinalizadores de recursos refresh são atualizados pelo método, mas uma alteração de sinalizador de recurso não causa uma atualização das definições de configuração e vice-versa. Além disso, se a atualização para definições de configuração não estiver habilitada, os sinalizadores de recursos ainda poderão ser habilitados para atualização.

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

# Later in your code
config.refresh()

Referência do Cofre da Chave

A Configuração de Aplicativo do Azure dá suporte à referência de segredos armazenados no Cofre da Chave do Azure. Na Configuração do Aplicativo, você pode criar chaves que mapeiam para segredos armazenados no Cofre da Chave. Os segredos são armazenados com segurança no Cofre da Chave, mas podem ser acessados como qualquer outra configuração uma vez carregados.

A biblioteca do provedor de configuração recupera referências do Cofre da Chave, assim como faz para quaisquer outras chaves armazenadas na Configuração do aplicativo. Como o cliente reconhece as chaves como referências do Cofre da Chave, elas têm um tipo de conteúdo exclusivo e o cliente se conecta ao Cofre da Chave para recuperar seus valores para seu aplicativo. Você precisa configurar uma maneira de se conectar ao Cofre da Chave, fornecendo uma credencial ou fornecendo clientes.

Com credenciais

Você pode definir o argumento keyvault_credential com uma credencial e todas as referências do cofre de chaves são resolvidas com ele. O provedor tenta se conectar a qualquer cofre de chaves referenciado com a credencial fornecida.

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


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

Com clientes

Você pode definir o argumento keyvault_client_configs com um dicionário de configurações de cliente.

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)

Observação

Quaisquer propriedades extras fornecidas são passadas para a criação do SecretClient.

Decifrador secreto

Se nenhuma credencial ou cliente for fornecido, um resolvedor secreto pode ser usado. O resolvedor de segredos fornece uma maneira de retornar qualquer valor desejado para uma referência do cofre de chaves.

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)

Atualização de segredos do Cofre de Chaves

A Configuração de Aplicativo do Azure permite configurar intervalos de atualização secretos independentemente do seu ciclo de atualização de configuração. Isso é crucial para a segurança porque, embora o URI de referência do Cofre da Chave na Configuração do Aplicativo permaneça inalterado, o segredo subjacente no Cofre da Chave pode ser girado como parte de suas práticas de segurança.

Para garantir que a sua aplicação utiliza sempre os valores secretos mais recentes, configure a secret_refresh_interval palavra-chave em load. Isso força o provedor a recuperar novos valores secretos do Cofre de Chaves quando:

  • A sua aplicação chama refresh
  • O intervalo de atualização configurado para o segredo decorreu

Esse mecanismo funciona mesmo quando nenhuma alteração é detetada na sua loja de configuração de aplicações, garantindo que a sua aplicação permaneça sincronizada com segredos rodados.

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
)

Georreplicação

A biblioteca do Provedor de Configuração de Aplicativo do Azure descobre automaticamente as réplicas do repositório de configuração fornecido e usa as réplicas se surgir algum problema. Para obter mais informações, consulte replicação geográfica.

A descoberta de réplicas está habilitada por padrão. Se quiser desativá-lo, você pode definir replica_discovery_enabled como False.

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

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

Próximos passos

Para saber como usar o provedor de configuração do Python, continue para o tutorial a seguir.

Usar configuração dinâmica em Python

Para ver como usar o provedor em uma aplicação web, confira nossos exemplos de Django e Flask.

Exemplo de Django

Exemplo Flask

  • Last updated on