Patrones de uso de las bibliotecas de Azure para Python

El SDK de Azure para Python se compone exclusivamente 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.

Instalación de la biblioteca

# 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

# Install the Azyre management library package
conda install azure-mgmt

# Install the client library for Azure Storage
conda install azure-storage

Operaciones asincrónicas

Muchas operaciones que se invocan mediante objetos de cliente y objetos de administración de cliente (como ComputeManagementClient.virtual_machines.begin_create_or_update y WebSiteManagementClient.web_apps.create_or_update) devuelven un objeto de tipo AzureOperationPoller[<type>] en el que el elemento <type> es específico de la operación en cuestión.

Ambos métodos son asincrónicos. Los distintos nombres de método se deben 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 asincrónicos. 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.

En cualquier caso, un tipo de valor devuelto AzureOperationPoller significa definitivamente 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: Aprovisionamiento e implementación de una aplicación web, muestra un ejemplo del uso del sondeador 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 es de tipo , lo que significa begin_create_or_update que el valor devuelto de es un objeto AzureOperationPoller[Site]poller.result()begin_create_or_update

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 argumentos con nombre adicionales. 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.

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.

Argumentos para bibliotecas no principales

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 a create_or_update puede crear una instancia discreta de ResourceGroup directamente con sus argumentos necesarios (location en este caso):

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:

rg_result = resource_client.resource_groups.create_or_update(
    "PythonAzureExample-rg",
    {
        "location": "centralus"
    }
)

Al usar JSON, 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 y object_id): 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 = "centralus",
        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': 'centralus',
        '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 tiene el formato correcto, normalmente se muestra el error "DeserializationError: Unable to deserialize to object: type, AttributeError: 'str' object has no attribute 'get'" (DeserializationError: No se puede deserializar en el objeto: tipo, AttributeError: el objeto 'str' no tiene un 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 ni interdependientes.

• Ejemplo: Creación de un grupo de recursos

• Ejemplo: Uso de Azure Storage

• Ejemplo: Aprovisionamiento de una aplicación web e implementación de código

• Ejemplo: Aprovisionamiento y consulta de una base de datos

• Ejemplo: Aprovisionamiento de una máquina virtual

• Uso de Azure Managed Disks con máquinas virtuales

• Realización de una breve encuesta sobre el SDK de Azure para Python