Bibliotecas do Azure para padrões de uso do Python

  • Artigo

O SDK do Azure para Python é composto por muitas bibliotecas independentes, que estão 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

Se ainda não o fez, você pode configurar um ambiente onde você pode 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 gerenciamento fornecem versões assíncronas (.aio). A asyncio biblioteca 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 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 para aiohttp funcionar. A azure-core biblioteca 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 de 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 (como ComputeManagementClient.virtual_machines.begin_create_or_update e WebSiteManagementClient.web_apps.begin_create_or_update retornar um poller para operações de longa execução, 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, o que é devido a diferenças de versão. Bibliotecas mais antigas que não são baseadas em azure.core normalmente usam nomes como create_or_update. As bibliotecas baseadas em azure.core adicionam o prefixo aos nomes dos begin_ métodos para indicar melhor que são operações de sondagem longas. 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 LROPoller tipo de retorno 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, retirado de Exemplo: Criar e implantar um aplicativo Web, mostra um exemplo de uso do poller 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 de retorno de begin_create_or_update é do tipo AzureOperationPoller[Site], o que significa que o valor de retorno 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 código de aplicativo, você pode usar try...except blocos em torno de operações de biblioteca.

Para obter mais informações sobre o tipo de exceções que podem ser levantadas, 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 oferecer 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, aqui estão um subconjunto dos argumentos de palavra-chave para azure-core. Para obter uma lista completa, consulte o LEIA-ME 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.

As bibliotecas individuais não são obrigadas a suportar nenhum desses argumentos, portanto, sempre consulte a documentação de referência de cada biblioteca para obter detalhes exatos. Além disso, cada biblioteca pode oferecer suporte a outros argumentos. Por exemplo, para argumentos de palavra-chave específicos de armazenamento de blob, consulte o Leiame 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 ResourceManagementClient objeto por meio do qual você cria um grupo de recursos com seu create_or_update método. O segundo argumento para esse método é do tipo ResourceGroup.

Para chamar o create_or_update método, você pode criar uma instância discreta de 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"}
)

Quando você usa JSON embutido, as bibliotecas do Azure convertem automaticamente o JSON embutido no 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 incorporados, use um código como o seguinte (supondo tenant_idque 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 estiver formado corretamente, você normalmente obterá o erro "DeserializationError: Unable to deserialize to 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 tentar esses exemplos em qualquer ordem, pois eles não são sequenciais ou interdependentes.