Compartir vía

Copiar un blob con programación asincrónica mediante Python

  • Artículo

En este artículo se muestra cómo copiar un blob con programación asincrónica mediante la biblioteca cliente de Azure Storage para Python. Puede copiar un blob desde un origen dentro de la misma cuenta de almacenamiento, desde un origen en una cuenta de almacenamiento diferente o desde cualquier objeto accesible recuperado a través de una solicitud HTTP GET en una dirección URL determinada. También puede anular una operación de copia pendiente.

Los métodos de la biblioteca cliente descritos en este artículo usan la operación de la API de REST Copiar blob y se pueden usar cuando desee realizar una copia con programación asincrónica. Para la mayoría de los escenarios de copia en los que desea mover datos a una cuenta de almacenamiento y tener una dirección URL para el objeto de origen, consulte Copiar un blob desde una dirección URL de objeto de origen con Python.

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 :

import datetime
from azure.identity import DefaultAzureCredential
from azure.storage.blob import (
    BlobServiceClient,
    BlobClient,
    BlobLeaseClient,
    BlobSasPermissions,
    generate_blob_sas
)

Authorization

El mecanismo de autorización debe tener los permisos necesarios para realizar una operación de copia, o para abortar una copia pendiente. Para la autorización con Microsoft Entra ID (recomendada), la función integrada Azure RBAC con menos privilegios varía en función de varios factores. 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 la copia de blobs con programación asincrónica

La operación Copy Blob puede finalizar de forma asincrónica y se realiza en función del mejor esfuerzo, lo que significa que no se garantiza que la operación se inicie inmediatamente o se complete dentro de un período de tiempo especificado. La operación de copia se programa en segundo plano y se realiza cuando el servidor tiene recursos disponibles. La operación se puede completar sincrónicamente si la copia se produce dentro de la misma cuenta de almacenamiento.

Una operación Copy Blob puede realizar cualquiera de las siguientes acciones:

  • Copie un blob de origen en un blob de destino con un nombre diferente. El blob de destino puede ser un blob existente del mismo tipo de blob (en bloques, anexos o en páginas), o puede ser un nuevo blob creado por la operación de copia.
  • Copie un blob de origen en un blob de destino con el mismo nombre, lo que reemplaza el blob de destino. Este tipo de operación de copia quita los bloques sin confirmar y sobrescribe los metadatos del blob de destino.
  • Copie un archivo de origen del servicio Azure File en un blob de destino. El blob de destino puede ser un blob en bloques existente o un nuevo blob de ese tipo creado por la operación de copia. No se admite la copia de archivos a blobs en páginas o blobs en anexos.
  • Copie una instantánea sobre su blob base. Si se mueve una instantánea a la posición del blob, puede restaurar una versión anterior de un blob.
  • Copie una instantánea en un blob de destino con otro nombre. El blob resultante de destino es un blob en el que se puede escribir y no una instantánea.

El blob de origen para una operación de copia puede ser de los siguientes tipos: blob en bloques, blob anexo, blob en páginas, instantánea de blob o la versión de un blob. La operación de copia siempre copia todo el blob o archivo de origen. No se admite la copia de un intervalo de bytes o un conjunto de bloques.

Si el blob de destino ya existe, debe ser del mismo tipo de blob que el blob de origen y se sobrescribe el blob de destino existente. El blob de destino no se puede modificar mientras está en curso una operación de copia y un blob de destino solo puede tener una operación de copia pendiente.

Para obtener más información sobre la operación Copy Blob, incluida la información sobre las propiedades, las etiquetas de índice, los metadatos y la facturación, consulte Comentarios sobre la copia de blobs.

Copiar un blob con programación asincrónica

En esta sección se proporciona información general sobre los métodos proporcionados por la biblioteca cliente de Azure Storage para Python para realizar una operación de copia con programación asincrónica.

Los métodos siguientes encapsulan la operación de la API de REST Copiar blob y comienzan una copia asincrónica de los datos del blob de origen:

start_copy_from_url devuelve un diccionario que contiene copy_status y copy_id. La propiedad copy_status es correcta si la copia se completó sincrónicamente o pendiente si la copia se ha iniciado de forma asincrónica.

Copiar un blob desde un origen dentro de Azure

Si va a copiar un blob dentro de la misma cuenta de almacenamiento, la operación se puede completar de forma sincrónica. El acceso al blob de origen se puede autorizar mediante Microsoft Entra ID, una firma de acceso compartido (SAS) o una clave de cuenta. Para obtener una operación de copia sincrónica alterativa, consulte Copiar un blob desde una dirección URL de objeto de origen con Python.

Si el origen de copia es un blob en otra cuenta de almacenamiento, la operación se puede completar de forma asincrónica. El blob de origen debe ser público o autorizado a través del token de SAS. El token de SAS debe incluir el permiso Lectura (“r”). Para más información sobre los tokens de SAS, consulte Delegación del acceso con firmas de acceso compartido.

En el ejemplo siguiente se muestra un escenario para copiar un blob de origen desde otra cuenta de almacenamiento con programación asincrónica. En este ejemplo, se crea una dirección URL de blob de origen con un token de SAS de delegación de usuarios anexado. En el ejemplo se muestra cómo generar el token de SAS mediante la biblioteca cliente, aunque también puede proporcionar el suyo propio. En este ejemplo también se muestra cómo conceder el blob de origen durante la operación de copia para evitar cambios en el blob desde un cliente diferente. La operación Copy Blob guarda el valor ETag del blob de origen cuando se inicia la operación de copia. Si el valor ETag se cambia antes de que finalice la operación de copia, se produce un error en la operación.

