Share via

Patrones de uso de las bibliotecas de Azure para Python

  • Artículo

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 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:

Instalación de la biblioteca

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.

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.

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ífica de la operación en cuestión.

Nota:

Puede observar diferencias en los nombres de método de una biblioteca, lo que se debe a las diferencias de versión. 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. 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 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:

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 con errores a la API REST de Azure. En el caso del código de la aplicación, puede usar try...except bloques 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 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 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 método en cuestión puede 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 consulte la documentación de referencia de cada biblioteca para obtener 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 para 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 ResourceManagementClient objeto a través del cual se crea un grupo de recursos con su create_or_update método . El segundo argumento de 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 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 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 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: 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 ú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 o interdependientes.