Share via

Azure App Configuration biblioteca de cliente para Python – versão 1.5.0

  • Artigo

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.

Os programas modernos, especialmente os programas em execução numa cloud, geralmente têm muitos componentes distribuídos por natureza. A propagação das definições de configuração nestes componentes pode levar a erros difíceis de resolver durante a implementação de uma aplicação. Utilize App Configuration para armazenar de forma segura todas as definições da sua aplicação num único local.

Utilize a biblioteca de cliente para App Configuration para criar e gerir definições de configuração de aplicações.

Código fonte | Pacote (Pypi) | Pacote (Conda) | Documentação | de referência da APIDocumentação do produto

Exclusão de Responsabilidade

O suporte de pacotes Python do SDK do Azure para Python 2.7 terminou a 01 de janeiro de 2022. Para obter mais informações e perguntas, consulte https://github.com/Azure/azure-sdk-for-python/issues/20691O Python 3.7 ou posterior é necessário para utilizar este pacote. Para obter mais detalhes, veja Azure SDK for Python version support policy (Política de suporte de versões do Azure SDK para Python).

Introdução

Instalar o pacote

Instale a biblioteca de cliente Azure App Configuration para Python com pip:

pip install azure-appconfiguration

Pré-requisitos

Para criar um Arquivo de Configuração, pode utilizar o Portal do Azure ou a CLI do Azure.

Depois disso, crie o Arquivo de Configuração:

az appconfig create --name <config-store-name> --resource-group <resource-group-name> --location eastus

Autenticar o cliente

Para interagir com o serviço App Configuration, terá de criar uma instância da classe AzureAppConfigurationClient. Para tornar isto possível, pode utilizar a cadeia de ligação do Arquivo de Configuração ou utilizar um token do AAD.

Utilizar cadeia de ligação

Obter credenciais

Utilize o fragmento da CLI do Azure abaixo para obter o cadeia de ligação a partir do Arquivo de Configuração.

az appconfig credential list --name <config-store-name>

Em alternativa, obtenha o cadeia de ligação no portal do Azure.

Criar cliente

Assim que tiver o valor da cadeia de ligação, pode criar o AzureAppConfigurationClient:

import os
from azure.appconfiguration import AzureAppConfigurationClient

CONNECTION_STRING = os.environ["APPCONFIGURATION_CONNECTION_STRING"]

# Create app config client
client = AzureAppConfigurationClient.from_connection_string(CONNECTION_STRING)

Utilizar o token do AAD

Aqui, demonstramos a utilização de DefaultAzureCredential para autenticar como principal de serviço. No entanto, a AzureAppConfigurationClient aceita qualquer credencial de identidade do azure . Veja a documentação do azure-identity para obter mais informações sobre outras credenciais.

Criar um principal de serviço (opcional)

Este fragmento da CLI do Azure mostra como criar um novo principal de serviço. Antes de utilizá-lo, substitua "your-application-name" pelo nome adequado para o principal de serviço.

Criar um principal de serviço:

az ad sp create-for-rbac --name http://my-application --skip-assignment

Resultado:

{
    "appId": "generated app id",
    "displayName": "my-application",
    "name": "http://my-application",
    "password": "random password",
    "tenant": "tenant id"
}

Utilize a saída para definir variáveis de ambiente AZURE_CLIENT_ID ("appId" acima), AZURE_CLIENT_SECRET ("palavra-passe" acima) e AZURE_TENANT_ID ("inquilino" acima). O exemplo seguinte mostra uma forma de o fazer no Bash:

export AZURE_CLIENT_ID="generated app id"
export AZURE_CLIENT_SECRET="random password"
export AZURE_TENANT_ID="tenant id"

Atribua uma das funções de App Configuration aplicáveis ao principal de serviço.

Criar um cliente

Assim que as variáveis de ambiente AZURE_CLIENT_ID, AZURE_CLIENT_SECRET e AZURE_TENANT_ID estiverem definidas, DefaultAzureCredential poderá autenticar o AzureAppConfigurationClient.

