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.

Configure 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. Para começar a usar o ambiente virtual, não deixe de ativá-lo. 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

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

Instalação da biblioteca

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

pip
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 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 como aiohttp para funcionar. A azure-core biblioteca fornece um transporte assíncrono, AioHttpTransportque é usado pelas bibliotecas assíncronas, portanto, talvez não seja necessário 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 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 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 poller para operações de longa duraçã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, 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. 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 código antigo para uma biblioteca mais recente baseada em azure.core normalmente significa adicionar o prefixo aos nomes de método, já que a begin_ maioria das assinaturas de método permanece a mesma.

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:



# 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 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 o código da aplicação, poderá usar blocos try...except em torno de operações da 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.

Exploração Florestal

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 Registo de logs 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 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 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.

Nome	Tipo	Predefinido	Descrição
ativar_registos	Bool	Falso	Permite o registo. Para obter mais informações, consulte Registo de logs nas bibliotecas do Azure.
Proxies	dicionário	{}	URLs de servidor proxy. Para obter mais informações, consulte Como configurar proxies.
usar_configurações_de_ambiente	Bool	Verdade	Se for Verdadeiro, permite o uso das variáveis de ambiente `HTTP_PROXY` e `HTTPS_PROXY` para proxies. Se False, as variáveis de ambiente são ignoradas. Para obter mais informações, consulte Como configurar proxies.
tempo_limite_de_conexão	Int	300	O tempo limite em segundos para estabelecer uma conexão com os endpoints da REST API do Azure.
tempo limite de leitura	Int	300	O tempo limite em segundos para concluir uma operação da API REST do Azure (ou seja, aguardando uma resposta).
repetição_total	Int	10	O número de tentativas de repetição permitidas para chamadas de API REST. Use `retry_total=0` para desativar retentativas.
modo_de_tentativa	enumeração	exponencial	Aplica o tempo de repetição de forma linear ou exponencial. Se for «única», são feitas novas tentativas a intervalos regulares. Se for 'exponencial', cada nova tentativa espera o dobro do tempo da tentativa anterior.

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 específicos de palavras-chave do armazenamento de blob, consulte o ficheiro README 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 objeto KeyVaultManagementClient e esteja chamando seu create_or_update. 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 esses exemplos pode ser encontrado no GitHub.)

Se o JSON não estiver formado corretamente, normalmente obterá 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 este erro porque o parâmetro sku é um objeto Sku que espera o objeto JSON em linha, 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.

Comentários

Esta página foi útil?

Last updated on 2025-04-22