Copier un objet blob avec une planification asynchrone à l’aide de Python

  • Article

Cet article explique comment copier un blob avec une planification asynchrone à l’aide de la bibliothèque de client Stockage Azure pour Python. Vous pouvez copier un blob à partir d’une source dans le même compte de stockage, d’une source dans un autre compte de stockage ou de tout objet accessible récupéré via une requête HTTP GET sur une URL donnée. Vous pouvez également abandonner une opération de copie en attente.

Les méthodes de bibliothèque de client décrites dans cet article utilisent l’opération d’API REST Copier un blob et peuvent être utilisées lorsque vous souhaitez effectuer une copie avec une planification asynchrone. Dans la plupart des scénarios de copie selon lesquels vous souhaitez déplacer des données dans un compte de stockage et avoir une URL pour l’objet source, consultez Copier un blob à partir d’une URL d’objet source avec Python.

Prérequis

Paramétrer votre environnement

Si vous n’avez aucun projet existant, cette section vous montre comment configurer un projet de façon à utiliser la bibliothèque de client Stockage Blob Azure pour Python. Pour plus d’informations, consultez Bien démarrer avec le service Stockage Blob Azure et Python.

Pour utiliser les exemples de code de cet article, effectuez les étapes suivantes pour configurer votre projet.

Installer des packages

Installez les packages suivants en utilisant pip install :

pip install azure-storage-blob azure-identity

Ajouter des instructions import

Ajoutez les instructions import suivantes :

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

Autorisation

Le mécanisme d’autorisation doit disposer des autorisations nécessaires pour effectuer une opération de copie ou abandonner une copie en attente. Pour l’autorisation avec Microsoft Entra ID (recommandé), le rôle intégré RBAC Azure avec le moins de privilèges varie en fonction de plusieurs facteurs. Pour en savoir plus, consultez les conseils d’autorisation pour les opérations Copy Blob (API REST) ou Abort Copy Blob (API REST).

Créer un objet client

Pour connecter une application au Stockage Blob, créez une instance de BlobServiceClient. L’exemple suivant montre comment créer un objet client à l’aide de DefaultAzureCredential pour l’autorisation :

# 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)

Vous pouvez également créer des objets clients pour des conteneurs ou des objets blob spécifiques, directement ou à partir de l’objet BlobServiceClient. Pour en savoir plus sur la création et la gestion d’objets clients, consultez Créer et gérer des objets clients qui interagissent avec des ressources de données.

À propos de la copie de blob avec la planification asynchrone

L’opération Copy Blob peut se terminer de manière asynchrone et est effectuée selon les meilleurs efforts, ce qui signifie que l’opération n’est pas garantie de démarrer immédiatement ou de se terminer dans un délai spécifié. L’opération de copie est planifiée en arrière-plan et effectuée lorsque le serveur dispose de ressources disponibles. L’opération peut se terminer de manière synchrone si la copie se produit dans le même compte de stockage.

Une opération Copy Blob peut effectuer l’une des actions suivantes :

  • Copiez un objet blob source vers un objet blob de destination avec un nom différent. Le blob de destination peut être un blob existant du même type de blob (bloc, ajout ou page) ou un nouveau blob créé par l’opération de copie.
  • Copiez un blob source vers un blob de destination portant le même nom, ce qui a pour effet de remplacer le blob de destination. Ce type d’opération de copie supprime tous les blocs non validés et remplace les métadonnées du blob de destination.
  • Copiez un fichier source figurant dans le service Azure File vers un objet blob de destination. L’objet blob de destination peut être un objet blob existant ou un nouvel objet blob de blocs créé par l’opération de copie. La copie à partir de fichiers vers des blob de pages ou d’ajout n’est pas prise en charge.
  • Copiez un instantané sur son objet blob de base. En plaçant un instantané à la place d'un objet blob de base, vous pouvez restaurer une version antérieure de l’objet blob.
  • Copiez un instantané sur un objet blob de destination avec un nom différent. L’objet blob de destination obtenu est un objet blob modifiable et non pas un instantané.

Le blob source d’une opération de copie peut être l’un des types suivants : un blob de blocs, un blob d’ajout, un blob de pages, un instantané ou une version de blob. L’opération de copie copie toujours l’intégralité du blob ou du fichier source. La copie d’une plage d’octets ou d’un ensemble de blocs n’est pas prise en charge.

Si le blob de destination existe déjà, il doit être du même type que le blob source, et le blob de destination existant est remplacé. L’objet blob de destination ne peut pas être modifié lorsqu’une opération de copie est en cours et un objet blob de destination ne peut avoir qu’une seule opération de copie en attente.

Pour en savoir plus sur l’opération Copy Blob, notamment des informations sur les propriétés, les balises d’index, les métadonnées et la facturation, consultez Copier les remarques du blob.

