Bibliotecas do Azure para padrões de uso Python

  • Artigo

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:

Instalação da 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 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.

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.

Nota

Você pode notar diferenças nos nomes de método em uma biblioteca, o que se deve 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 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:

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.

Nome Tipo Predefinido Description
logging_enable booleano False Permite o registro em log. Para obter mais informações, consulte Registro em log nas bibliotecas do Azure.
Proxies ditado {} URLs de servidor proxy. Para obter mais informações, consulte Como configurar proxies.
use_env_settings booleano True Se True, permite o uso de variáveis e HTTP_PROXYHTTPS_PROXY de ambiente para proxies. Se False, as variáveis de ambiente são ignoradas. Para obter mais informações, consulte Como configurar proxies.
connection_timeout número inteiro 300 O tempo limite em segundos para estabelecer uma conexão com pontos de extremidade da API REST do Azure.
read_timeout número inteiro 300 O tempo limite em segundos para concluir uma operação da API REST do Azure (ou seja, aguardando uma resposta).
retry_total número inteiro 10 O número de tentativas de repetição permitidas para chamadas de API REST. Use retry_total=0 para desativar tentativas.
retry_mode 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 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.