Configuração de Aplicativos do Azure biblioteca de clientes para Python – versão 1.5.0

  • Artigo

A Configuração de Aplicativos do Azure é um serviço gerenciado que ajuda os desenvolvedores a centralizarem as configurações de seus aplicativos de maneira simples e segura.

Programas modernos, especialmente programas executando em uma nuvem, geralmente possuem muitos componentes que são distribuídos por natureza. A distribuição das definições de configuração entre esses componentes pode levar a erros difíceis de serem resolvidos durante uma implantação de aplicativo. Use Configuração de Aplicativos para armazenar com segurança todas as configurações do aplicativo em um só lugar.

Use a biblioteca de clientes para Configuração de Aplicativos para criar e gerenciar definições de configuração de aplicativo.

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

Aviso de isenção de responsabilidade

O suporte a pacotes python do SDK do Azure para Python 2.7 terminou em 01 de janeiro de 2022. Para obter mais informações e perguntas, consulte https://github.com/Azure/azure-sdk-for-python/issues/20691Python 3.7 ou posterior é necessário para usar esse pacote. Para obter mais detalhes, consulte a política de suporte do SDK do Azure para Python.

Introdução

Instalar o pacote

Instale a biblioteca de clientes do Configuração de Aplicativos do Azure para Python com pip:

pip install azure-appconfiguration

Pré-requisitos

  • É necessário ter o Python 3.7 ou posterior para usar esse pacote.
  • Você precisa de uma assinatura do Azure e de um Repositório de Configurações para usar esse pacote.

Para criar um Repositório de Configurações, você pode usar o Portal do Azure ou a CLI do Azure.

Depois disso, crie o Repositório de Configurações:

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

Autenticar o cliente

Para interagir com o serviço Configuração de Aplicativos, você precisará criar uma instância da classe AzureAppConfigurationClient. Para tornar isso possível, você pode usar o cadeia de conexão do Repositório de Configurações ou usar um token do AAD.

Usar a cadeia de conexão

Obter credenciais

Use o snippet da CLI do Azure abaixo para obter o cadeia de conexão do Repositório de Configurações.

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

Como alternativa, obtenha o cadeia de conexão no Portal do Azure.

Criar cliente

Depois de ter o valor do cadeia de conexão, você poderá 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)

Usar token do AAD

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

Criar uma entidade de serviço (opcional)

Este snippet da CLI do Azure mostra como criar uma nova entidade de serviço. Antes de usá-lo, substitua "your-application-name" pelo nome apropriado para sua entidade de serviço.

Criar uma entidade de serviço:

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

Saída:

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

Use a saída para definir AZURE_CLIENT_ID ("appId" acima), AZURE_CLIENT_SECRET ("senha" acima) e AZURE_TENANT_ID ("locatário" acima). O exemplo a seguir mostra uma maneira de fazer isso 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 Configuração de Aplicativos aplicáveis à entidade de serviço.

Criar um cliente

Depois que o AZURE_CLIENT_ID, AZURE_CLIENT_SECRET e AZURE_TENANT_ID variáveis de ambiente forem definidas, DefaultAzureCredential poderá autenticar o AzureAppConfigurationClient.

Construir o cliente também requer a URL do repositório de configuração, que você pode obter da CLI do Azure ou do Portal do Azure. No Portal do Azure, a URL pode ser encontrada listada como o serviço "Ponto de extremidade"

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

credential = DefaultAzureCredential()

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

Principais conceitos

Definição de configuração

Uma Definição de Configuração é o recurso fundamental dentro de um Repositório de Configurações. Em sua forma mais simples, é uma chave e um valor. No entanto, há propriedades adicionais, como o tipo de conteúdo modificável e os campos de marcas que permitem que o valor seja interpretado ou associado de maneiras diferentes.

A propriedade Label de uma Configuração fornece uma maneira de separar as Definições de Configuração em dimensões diferentes. Essas dimensões são definidas pelo usuário e podem assumir qualquer forma. Alguns exemplos comuns de dimensões a serem usadas para um rótulo incluem regiões, versões semânticas ou ambientes. Muitos aplicativos têm um conjunto necessário de chaves de configuração que têm valores variados à medida que o aplicativo existe em diferentes dimensões.

Por exemplo, MaxRequests pode ser 100 em "NorthAmerica" e 200 em "WestEurope". Ao criar uma Configuração chamada MaxRequests com um rótulo de "NorthAmerica" e outro, somente com um valor diferente, no rótulo "WestEurope", um aplicativo pode recuperar perfeitamente as Definições de Configuração conforme é executado nessas 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

Configuração de Aplicativos do Azure permite que os usuários criem uma instantâneo pontual de seu repositório de configuração, fornecendo a eles a capacidade de tratar as configurações como uma versão consistente. Esse recurso permite que os aplicativos tenham uma exibição consistente da configuração, garantindo que não haja incompatibilidades de versão nas configurações individuais devido à leitura à medida que as atualizações foram feitas. Os instantâneos são imutáveis, garantindo que a configuração possa ser revertida com confiança para uma última configuração válida no caso de um problema.

Exemplos

As seções a seguir fornecem vários snippets de código que abrangem algumas das tarefas mais comuns do Serviço de Configuração, incluindo:

Criar uma configuração

Crie uma Configuração a ser armazenada no Repositório de Configurações. Há duas maneiras de armazenar uma Configuração:

  • add_configuration_setting criará uma configuração somente se a configuração ainda não existir no repositório.
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 criará uma configuração se ela não existir ou substituir uma configuraçã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 configuração

Obter uma configuração armazenada anteriormente.

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

Excluir uma configuração

Exclua uma configuração existente.

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

Listar definições de configuração

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

Há suporte para o cliente assíncrono. Para usar a biblioteca de clientes 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)

Esse AzureAppConfigurationClient assíncrono tem as mesmas assinaturas de método que as de sincronização, exceto que elas são assíncronas. Por exemplo, para recuperar uma configuração de forma assíncrona, async_client pode ser usado:

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

Para usar list_configuration_settings, chame-o de forma síncrona e itere sobre o iterador assíncrono retornado 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)

Solução de problemas

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

Próximas etapas

Mais códigos de exemplo

Várias Configuração de Aplicativos exemplos de biblioteca de clientes estão disponíveis para você neste repositório GitHub. Estão incluídos:

Para obter mais detalhes, consulte os exemplos README.

Contribuição

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, visite https://cla.microsoft.com.

Quando você envia uma solicitação de pull, um bot do CLA determina automaticamente se você precisa fornecer um CLA e preencher a PR corretamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios que usam nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o código de conduta ou entre em contato com opencode@microsoft.com para enviar outras perguntas ou comentários.