Bibliotecas do Azure para padrões de uso Python

O SDK do Azure para Python é composto por muitas bibliotecas independentes, que estão listadas no índice do pacote do SDK do Python.

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

Configurar o seu ambiente de desenvolvimento local

Se ainda não o fez, pode configurar um ambiente onde pode executar este código. Seguem-se algumas opções:

• Configure um ambiente virtual Python usando venv ou sua ferramenta de escolha. Você pode criar o ambiente virtual localmente ou no Azure Cloud Shell e executar o código lá. Certifique-se de ativar o ambiente virtual para começar a usá-lo.

• Use um ambiente de conda.

• Use um contêiner de desenvolvimento no Visual Studio Code ou GitHub Codespaces.

Instalação da biblioteca

# 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

# Install the Azure management library package
conda install azure-mgmt

# Install the client library for Azure Storage
conda install azure-storage

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 destinam-se a 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, AioHttpTransportque é 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 Blob 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 duração, LROPoller[<type>], onde <type> é específico para a operação em questão.

O LROPoller tipo de retorno significa que a operação é assíncrona. Assim, você deve chamar o método do result poller para aguardar a conclusão da operação e obter seu resultado.

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 é do tipo AzureOperationPoller[Site], o que significa que o valor de begin_create_or_update 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 o código do 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.

Registo

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

Configuração do proxy

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

Argumentos opcionais para objetos e métodos de cliente

Na documentação de referência da biblioteca, você geralmente vê um **kwargs argumento ou **operation_config na assinatura de um construtor de objeto cliente ou um método de operação específico. Esses espaços reservados indicam que o objeto ou método em questão pode suportar 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 geralmente são apoiados, conforme descrito nas seções a seguir.

Argumentos para bibliotecas baseadas em azure.core

Esses argumentos se aplicam às bibliotecas listadas em Python - New Libraries. Por exemplo, aqui está um subconjunto dos argumentos de palavra-chave para azure-core. Para obter uma lista completa, consulte o Leiame do GitHub para azure-core.

As bibliotecas individuais não são obrigadas a suportar nenhum destes argumentos, por isso consulte sempre a documentação de referência de cada biblioteca para obter detalhes exatos. Além disso, cada biblioteca pode suportar 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 dentro das 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 através do qual você cria um grupo de recursos com seu create_or_update método. O segundo argumento para este 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 que o 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, caso em que você também pode usar JSON aninhado.

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

Para chamar begin_create_or_update com objetos incorporados, use um código como o seguinte (assumindo tenant_id, object_ide LOCATION já estão 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 usando 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 o que preferir e até mesmo misturá-las. (O código completo para estes exemplos pode ser encontrado em GitHub.)

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

Próximos passos

Agora que você entende os padrões comuns para usar as bibliotecas do Azure para Python, consulte os exemplos autônomos a seguir para explorar cenários específicos de gerenciamento e biblioteca de cliente. Você pode tentar esses exemplos em qualquer ordem, pois eles não são sequenciais ou interdependentes.

• Exemplo: Criar um grupo de recursos

• Exemplo: Usar o Armazenamento do Azure

• Exemplo: Criar um aplicativo Web e implantar código

• Exemplo: Criar e consultar um banco de dados

• Exemplo: Criar uma máquina virtual

• Usar Discos Gerenciados do Azure com máquinas virtuais

• Conclua uma breve pesquisa sobre o SDK do Azure para Python