Bibliotecas do Azure para padrões de uso do Python

  • Artigo

O SDK do Azure para Python é composto por muitas bibliotecas independentes listadas no índice de pacote do SDK do Python.

Todas as bibliotecas compartilham determinadas características e padrões de uso comuns, como a instalação e o uso de JSON embutido para argumentos de objeto.

Configurar seu ambiente de desenvolvimento

Caso ainda não tenha feito isso, você pode configurar um ambiente onde você possa executar esse código. Estas são algumas opções:

Instalação de biblioteca

Para instalar um pacote de biblioteca específico, use pip install:

# Install the management library for Azure Storage
pip install azure-mgmt-storage

# Install the client library for Azure Blob Storage
pip install azure-storage-blob

pip install recupera a versão mais recente de uma biblioteca no seu ambiente atual do Python.

Você também pode usar pip para desinstalar bibliotecas e instalar versões específicas, incluindo versões prévias. Para mais informações, consulte Como instalar pacotes de biblioteca do Azure para Python.

Operações assíncronas

Bibliotecas assíncronas

Muitas bibliotecas de cliente e de gerenciamento fornecem versões assíncronas (.aio). A biblioteca asyncio está disponível desde o Python 3.4, e as palavras-chave async/await foram introduzidas no Python 3.5. As versões assíncronas das bibliotecas devem ser usadas com o Python 3.5 e posterior.

Exemplos de bibliotecas do SDK do Python do Azure com versões assíncronas incluem: azure.storage.blob.aio, azure.servicebus.aio, azure.mgmt.keyvault.aio e azure.mgmt.compute.aio.

Essas bibliotecas precisam de um transporte assíncrono como aiohttp para funcionar. A biblioteca azure-core fornece um transporte assíncrono, AioHttpTransport, que é usado pelas bibliotecas assíncronas.

O código a seguir mostra como criar um cliente para a versão assíncrona da biblioteca do Armazenamento de Blobs do Azure:

credential = DefaultAzureCredential()

async def run():

    async with BlobClient(
        storage_url,
        container_name="blob-container-01",
        blob_name=f"sample-blob-{str(uuid.uuid4())[0:5]}.txt",
        credential=credential,
    ) as blob_client:

        # Open a local file and upload its contents to Blob Storage
        with open("./sample-source.txt", "rb") as data:
            await blob_client.upload_blob(data)
            print(f"Uploaded sample-source.txt to {blob_client.url}")

        # Close credential
        await credential.close()

asyncio.run(run())

O exemplo completo está no GitHub em use_blob_auth_async.py. Para obter a versão síncrona desse código, consulte Exemplo: carregar um blob.

Operações de execução prolongada