Construir o cliente também requer o URL do arquivo de configuração, que pode obter a partir da CLI do Azure ou do Portal do Azure. No portal do Azure, o URL pode ser encontrado listado como o "Ponto Final" do serviço

from azure.identity import DefaultAzureCredential
from azure.appconfiguration import AzureAppConfigurationClient

credential = DefaultAzureCredential()

client = AzureAppConfigurationClient(base_url="your_endpoint_url", credential=credential)

Conceitos-chave

Definição de Configuração

Uma Definição de Configuração é o recurso fundamental num Arquivo de Configuração. Na sua forma mais simples, é uma chave e um valor. No entanto, existem propriedades adicionais, como o tipo de conteúdo modificável e os campos de etiquetas que permitem que o valor seja interpretado ou associado de formas diferentes.

A propriedade Etiqueta de uma Definição de Configuração fornece uma forma de separar as Definições de Configuração em dimensões diferentes. Estas dimensões são definidas pelo utilizador e podem assumir qualquer forma. Alguns exemplos comuns de dimensões a utilizar para uma etiqueta incluem regiões, versões semânticas ou ambientes. Muitas aplicações têm um conjunto necessário de chaves de configuração que têm valores variáveis, uma vez que a aplicação existe em diferentes dimensões.

Por exemplo, MaxRequests pode ser 100 em "NorthAmerica" e 200 em "WestEurope". Ao criar uma Definição de Configuração denominada MaxRequests com uma etiqueta "NorthAmerica" e outra, apenas com um valor diferente, na etiqueta "Europa Ocidental", uma aplicação pode obter de forma totalmente integrada as Definições de Configuração, uma vez que é executada nestas duas dimensões.

Propriedades de uma Definição de Configuração:

key : str
label : str
content_type : str
value : str
last_modified : str
read_only : bool
tags : dict
etag : str

Instantâneo

Azure App Configuration permite que os utilizadores criem um instantâneo para um ponto anterior no tempo do respetivo arquivo de configuração, proporcionando-lhes a capacidade de tratar as definições como uma versão consistente. Esta funcionalidade permite que as aplicações tenham uma vista consistente da configuração, garantindo que não existem incompatibilidades de versões para definições individuais devido à leitura à medida que as atualizações foram efetuadas. Os instantâneos são imutáveis, garantindo que a configuração pode ser revertida com confiança para uma última configuração conhecida em caso de problema.

Exemplos

As secções seguintes fornecem vários fragmentos de código que abrangem algumas das tarefas mais comuns do Serviço de Configuração, incluindo:

Criar uma Definição de Configuração

Crie uma Definição de Configuração para ser armazenada no Arquivo de Configuração. Existem duas formas de armazenar uma Definição de Configuração:

  • add_configuration_setting cria uma definição apenas se a definição ainda não existir no arquivo.
config_setting = ConfigurationSetting(
    key="MyKey", label="MyLabel", value="my value", content_type="my content type", tags={"my tag": "my tag value"}
)
added_config_setting = client.add_configuration_setting(config_setting)
  • set_configuration_setting cria uma definição se não existir ou substitui uma definição existente.
added_config_setting.value = "new value"
added_config_setting.content_type = "new content type"
updated_config_setting = client.set_configuration_setting(added_config_setting)

Obter uma Definição de Configuração

Obter uma Definição de Configuração armazenada anteriormente.

fetched_config_setting = client.get_configuration_setting(key="MyKey", label="MyLabel")

Eliminar uma Definição de Configuração

Eliminar uma Definição de Configuração existente.

client.delete_configuration_setting(
    key="MyKey",
    label="MyLabel",
)

Definições de Configuração da Lista

Liste todas as definições de configuração filtradas com label_filter e/ou key_filter.

config_settings = client.list_configuration_settings(label_filter="MyLabel")
for item in config_settings:
    print_configuration_setting(item)

Criar um Instantâneo

from azure.appconfiguration import ConfigurationSettingsFilter

