Creación y administración de concesiones de blobs con Python

  • Artículo

En este artículo se muestra cómo crear y administrar las concesiones de blob mediante la biblioteca cliente para Python de Azure Storage. Puede usar la biblioteca cliente para adquirir, renovar, liberar e interrumpir concesiones de blobs.

Para obtener información sobre cómo alquilar un blob mediante API asincrónicas, consulte Concesión de blobs de forma asincrónica.

Requisitos previos

Configurar el entorno

Si no tiene un proyecto existente, en esta sección se muestra cómo configurar uno para que funcione con la biblioteca cliente de Azure Blob Storage para Python. Para más información, vea Introducción a Azure Blob Storage y Python.

Para trabajar con los ejemplos de código de este artículo, siga los pasos siguientes a fin de configurar el proyecto.

Instalar paquetes

Instale los siguientes paquetes mediante pip install:

pip install azure-storage-blob azure-identity

Adición de instrucciones import

Agregue las instrucciones siguientes import :

from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient, BlobLeaseClient

Authorization

El mecanismo de autorización debe tener los permisos necesarios para poder funcionar con una concesión de blobs. Para la autorización con Microsoft Entra ID (recomendado) se necesita el rol integrado de RBAC de Azure de Colaborador de datos de Storage Blob o superior. Para obtener más información, consulte la guía de autorización de Blob de concesión (API de REST).

Creación de un objeto de cliente

Para conectar una aplicación a Blob Storage, cree una instancia de BlobServiceClient. En el ejemplo siguiente se muestra cómo crear un objeto de cliente mediante DefaultAzureCredential para la autorización:

# TODO: Replace <storage-account-name> with your actual storage account name
account_url = "https://<storage-account-name>.blob.core.windows.net"
credential = DefaultAzureCredential()

# Create the BlobServiceClient object
blob_service_client = BlobServiceClient(account_url, credential=credential)

También puede crear objetos de cliente para contenedores o blobs específicos ya sea directamente o desde el objeto BlobServiceClient. Para obtener más información sobre cómo crear y administrar objetos de cliente, consulte Crear y administrar objetos de cliente que interactúan con los recursos de datos.

Acerca de las concesiones de blobs

Una concesión crea y administra un bloqueo en un blob para las operaciones de escritura y eliminación. La duración del bloqueo puede ser de 15 a 60 segundos, o puede ser infinita. Una concesión sobre un blob proporciona acceso exclusivo de escritura y eliminación sobre el blob. Para escribir en un blob con una concesión activa, un cliente debe incluir el identificador de la concesión activa en la solicitud de escritura.

Para obtener más información sobre los estados de concesión y cuándo puede realizar una acción determinada en una concesión, consulte Estados y acciones de concesión.

Se admiten todas las operaciones de contenedor en un contenedor que incluye blobs con una concesión activa, como Delete Container. Por lo tanto, un contenedor puede eliminarse aunque los blobs que contiene tengan concesiones activas. Utilice la operación Lease Container para controlar los derechos para eliminar un contenedor.

Las operaciones de concesión se controlan mediante la clase BlobLeaseClient, que proporciona un cliente que contiene todas las operaciones de concesión para blobs y contenedores. Para obtener más información sobre las concesiones de contenedor mediante la biblioteca cliente, consulte Creación y administración de concesiones de contenedor con Python.

Adquisición de una concesión

Al adquirir una concesión de blob, obtiene un id. de concesión que el código puede usar para operar en el blob. Si el blob ya tiene una concesión activa, solo puede solicitar una nueva concesión mediante el id. de concesión activo. No obstante, puede especificar una nueva duración de concesión.

Para adquirir una concesión, cree una instancia de la clase BlobLeaseClient y, a continuación, use cualquiera de estos métodos:

También puede adquirir una concesión en un blob mediante la creación de una instancia de BlobClient y el uso del método siguiente:

En el ejemplo siguiente, se adquiere una concesión de 30 segundos para un blob.

def acquire_blob_lease(self, blob_service_client: BlobServiceClient, container_name):
    # Instantiate a BlobClient
    blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")

    # Acquire a 30-second lease on the blob
    lease_client = blob_client.acquire_lease(30)

    return lease_client

Renovación de una concesión

Puede renovar una concesión de blob si el id. de concesión especificado en la solicitud coincide con el id. de concesión asociado al blob. La concesión se puede renovar incluso si ha expirado, siempre que el blob no se haya modificado ni concedido de nuevo desde la caducidad de la concesión. Cuando se renueva una concesión, se restablece su duración.

Para renovar una concesión, use el método siguiente:

En el ejemplo siguiente, se renueva una concesión para un blob:

def renew_blob_lease(self, lease_client: BlobLeaseClient):
    # Renew a lease on a blob
    lease_client.renew()

Liberación de una concesión

Puede liberar una concesión de blob si el id. de concesión especificado en la solicitud coincide con el id. de concesión asociado al blob. Liberar la concesión permite a otro cliente adquirir la concesión sobre el blob inmediatamente después de que finalice la operación de liberación.

Puede liberar una concesión mediante el método siguiente:

En el ejemplo siguiente, se libera la concesión en un contenedor.

def release_blob_lease(self, lease_client: BlobLeaseClient):
    # Release a lease on a blob
    lease_client.release()

Interrupción de una concesión