def copy_from_source_in_azure_async(self, source_blob: BlobClient, destination_blob: BlobClient, blob_service_client: BlobServiceClient):
    # Lease the source blob during copy to prevent other clients from modifying it
    lease = BlobLeaseClient(client=source_blob)

    sas_token = self.generate_user_delegation_sas(blob_service_client=blob_service_client, source_blob=source_blob)
    source_blob_sas_url = source_blob.url + "?" + sas_token

    # Create an infinite lease by passing -1 as the lease duration
    lease.acquire(lease_duration=-1)

    # Start the copy operation - specify False for the requires_sync parameter
    copy_operation = dict()
    copy_operation = destination_blob.start_copy_from_url(source_url=source_blob_sas_url, requires_sync=False)
    
    # If start_copy_from_url returns copy_status of 'pending', the operation has been started asynchronously
    # You can optionally add logic here to wait for the copy operation to complete

    # Release the lease on the source blob
    lease.break_lease()

def generate_user_delegation_sas(self, blob_service_client: BlobServiceClient, source_blob: BlobClient):
    # Get a user delegation key
    delegation_key_start_time = datetime.datetime.now(datetime.timezone.utc)
    delegation_key_expiry_time = delegation_key_start_time + datetime.timedelta(hours=1)
    key = blob_service_client.get_user_delegation_key(
        key_start_time=delegation_key_start_time,
        key_expiry_time=delegation_key_expiry_time
    )

    # Create a SAS token that's valid for one hour, as an example
    sas_token = generate_blob_sas(
        account_name=blob_service_client.account_name,
        container_name=source_blob.container_name,
        blob_name=source_blob.blob_name,
        account_key=None,
        user_delegation_key=key,
        permission=BlobSasPermissions(read=True),
        expiry=datetime.datetime.now(datetime.timezone.utc) + datetime.timedelta(hours=1),
        start=datetime.datetime.now(datetime.timezone.utc)
    )

    return sas_token

Nota:

Los tokens de SAS de delegación de usuarios ofrecen mayor seguridad, ya que se firman con credenciales de Microsoft Entra en lugar de con una clave de cuenta. Para crear un token de SAS de delegación de usuarios, la entidad de seguridad de Microsoft Entra necesita los permisos adecuados. Para conocer los requisitos de autorización, consulte Obtención de la clave de delegación de usuarios.

Copiar un blob desde un origen externo a Azure

Puede realizar una operación de copia en cualquier objeto de origen que se pueda recuperar a través de solicitudes HTTP GET en una dirección URL determinada, incluyendo los objetos accesibles de fuera de Azure. En el ejemplo siguiente se muestra un escenario para copiar un blob desde una dirección URL de objeto de origen accesible.

def copy_from_external_source_async(self, source_url: str, destination_blob: BlobClient):
    # Start the copy operation - specify False for the requires_sync parameter
    copy_operation = dict()
    copy_operation = destination_blob.start_copy_from_url(source_url=source_url, requires_sync=False)
    
    # If start_copy_from_url returns copy_status of 'pending', the operation has been started asynchronously
    # You can optionally add logic here to wait for the copy operation to complete

Comprobación del estado de una operación de copia

Para comprobar el estado de una operación asincrónica de Copy Blob, puede sondear el método get_blob_properties y comprobar el estado de la copia.

El siguiente ejemplo de código muestra cómo comprobar el estado de una operación de copia pendiente:

def check_copy_status(self, destination_blob: BlobClient):
    # Get the copy status from the destination blob properties
    copy_status = destination_blob.get_blob_properties().copy.status

    return copy_status

Anulación de una operación de copia

La anulación de una operación Copy Blob pendiente da como resultado un blob de destino de longitud cero. Sin embargo, los nuevos valores de los metadatos del blob de destino se copian del blob de origen o se establecen explícitamente durante la operación de copia. Para conservar los metadatos originales anteriores a la copia, cree una instantánea del blob de destino antes de llamar a uno de los métodos de copia.

Para anular una operación de copia pendiente, llame a la siguiente operación:

Estos métodos encapsulan la operación de la API de RESTAnular copia de blob, que cancela una operación Copy Blob pendiente. El siguiente ejemplo de código muestra cómo anular una operación Copy Blob pendiente:

def abort_copy(self, destination_blob: BlobClient):
    # Get the copy operation details from the destination blob properties
    copy_status = destination_blob.get_blob_properties().copy.status
    copy_id = destination_blob.get_blob_properties().copy.id

    # Check the copy status and abort if pending
    if copy_status == 'pending':
        destination_blob.abort_copy(copy_id)
        print(f"Copy operation {copy_id} has been aborted")

Recursos

Para obtener más información sobre cómo descargar blobs con programación asincrónica usando la biblioteca cliente de Azure Blob Storage para Python, consulte los recursos siguientes.

Ejemplos de código

Operaciones de API REST

Azure SDK para Python contiene bibliotecas que se basan en la API REST de Azure, lo que le permite interactuar con las operaciones de API REST por medio de paradigmas de Python que ya conoce. Los métodos de biblioteca cliente descritos en este artículo usan las siguientes operaciones de la API de REST:

Recursos de la biblioteca cliente

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.