Compartir a través de

Bibliotecas de Azure para patrones de uso de Python

El SDK de Azure para Python se compone de muchas bibliotecas independientes, que se enumeran en el índice de paquetes del SDK de Python.

Todas las bibliotecas comparten ciertas características comunes y patrones de uso, como la instalación y el uso de JSON insertado para argumentos de objeto.

Configuración del entorno de desarrollo local

Si aún no lo ha hecho, puede configurar un entorno en el que pueda ejecutar este código. Estas son algunas opciones:

  • Configure un entorno virtual de Python mediante venv o la herramienta que prefiera. Para empezar a usar el entorno virtual, asegúrese de activarlo. Para instalar Python, consulte Instalación de Python.

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

  • Use un entorno de Conda. Para instalar Conda, consulte Instalación de Miniconda.

  • Usa un contenedor de desarrollo en Visual Studio Code o en GitHub Codespaces .

Instalación de la biblioteca

Elija el método de instalación correspondiente a la herramienta de administración del entorno de Python, ya sea pip o conda.

Para instalar un paquete 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 la versión más reciente de una biblioteca en el entorno de Python actual.

También puede usar pip para desinstalar bibliotecas e instalar versiones específicas, incluidas las versiones preliminares. Para más información, consulte Instalación de paquetes de biblioteca de Azure para Python.

Operaciones asincrónicas

Bibliotecas asincrónicas

Muchas bibliotecas de administración y cliente proporcionan versiones asincrónicas (.aio). La asyncio biblioteca está disponible desde Python 3.4 y las palabras clave async/await se introdujeron en Python 3.5. Las versiones asincrónicas de las bibliotecas están diseñadas para usarse con Python 3.5 y versiones posteriores.

Algunos ejemplos de bibliotecas del SDK de Azure Python con versiones asincrónicas son : azure.storage.blob.aio, azure.servicebus.aio, azure.mgmt.keyvault.aio y azure.mgmt.compute.aio.

Estas bibliotecas necesitan un transporte asincrónico como aiohttp para funcionar. La azure-core biblioteca proporciona un transporte asincrónico, , AioHttpTransportque usa las bibliotecas asincrónicas, por lo que es posible que no sea necesario instalar aiohttp por separado.

En el código siguiente se muestra cómo crear un archivo de Python que muestra cómo crear un cliente para la versión asincrónica de la biblioteca de Azure Blob Storage:

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())

El ejemplo completo está en GitHub en use_blob_auth_async.py. Para obtener la versión sincrónica de este código, consulte Ejemplo: Carga de un blob.

Operaciones de larga duración

Algunas operaciones de administración que se invocan (como ComputeManagementClient.virtual_machines.begin_create_or_update y WebAppsClient.web_apps.begin_create_or_update) devuelven un sondeo para operaciones de larga duración, LROPoller[<type>], donde <type> es específico de la operación en cuestión.

Nota:

Puede observar diferencias en los nombres de método de una biblioteca en función de su versión y de si se basa en azure.core. Las bibliotecas anteriores que no se basan en azure.core suelen usar nombres como create_or_update. Las bibliotecas basadas en azure.core agregan el begin_ prefijo a los nombres de método para indicar mejor que son operaciones de sondeo largas. Migrar código antiguo a una biblioteca basada en azure.core más reciente normalmente significa agregar el begin_ prefijo a los nombres de método, ya que la mayoría de las firmas de método siguen siendo las mismas.

El LROPoller tipo de valor devuelto significa que la operación es asincrónica. En consecuencia, debe llamar al método result del sondeador para esperar a que finalice la operación y obtener el resultado.

El código siguiente, tomado de Ejemplo: Creación e implementación de una aplicación web, muestra un ejemplo del uso del sondeo para esperar un 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()

En este caso, el valor devuelto de begin_create_or_update es de tipo AzureOperationPoller[Site], lo que significa que el valor devuelto de poller.result() es un objeto Site.

Excepciones

En general, las bibliotecas de Azure generan excepciones cuando las operaciones no funcionan según lo previsto, incluidas las solicitudes HTTP erróneas a la API REST de Azure. En el caso del código de la aplicación, puede usar bloques try...except en torno a las operaciones de biblioteca.

Para obtener más información sobre el tipo de excepciones que se pueden generar, consulte la documentación de la operación en cuestión.

Registro

Las bibliotecas de Azure más recientes usan la biblioteca estándar logging de Python para generar la salida del registro. Puede establecer el nivel de registro para bibliotecas individuales, grupos de bibliotecas o todas las bibliotecas. Una vez registrado un controlador de flujo de registro, puede habilitar el registro para un objeto de cliente específico o una operación específica. Para más información, consulte Registro en las bibliotecas de Azure.

Configuración de proxy

Para especificar un proxy, puede usar variables de entorno o argumentos opcionales. Para obtener más información, consulte Configuración de servidores proxy.

Argumentos opcionales para los objetos y métodos de cliente