filters = [ConfigurationSettingsFilter(key="my_key1", label="my_label1")]
response = client.begin_create_snapshot(name=snapshot_name, filters=filters)
created_snapshot = response.result()
print_snapshot(created_snapshot)

Obter um Instantâneo

received_snapshot = client.get_snapshot(name=snapshot_name)

Arquivar um Instantâneo

archived_snapshot = client.archive_snapshot(name=snapshot_name)
print_snapshot(archived_snapshot)

Recuperar um Instantâneo

recovered_snapshot = client.recover_snapshot(name=snapshot_name)
print_snapshot(recovered_snapshot)

Listar Instantâneos

for snapshot in client.list_snapshots():
    print_snapshot(snapshot)

Listar Definições de Configuração de um Instantâneo

for config_setting in client.list_configuration_settings(snapshot_name=snapshot_name):
    print_configuration_setting(config_setting)

APIs Assíncronas

O cliente assíncrono é suportado. Para utilizar a biblioteca de cliente assíncrona, importe o AzureAppConfigurationClient do pacote azure.appconfiguration.aio em vez de azure.appconfiguration

import os
from azure.appconfiguration.aio import AzureAppConfigurationClient

CONNECTION_STRING = os.environ["APPCONFIGURATION_CONNECTION_STRING"]

# Create app config client
client = AzureAppConfigurationClient.from_connection_string(CONNECTION_STRING)

Este AzureAppConfigurationClient assíncrono tem as mesmas assinaturas de método que as sincronizadas, exceto que são assíncronas. Por exemplo, para obter uma Definição de Configuração de forma assíncrona, pode utilizar async_client:

fetched_config_setting = await client.get_configuration_setting(key="MyKey", label="MyLabel")

Para utilizar list_configuration_settings, chame-a de forma síncrona e itere sobre o iterador assíncrono devolvido de forma assíncrona

config_settings = client.list_configuration_settings(label_filter="MyLabel")
async for item in config_settings:
    print_configuration_setting(item)

from azure.appconfiguration import ConfigurationSettingsFilter

filters = [ConfigurationSettingsFilter(key="my_key1", label="my_label1")]
response = await client.begin_create_snapshot(name=snapshot_name, filters=filters)
created_snapshot = await response.result()
print_snapshot(created_snapshot)

received_snapshot = await client.get_snapshot(name=snapshot_name)

archived_snapshot = await client.archive_snapshot(name=snapshot_name)
print_snapshot(archived_snapshot)

recovered_snapshot = await client.recover_snapshot(name=snapshot_name)
print_snapshot(recovered_snapshot)

async for snapshot in client.list_snapshots():
    print_snapshot(snapshot)

async for config_setting in client.list_configuration_settings(snapshot_name=snapshot_name):
    print_configuration_setting(config_setting)

Resolução de problemas

Veja o guia de resolução de problemas para obter detalhes sobre como diagnosticar vários cenários de falha.

Passos seguintes

Mais código de exemplo

Estão disponíveis vários App Configuration exemplos de biblioteca de cliente neste repositório do GitHub. Incluem-se:

Para obter mais detalhes, veja os exemplos README.

Contribuir

Agradecemos todas as contribuições e sugestões para este projeto. A maioria das contribuições requerem que celebre um Contrato de Licença de Contribuição (CLA) no qual se declare que tem o direito de conceder e que, na verdade, concede-nos os direitos para utilizar a sua contribuição. Para mais detalhes, visite https://cla.microsoft.com.

Quando submete um pedido Pull, um bot do CLA determina automaticamente se tem de fornecer um CLA e decorar o PR de forma adequada (por exemplo, etiqueta, comentário). Só tem de seguir as instruções fornecidas pelo bot. Apenas terá de fazer isto uma vez em todos os repositórios com o nosso CLA.

Este projeto adotou o Microsoft Open Source Code of Conduct (Código de Conduta do Microsoft Open Source). Para obter mais informações, veja a Code of Conduct FAQ (FAQ do Código de Conduta) ou envie um e-mail para opencode@microsoft.com com quaisquer perguntas ou comentários adicionais.