Bibliotecas do Azure para padrões de uso do Python

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

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

Configurar seu ambiente de desenvolvimento local

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

Configure um ambiente virtual do Python usando venv ou sua ferramenta de escolha. Para começar a usar o ambiente virtual, ative-o. Para instalar o Python, consulte Instalar o Python.

Bash
PowerShell

#!/bin/bash
# Create a virtual environment
python -m venv .venv
# Activate the virtual environment
source .venv/Scripts/activate # only required for Windows (Git Bash)

# PowerShell syntax
# Create a virtual environment
python -m venv venv
# Activate the virtual environment
. .\venv\Scripts\Activate.ps1

Usar um ambiente Conda. Para instalar o Conda, consulte Instalar o Miniconda.
Use um contêiner de desenvolvimento no Visual Studio Code ou no GitHub Codespaces.

Instalação da biblioteca

Escolha o método de instalação que corresponde à ferramenta de gerenciamento de ambiente do Python, pip ou conda.

semente
Conda

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

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

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

REM Install the azure identity library for Azure authentication
pip install azure-identity

pip install recupera a versão mais recente de uma biblioteca em seu ambiente python atual.

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

Para instalar um pacote de biblioteca específico em um ambiente conda, use conda install:

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

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

REM Install the azure identity library for Azure authentication
pip install azure-identity

conda install recupera a versão mais recente de um pacote em seu ambiente Conda atual.

Para obter mais informações, incluindo como remover pacotes ou instalar versões específicas, consulte Como instalar pacotes de biblioteca do Azure para Python.

Operações assíncronas

Bibliotecas assíncronas

Muitas bibliotecas de gerenciamento e cliente fornecem versões assíncronas (.aio). A asyncio biblioteca está disponível desde 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 azure-core biblioteca fornece um transporte assíncrono, AioHttpTransportque é usado pelas bibliotecas assíncronas, portanto, talvez você não precise instalar aiohttp separadamente.

O código a seguir mostra como criar um arquivo python que demonstra 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: Envio de um blob.

Operações de longa duração

Algumas operações de gerenciamento que você invoca (como ComputeManagementClient.virtual_machines.begin_create_or_update e WebAppsClient.web_apps.begin_create_or_update) retornam um sondador para operações de longa execução, LROPoller[<type>], em que <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, dependendo de sua versão e se ela é baseada em azure.core. Bibliotecas mais antigas que não são baseadas em 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 são operações de sondagem longas. Migrar código antigo para uma biblioteca mais recente baseada em azure.core normalmente significa adicionar o begin_ prefixo a nomes de método, pois a maioria das assinaturas de método permanece a mesma.

O LROPoller tipo de retorno significa que a operação é assíncrona. Você deve 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 a partir de Exemplo: Criar e implantar um aplicativo Web, mostra um exemplo de como usar o poller para aguardar um resultado:



# Step 3: With the plan in place, provision the web app itself, which is the process that can host
# whatever code we want to deploy to it.

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 begin_create_or_update é do tipo AzureOperationPoller[Site], o que significa que o valor retornado 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 para 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.

Registro em log

As bibliotecas mais recentes do Azure usam a biblioteca padrão logging python para gerar a 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 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, consulte Como configurar proxies.

Argumentos opcionais para objetos e métodos do cliente

Na documentação de referência da biblioteca, você frequentemente vê um argumento **kwargs ou **operation_config na assinatura de um construtor de objeto 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 geralmente têm suporte, conforme descrito nas seções a seguir.

Argumentos para bibliotecas baseadas no azure.core

Esses argumentos se aplicam às bibliotecas listadas no 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 GitHub README para azure-core.

Nome	Tipo	Padrão	Descrição
logging_enable	Bool	Falso	Habilita o registro em log. Para obter mais informações, consulte Log nas bibliotecas do Azure.
Proxies	dicionário	{}	URLs do servidor proxy. Para obter mais informações, consulte Como configurar proxies.
use_env_settings	Bool	Verdade	Caso seja True, permite o uso de variáveis de ambiente `HTTP_PROXY` e `HTTPS_PROXY` para proxies. Se False, as variáveis de ambiente serão ignoradas. Para obter mais informações, consulte Como configurar proxies.
connection_timeout	int	300	O tempo limite em segundos para estabelecer uma conexão com os endpoints 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 permitidos para chamadas à API REST. Use `retry_total=0` para desativar repetições.
retry_mode	enumeração	exponencial	Aplica o tempo de repetição de maneira linear ou exponencial. Se forem 'single', as repetições serão feitas em intervalos regulares. Se for "exponencial", cada repetição aguardará duas vezes mais do que a 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 de 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 GitHub README 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 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 método create_or_update, você pode criar diretamente uma instância específica de ResourceGroup com os 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 em linha:

# 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 JSON aninhado.

Por exemplo, suponha que você tenha uma instância do objeto KeyVaultManagementClient e esteja chamando seu create_or_update. Nesse 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]. Um Sku contém um SkuName objeto e cada AccessPolicyEntry um contém um Permissions objeto.

Para chamar begin_create_or_update com objetos inseridos, você usa código como o seguinte (supondo tenant_id, object_ide LOCATION já está definido). 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 inline é exibida 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 ambos os formulários são equivalentes, você pode escolher o que preferir e até intercalá-los. (O código completo para esses exemplos pode ser encontrado no GitHub.)

Se o JSON não estiver formado corretamente, você normalmente receberá o erro "DesserializationError: não é possível desserializar para objeto: tipo, AttributeError: o objeto 'str' não tem nenhum atributo '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, 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ê entende os padrões comuns para usar as bibliotecas do Azure para Python, confira os exemplos autônomos a seguir para explorar cenários específicos de gerenciamento e biblioteca de clientes. Você pode experimentar esses exemplos em qualquer ordem, pois eles não são sequenciais ou interdependentes.

Comentários

Esta página foi útil?

Last updated on 2025-04-30