En la documentación de referencia de la biblioteca, a menudo se ve un argumento **kwargs o **operation_config en la firma de un constructor de objeto cliente o de un método de operación específico. Estos marcadores de posición indican que el objeto o el método en cuestión pueden admitir otros argumentos con nombre. Normalmente, la documentación de referencia indica los argumentos específicos que puede usar. También hay algunos argumentos generales que a menudo se admiten como se describe en las secciones siguientes.

Argumentos para bibliotecas basadas en azure.core

Estos argumentos se aplican a esas bibliotecas enumeradas en Python: nuevas bibliotecas. Por ejemplo, este es un subconjunto de los argumentos de palabra clave para azure-core. Para obtener una lista completa, consulte el archivo LÉAME de GitHub para azure-core.

Nombre Tipo Predeterminado Descripción
logging_enable booleano Falso Habilita el registro. Para más información, consulte Registro en las bibliotecas de Azure.
Proxies diccionario {} Direcciones URL del servidor proxy. Para obtener más información, consulte Configuración de servidores proxy.
use_env_settings booleano Cierto Si es True, permite el uso de las variables de entorno HTTP_PROXY y HTTPS_PROXY para servidores proxy. Si es False, se omiten las variables de entorno. Para obtener más información, consulte Configuración de servidores proxy.
connection_timeout Int 300 Tiempo de espera en segundos para realizar una conexión a los puntos de conexión de la API REST de Azure.
read_timeout Int 300 Tiempo de espera en segundos para completar una operación de API REST de Azure (es decir, esperar una respuesta).
retry_total Int 10 Número de reintentos permitidos para las llamadas a la API REST. Utilice retry_total=0 para deshabilitar los reintentos.
modo de reintento enumeración exponencial Aplica el tiempo de reintento de forma lineal o exponencial. Si es "single", los reintentos se realizarán a intervalos regulares. Si es "exponencial", cada reintento espera el doble de tiempo que el reintento anterior.

Las bibliotecas individuales no están obligadas a admitir ninguno de estos argumentos, por lo que siempre consulte la documentación de referencia de cada biblioteca para obtener detalles exactos. Además, cada biblioteca puede admitir otros argumentos. Por ejemplo, para argumentos específicos de clave de blob storage, ver el README de GitHub para azure-storage-blob.

Patrón JSON en línea para argumentos de objeto

Muchas operaciones dentro de las bibliotecas de Azure permiten expresar argumentos de objeto como objetos discretos o como JSON insertado.

Por ejemplo, supongamos que tiene un objeto ResourceManagementClient mediante el cual se crea un grupo de recursos con el método create_or_update. El segundo argumento para este método es de tipo ResourceGroup.

Para llamar al create_or_update método , puede crear una instancia discreta de ResourceGroup directamente con sus argumentos necesarios (location en este caso):

# Provision the resource group.
rg_result = resource_client.resource_groups.create_or_update(
    "PythonSDKExample-rg",
    ResourceGroup(location="centralus")
)

Como alternativa, puede pasar los mismos parámetros como JSON insertado:

# Provision the resource group.
rg_result = resource_client.resource_groups.create_or_update(
    "PythonAzureExample-rg", {"location": "centralus"}
)

Cuando se usa JSON insertado, las bibliotecas de Azure convierten automáticamente el JSON insertado en el tipo de objeto adecuado para el argumento en cuestión.

Los objetos también pueden tener argumentos de objeto anidados, en cuyo caso también puede usar JSON anidado.

Por ejemplo, supongamos que tiene una instancia del objeto KeyVaultManagementClient y llama a create_or_update. En este caso, el tercer argumento es de tipo VaultCreateOrUpdateParameters, que contiene un argumento de tipo VaultProperties. VaultProperties, a su vez, contiene argumentos de objeto de tipo Sku y list[AccessPolicyEntry]. un Sku objeto contiene un SkuName objeto y cada AccessPolicyEntry uno contiene un Permissions objeto .

Para llamar a begin_create_or_update con objetos incrustados, use código como el siguiente (suponiendo tenant_idque ya están definidos , object_idy LOCATION ). También puede crear los objetos necesarios antes de la llamada de función.

# 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()

La misma llamada que usa JSON en línea aparece de la siguiente manera:

# 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()

Dado que ambos formularios son equivalentes, puede elegir lo que prefiera e incluso mezclarlos. (El código completo de estos ejemplos se puede encontrar en GitHub).

Si el JSON no se ha formado correctamente, normalmente aparece el error "DeserializationError: No se puede deserializar en el objeto: type, AttributeError: 'str' object no tiene el atributo 'get'". Una causa común de este error es que se proporciona una sola cadena para una propiedad cuando la biblioteca espera un objeto JSON anidado. Por ejemplo, si se usa 'sku': 'standard' en el ejemplo anterior, se genera este error porque el parámetro sku es un objeto Sku que espera el objeto JSON insertado, en este caso {'name': 'standard'}, que se asigna al tipo SkuName esperado.

Pasos siguientes

Ahora que comprende los patrones comunes para usar las bibliotecas de Azure para Python, consulte los siguientes ejemplos independientes para explorar escenarios de biblioteca cliente y administración específicos. Puede probar estos ejemplos en cualquier orden, ya que no son secuenciales o interdependientes.