Puede interrumpir una concesión de blobs si el blob tiene una concesión activa. Cualquier solicitud autorizada puede interrumpir la concesión; no es necesario que la solicitud especifique un identificador de concesión que coincida. Una concesión no se puede renovar después de que se interrumpa e interrumpir una concesión impide que se adquiera una nueva concesión durante un período de tiempo hasta que expire o se libere la concesión original.

Puede interrumpir una concesión mediante el método siguiente:

En el ejemplo siguiente, se interrumpe la concesión de un blob:

def break_blob_lease(self, lease_client: BlobLeaseClient):
    # Break a lease on a blob
    lease_client.break_lease()

Concesión de blobs de forma asincrónica

La biblioteca cliente de Azure Blob Storage para Python admite la concesión de blobs de forma asincrónica. Para obtener más información sobre los requisitos de configuración del proyecto, consulte Programación asincrónica.

Siga estos pasos para conceder un blob mediante API asincrónicas:

  1. Agregue las siguientes instrucciones import:

    import asyncio

from azure.identity.aio import DefaultAzureCredential
from azure.storage.blob.aio import BlobServiceClient, BlobLeaseClient

  2. Agregue código para ejecutar el programa mediante asyncio.run. Esta función ejecuta la corrutina pasada, main() en nuestro ejemplo, y administra el bucle de eventos asyncio. Las corrutinas se declaran con la sintaxis async/await. En este ejemplo, la corrutina main() crea primero el nivel superior BlobServiceClient mediante async with, y a continuación, llama al método que adquiere la concesión del blob. Tenga en cuenta que solo el cliente de nivel superior debe usar async with, ya que otros clientes creados a partir de él comparten el mismo grupo de conexiones.

    async def main():
    sample = BlobSamples()

    # TODO: Replace <storage-account-name> with your actual storage account name
    account_url = "https://<storage-account-name>.blob.core.windows.net"
    credential = DefaultAzureCredential()

    async with BlobServiceClient(account_url, credential=credential) as blob_service_client:
        lease_client = await sample.acquire_blob_lease(blob_service_client, "sample-container")

if __name__ == '__main__':
    asyncio.run(main())

  3. Agregue código para adquirir una concesión de blobs. El código es el mismo que el ejemplo sincrónico, salvo que el método se declara con la palabra clave async y la palabra clave await se usa al llamar al método acquire_lease.

    async def acquire_blob_lease(self, blob_service_client: BlobServiceClient, container_name):
    # Instantiate a BlobClient
    blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")

    # Acquire a 30-second lease on the blob
    lease_client = await blob_client.acquire_lease(30)

    return lease_client

Con esta configuración básica, puede implementar otros ejemplos de este artículo como corrutinas mediante la sintaxis async/await.

Estados y acciones de concesión

En el diagrama siguiente se muestran los cinco estados de una concesión y los comandos o los eventos que provocan cambios en el estado de la misma.

Diagrama que muestra los estados de concesión de blobs y los desencadenadores de cambio de estado.

En la tabla siguiente se enumeran los cinco estados de concesión, se proporciona una breve descripción de cada uno y se enumeran las acciones de concesión permitidas en un estado determinado. Estas acciones de concesión provocan transiciones de estado, como se muestra en el diagrama.

Estado de concesión Descripción Acciones de concesión permitidas
Disponible La concesión está desbloqueada y se puede adquirir. acquire
Leased La concesión está bloqueada. acquire (solo con el mismo identificador de concesión), renew, change, release y break.
Expired La duración de la concesión ha expirado. acquire, renew, release y break.
Problemático La concesión se ha interrumpido, pero seguirá bloqueada hasta que haya expirado el período de interrupción. release y break
Interrumpido La concesión se ha interrumpido y el período de interrupción ha expirado. acquire, release y break

Cuando expira una concesión, Blob service mantiene el identificador de concesión hasta que el blob se modifica o se concede de nuevo. Un cliente puede intentar renovar o liberar la concesión mediante el identificador de concesión expirado. Si esta operación se realiza correctamente, el cliente sabe que el blob no se ha cambiado desde que el identificador de concesión era el último válido. Si se produce un error en la solicitud, el cliente sabe que el blob se ha modificado o se ha concedido de nuevo desde que la concesión estuvo activa por última vez. En ese caso, el cliente deberá adquirir una nueva concesión sobre el blob.

Si una concesión expira en lugar de liberarse explícitamente, es posible que el cliente tenga que esperar hasta un minuto para poder adquirir una nueva concesión sobre el blob. Sin embargo, el cliente puede renovar la concesión inmediatamente con el identificador de concesión si el blob no se ha modificado.

No se puede conceder una concesión para una instantánea de blob, dado que las instantáneas son de solo lectura. Si se solicita una concesión sobre una instantánea, se obtiene el código de estado 400 (Bad Request).

Recursos

Para obtener más información sobre cómo administrar concesiones de blob con la biblioteca cliente de Azure Blob Storage para Python, consulte los recursos siguientes.

Ejemplos de código

Operaciones de API REST

El SDK de Azure para Python contiene bibliotecas que se crean a partir de la API REST de Azure, lo que le permite interactuar con las operaciones de API REST a través de paradigmas conocidos de Python. Los métodos de la biblioteca cliente para administrar concesiones de blob usan esta operación de API de REST:

Recursos de la biblioteca cliente

Consulte también

Contenido relacionado

  • Este artículo forma parte de la guía para desarrolladores de Blob Storage para Python. Para más información, consulte la lista completa de artículos de la guía para desarrolladores en Compilación de la aplicación de Python.