Algumas operações de gerenciamento que você invoca (tais como ComputeManagementClient.virtual_machines.begin_create_or_update e WebSiteManagementClient.web_apps.begin_create_or_update retornam um sondador para operações de execução prolongado, LROPoller[<type>], onde <type> é específico para a operação em questão.

Observação

Você pode notar diferenças nos nomes de método em uma biblioteca, e isso é devido a diferenças de versão. Bibliotecas mais antigas que não são baseadas no azure.core normalmente usam nomes como create_or_update. Bibliotecas baseadas no azure.core adicionam o prefixo begin_ aos nomes de método para melhor indicar que eles são operações de sonda prolongada. Migrar um código antigo para uma biblioteca mais recente baseada no azure.core normalmente significa adicionar o prefixo begin_ aos nomes de método, já que a maioria das assinaturas de método permanece a mesma.

O tipo de retorno LROPoller significa que a operação é assíncrona. Você precisa chamar o método result do instrumento de sondagem para aguardar a operação ser concluída e obter o resultado dela.

O código a seguir, obtido de Exemplo: criar e implantar um aplicativo Web, mostra um exemplo de como usar o sondador para aguardar um resultado:

poller = app_service_client.web_apps.begin_create_or_update(RESOURCE_GROUP_NAME,
    WEB_APP_NAME,
    {
        "location": LOCATION,
        "server_farm_id": plan_result.id,
        "site_config": {
            "linux_fx_version": "python|3.8"
        }
    }
)

web_app_result = poller.result()

Nesse caso, o valor retornado de begin_create_or_update é do tipo AzureOperationPoller[Site], o que significa que o valor retornado de poller.result() é um objeto Site.

Exceções

Em geral, as bibliotecas do Azure geram exceções quando as operações não são executadas conforme o esperado, incluindo solicitações HTTP com falha para a API REST do Azure. Para o código do aplicativo, você pode usar blocos try...except em relação a operações de biblioteca.

Para obter mais informações sobre o tipo de exceções que podem ser geradas, consulte a documentação da operação em questão.

Logging

As bibliotecas do Azure mais recentes usam a biblioteca logging padrão do Python para gerar a saída de log. Você pode definir o nível de registros em log para bibliotecas individuais, grupos de bibliotecas ou todas as bibliotecas. Depois de registrar um manipulador de fluxo de log, você poderá habilitar o registro em log para um objeto de cliente específico ou uma operação específica. Para obter mais informações, confira Registrar em log nas bibliotecas do Azure.

Configuração de proxy

Para especificar um proxy, você pode usar variáveis de ambiente ou argumentos opcionais. Para obter mais informações, confira Como configurar proxies.

Argumentos opcionais para objetos e métodos de cliente

Na documentação de referência da biblioteca, você geralmente vê um argumento **kwargs ou **operation_config na assinatura de um construtor de objeto de cliente ou de um método de operação específico. Esses espaços reservados indicam que o objeto ou método em questão pode dar suporte a outros argumentos nomeados. Normalmente, a documentação de referência indica os argumentos específicos que você pode usar. Há também alguns argumentos gerais que frequentemente têm suporte, conforme descrito nas seções a seguir.

Argumentos para bibliotecas baseadas no azure.core

Esses argumentos se aplicam a essas bibliotecas listadas em Python – Novas Bibliotecas. Por exemplo, este é um subconjunto dos argumentos de palavra-chave para azure-core. Para ver uma lista completa, consulte o README do GitHub para azure-core.

Nome Tipo Padrão Descrição
logging_enable bool Falso Habilita o registro em log. Para obter mais informações, confira Registrar em log nas bibliotecas do Azure.
proxies dict {} URLs do servidor proxy. Para obter mais informações, confira Como configurar proxies.
use_env_settings bool Verdadeiro Se for True, permitirá o uso de variáveis de ambiente HTTP_PROXY e HTTPS_PROXY para proxies. Se for False, as variáveis de ambiente serão ignoradas. Para obter mais informações, confira Como configurar proxies.
connection_timeout int 300 O tempo limite em segundos para estabelecer uma conexão com os pontos de extremidade da API REST do Azure.
read_timeout int 300 O tempo limite em segundos para concluir uma operação da API REST do Azure (ou seja, aguardando uma resposta).
retry_total int 10 O número de tentativas de repetição permitidas para chamadas à API REST. Use retry_total=0 para desabilitar repetições.
retry_mode enum exponential Aplica o tempo de repetição de maneira linear ou exponencial. Se for 'single', as repetições serão feitas em intervalos regulares. Se for 'exponential', cada repetição aguardará o dobro da repetição anterior.

Bibliotecas individuais não são obrigadas a dar suporte a nenhum desses argumentos, portanto sempre consulte a documentação de referência para cada biblioteca para obter detalhes exatos. Além disso, cada biblioteca pode dar suporte a outros argumentos. Por exemplo, para argumentos de palavra-chave específicos do armazenamento de blobs, consulte o README do GitHub para azure-storage-blob.

Padrão JSON embutido para argumentos de objeto

Muitas operações nas bibliotecas do Azure permitem que você expresse argumentos de objeto como objetos discretos ou como JSON embutido.

Por exemplo, suponha que você tenha um objeto ResourceManagementClient por meio do qual você cria um grupo de recursos com seu método create_or_update. O segundo argumento para esse método é do tipo ResourceGroup.

Para chamar o método create_or_update, você pode criar uma instância discreta do ResourceGroup diretamente com seus argumentos necessários (location neste caso):

# Provision the resource group.
rg_result = resource_client.resource_groups.create_or_update(
    "PythonSDKExample-rg",
    ResourceGroup(location="centralus")
)

Como alternativa, você pode passar os mesmos parâmetros como JSON embutido:

# Provision the resource group.
rg_result = resource_client.resource_groups.create_or_update(
    "PythonAzureExample-rg", {"location": "centralus"}
)

Ao usar o JSON em linha, as bibliotecas do Azure convertem automaticamente o JSON embutido para o tipo de objeto apropriado para o argumento em questão.

Os objetos também podem ter argumentos de objeto aninhados. Nesse caso, você também pode usar o JSON aninhado.

Por exemplo, vamos supor que você tenha uma instância de objeto KeyVaultManagementClient e chama seu método create_or_update. Nesse caso, o terceiro argumento é do tipo VaultCreateOrUpdateParameters, que por sua vez contém um argumento do tipo VaultProperties. VaultProperties, por sua vez, contém argumentos de objeto do tipo Sku e list[AccessPolicyEntry]. Uma Sku contém um objeto SkuName e cada AccessPolicyEntry contém um objeto Permissions.

Para chamar begin_create_or_update com objetos inseridos, use um código como o seguinte (supondo que tenant_id, object_id e LOCATION já estejam definidos). Você também pode criar os objetos necessários antes da chamada de função.

# Provision a Key Vault using inline parameters
poller = keyvault_client.vaults.begin_create_or_update(
    RESOURCE_GROUP_NAME,
    KEY_VAULT_NAME_A,
    VaultCreateOrUpdateParameters(
        location = LOCATION,
        properties = VaultProperties(
            tenant_id = tenant_id,
            sku = Sku(
                name="standard",
                family="A"
            ),            
            access_policies = [
                AccessPolicyEntry(
                    tenant_id = tenant_id,
                    object_id = object_id,
                    permissions = Permissions(
                        keys = ['all'],
                        secrets = ['all']
                    )
                )
            ]
        )
    )
)

key_vault1 = poller.result()

A mesma chamada que usa JSON embutido aparece da seguinte maneira:

# Provision a Key Vault using inline JSON
poller = keyvault_client.vaults.begin_create_or_update(
    RESOURCE_GROUP_NAME,
    KEY_VAULT_NAME_B,
    {
        'location': LOCATION,
        'properties': {
            'sku': {
                'name': 'standard',
                'family': 'A'
            },
            'tenant_id': tenant_id,
            'access_policies': [{
                'tenant_id': tenant_id,
                'object_id': object_id,                
                'permissions': {
                    'keys': ['all'],
                    'secrets': ['all']
                }
            }]
        }
    }
)

key_vault2 = poller.result()

Como ambas as formas são equivalentes, você pode escolher qual preferir e pode até mesmo misturá-las. O código completo dos exemplos está disponível no GitHub.

Se o JSON não for formado corretamente, você normalmente receberá o erro "DeserializationError: Não é possível desserializar para object: type, AttributeError: 'str' object has no attribute 'get'". Uma causa comum desse erro é fornecer uma cadeia de caracteres única para uma propriedade quando a biblioteca espera um objeto JSON aninhado. Por exemplo, o uso de 'sku': 'standard' no exemplo anterior gera esse erro porque o parâmetro sku é um objeto Sku que espera o objeto embutido JSON, nesse caso {'name': 'standard'}, que é mapeado para o tipo SkuName esperado.

Próximas etapas

Agora que você reconhece os padrões comuns para usar as bibliotecas do Azure para Python, confira os exemplos independentes a seguir para explorar cenários específicos de gerenciamento e de biblioteca de clientes. Você pode experimentar esses exemplos em qualquer ordem, pois eles não são sequenciais nem interdependentes.