Copier un blob avec une planification asynchrone

Cette section donne une vue d’ensemble des méthodes offertes par la bibliothèque de client de Stockage Azure pour Python afin d’effectuer une opération de copie avec une planification asynchrone.

Les méthodes suivantes encapsulent l’opération d’API REST Copier un blob et commencent une copie asynchrone des données à partir du blob source :

start_copy_from_url renvoie un dictionnaire contenant copy_status et copy_id. La propriété copy_status est réussie si la copie s’est terminée de manière synchrone ou en attente si la copie a été démarrée de manière asynchrone.

Copier un objet blob depuis une source dans Azure

Si vous copiez un objet blob dans le même compte de stockage, l’opération peut se terminer de manière synchrone. L’accès au blob source peut être autorisé avec Microsoft Entra ID, une signature d’accès partagé (SAS) ou une clé de compte. Pour une autre opération de copie synchrone, consultez Copier un objet blob à partir d’une URL d’objet source avec Python.

Si la source de copie est un objet blob dans un autre compte de stockage, l’opération peut se terminer de manière asynchrone. L’objet blob source doit être public ou autorisé via un jeton SAS. Le jeton SAP doit inclure l’autorisation Read ('r'). Pour en savoir plus sur les jetons SAP, consultez Déléguer l’accès avec des signatures d’accès partagé.

L’exemple suivant montre un scénario de copie d’un objet blob source à partir d’un autre compte de stockage avec une planification asynchrone. Dans cet exemple, nous créons une URL d’objet blob source avec un jeton SAP de délégation d’utilisateur ajouté. L’exemple montre comment générer le jeton SAP à l’aide de la bibliothèque de client, mais vous pouvez également fournir les vôtre. L’exemple montre également comment louer l’objet blob source pendant l’opération de copie pour empêcher des modifications apportées au blob à partir d’un autre client. L’opération Copy Blob enregistre la valeur ETag du blob source au démarrage de l’opération de copie. Si la valeur ETag est modifiée avant la fin de l’opération de copie, l’opération échoue.

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

Remarque

Les jetons SAP de délégation d’utilisateur offrent une plus grande sécurité, car ils sont signés avec des informations d’identification Microsoft Entra au lieu d’une clé de compte. Pour créer un jeton SAP de délégation d’utilisateur, le principal de sécurité Microsoft Entra a besoin des autorisations appropriées. Pour connaître les exigences d’autorisation, consultez Obtenir une clé de délégation d’utilisateur.

Copier un blob à partir d’une source en dehors d’Azure

Vous pouvez effectuer une opération de copie sur n’importe quel objet source qui peut être récupéré via une requête HTTP GET sur une URL donnée, y compris les objets accessibles extérieurs à Azure. L’exemple suivant illustre un scénario de copie d’un blob à partir d’une URL d’objet source accessible.

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

Vérifier l’état d’une opération de copie

Pour vérifier l’état d’une opération Copy Blob asynchrone, vous pouvez interroger la méthode get_blob_properties et vérifier l’état de la copie.

L’exemple de code suivant montre comment vérifier l’état d’une opération de copie en attente :

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

Abandonner une opération de copie

L'abandon d'une opération Copy Blob en attente génère un blob de destination de longueur nulle. Toutefois, les métadonnées du blob de destination ont les nouvelles valeurs copiées depuis le blob source ou définies explicitement pendant l'opération de copie. Pour conserver les métadonnées d’origine antérieures à la copie, créez un instantané de l’objet blob de destination avant d’appeler une des méthodes de copie.

Pour abandonner une opération de copie en attente, appelez l’opération suivante :

Cette méthode inclut l’opération d’API REST Abort Copy Blob dans un wrapper, ce qui annule une opération Copy Blob en attente. L’exemple de code suivant montre comment abandonner une opération Copy Blob en attente :

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")

Ressources

Pour en savoir plus sur la copie d’objets blob avec une planification asynchrone à l’aide de la bibliothèque de client Stockage Blob Azure pour Python, consultez les ressources suivantes.

Exemples de code

Opérations de l'API REST

Le kit de développement logiciel (SDK) Azure pour Python contient des bibliothèques qui s’appuient sur l’API REST Azure, vous permettant d’interagir avec les opérations de l’API REST par le biais de paradigmes Python familiers. Les méthodes de bibliothèque de client décrites dans cet article utilisent les opérations d’API REST suivantes :

Ressources de bibliothèque cliente

Contenu connexe

  • Cet article fait partie du guide Stockage Blob pour Python pour les développeurs. Pour découvrir plus d’informations, consultez la liste complète des articles du guide du développeur dans Générer votre application Python.