Patrones de uso de las bibliotecas de Azure para Python

Artículo
10/18/2023

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

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

Configurar el 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. Puede crear el entorno virtual localmente o en Azure Cloud Shell y ejecutar el código allí. Asegúrese de activar el entorno virtual para empezar a usarlo.
Use un entorno de conda.
Use un contenedor de desarrollo en Visual Studio Code o GitHub Codespaces.

Para instalar un paquete 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 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 los paquetes de biblioteca de Azure para Python.

Para instalar un paquete de biblioteca específico en un entorno de 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

conda install recupera la versión más reciente de un paquete en el entorno de Conda actual.

Para más información, incluido cómo quitar paquetes o instalar versiones específicas, consulte Instalación de los paquetes de biblioteca de Azure para Python.

Operaciones asincrónicas

Bibliotecas asincrónicas

Muchas bibliotecas de administración y de cliente proporcionan versiones asincrónicas (.aio). La biblioteca asyncio está disponible a partir de 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 biblioteca azure-core proporciona un transporte asincrónico, AioHttpTransport, que las bibliotecas asincrónicas usan.

En el código siguiente se 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 WebSiteManagementClient.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:

Es posible que observe diferencias en los nombres de método de una biblioteca. Esto se debe a las diferencias de versión. Las bibliotecas más antiguas que no se basan en azure.core suelen usar nombres como create_or_update. Las bibliotecas basadas en azure.core agregan el prefijo begin_ a los nombres de método para indicar mejor que son operaciones de sondeo largas. La migración del código anterior a una biblioteca basada en azure.core más reciente normalmente significa agregar el prefijo begin_ a los nombres de método, ya que la mayoría de las firmas de método siguen siendo las mismas.

El tipo de valor devuelto LROPoller 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:

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 de tipo Site.

Excepciones

En general, las bibliotecas de Azure generan excepciones cuando las operaciones no funcionan según lo previsto, incluidas las solicitudes HTTP con errores a la API REST de Azure. Para el código de la aplicación, puede usar bloques try...except alrededor de las operaciones con la biblioteca.

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

Registro

Las bibliotecas de Azure más recientes usan la biblioteca logging estándar de Python para generar la salida del registro. Puede establecer el nivel de registro para bibliotecas individuales, para grupos de bibliotecas o para todas las bibliotecas. Después de registrar un controlador del 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 servidor proxy, puede usar variables de entorno o argumentos opcionales. Para más información, consulte Configuración de servidores proxy.

Argumentos opcionales para objetos y métodos de cliente

En la documentación de referencia de la biblioteca, a menudo se ve un argumento **kwargs u **operation_config en la firma de un constructor de objetos de cliente o 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 se pueden usar. También hay algunos argumentos generales que se suelen admitir, como se describe en las secciones siguientes.

Argumentos para las bibliotecas basadas en azure.core

Estos argumentos se aplican a las 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	Valor predeterminado	Descripción
logging_enable	bool	False	Habilita el registro. Para más información, consulte Registro en las bibliotecas de Azure.
proxies	dict	{}	Direcciones URL del servidor proxy. Para más información, consulte Configuración de servidores proxy.
use_env_settings	bool	True	Si es True, permite el uso de las variables de entorno `HTTP_PROXY` y `HTTPS_PROXY` para los servidores proxy. Si es False, se omiten las variables de entorno. Para más información, consulte Configuración de servidores proxy.
connection_timeout	int	300	Tiempo de expiración en segundos para establecer una conexión con los puntos de conexión de la API REST de Azure.
read_timeout	int	300	Tiempo de expiración en segundos para completar una operación de la 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.
retry_mode	enum	exponential	Aplica el tiempo de reintento de forma lineal o exponencial. Si es "single", los reintentos se realizan a intervalos regulares. Si es "exponential", 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 se debe consultar la documentación de referencia de cada biblioteca para conocer los detalles exactos. Además, cada biblioteca puede admitir otros argumentos. Por ejemplo, para los argumentos de palabra clave específicos de Blob Storage, consulte el archivo Léame de GitHub correspondiente a azure-storage-blob.

Patrón de JSON insertado para argumentos de objeto

Muchas operaciones 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 de este método es de tipo ResourceGroup.

Para llamar al método create_or_update, 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"}
)

Al usar 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 su método create_or_update. En este caso, el tercer argumento es de tipo VaultCreateOrUpdateParameters, que a su vez contiene un argumento de tipo VaultProperties. VaultProperties, a su vez, contiene argumentos de objeto de tipo Sku y list[AccessPolicyEntry]. Un argumento Sku contiene un objeto SkuName y cada argumento AccessPolicyEntry contiene un objeto Permissions.

Para llamar a begin_create_or_update con objetos insertados, se usa un código similar al siguiente (suponiendo que ya se hayan definido tenant_id, object_id y 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 insertado 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 ambas maneras son equivalentes, puede elegir el que prefiera e incluso intercambiarlos. (El código completo de estos ejemplos se encuentra en GitHub).

Si el JSON no se ha formado correctamente, normalmente aparece el error "DeserializationError: Unable to deserialize to object: type, AttributeError: 'str' object has no attribute 'get'". Una causa común de este error es que se proporciona una única 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 conoce los patrones comunes de uso de las bibliotecas de Azure para Python, consulte los siguientes ejemplos independientes para explorar escenarios específicos de la biblioteca cliente y de administración. Puede probar estos ejemplos en cualquier orden, ya que no son secuenciales ni interdependientes.

Compartir a través de