Partager via

Copier un objet blob avec une planification asynchrone avec Go

  • Article

Cet article explique comment copier un objet blob avec la planification asynchrone en utilisant le module client Stockage Azure pour Go. Vous pouvez copier un objet blob à partir d’une source du 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 décrites dans cet article utilisent l’opération d’API REST Copier des objets blob et peuvent être utilisées lorsque vous souhaitez effectuer une copie avec une planification asynchrone. Pour la plupart des scénarios de copie où vous souhaitez déplacer des données dans un compte de stockage et avoir une URL pour l’objet source, consultez Copier un objet blob depuis une URL d’objet source avec Go.

Prérequis

Paramétrer votre environnement

Si vous n’avez aucun projet existant, cette section montre comment configurer un projet pour qu’il fonctionne avec le module client du Stockage Blob Azure pour Go. Les étapes incluent l’installation du module, l’ajout de chemins d’accès import et la création d’un objet client autorisé. Pour plus d’informations, consultez Prise en main de Stockage Blob Azure et de Go.

Installer des modules

Installez le module azblob à l’aide de la commande suivante :

go get github.com/Azure/azure-sdk-for-go/sdk/storage/azblob

Pour vous authentifier auprès de Microsoft Entra ID (recommandé), installez le module azidentity à l’aide de la commande suivante :

go get github.com/Azure/azure-sdk-for-go/sdk/azidentity

Ajouter des chemins d’importation

Dans votre fichier de code, ajoutez les chemins d’importation suivants :

import (
    "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
	"github.com/Azure/azure-sdk-for-go/sdk/storage/azblob"
)

Ces chemins d’importation représentent le minimum nécessaire pour démarrer. Certains exemples de code de cet article peuvent nécessiter des chemins d’importation supplémentaires. Pour plus d’informations et des exemples d’utilisation spécifiques, consultez Exemples de code.

Créer un objet client

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

func getServiceClientTokenCredential(accountURL string) *azblob.Client {
    // Create a new service client with token credential
    credential, err := azidentity.NewDefaultAzureCredential(nil)
    handleError(err)

    client, err := azblob.NewClient(accountURL, credential, nil)
    handleError(err)

    return client
}

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é), vous devez disposer au minimum du rôle RBAC Azure intégré Contributeur aux données Blob du stockage. Pour en savoir plus, consultez l’aide relative aux autorisations pour les opérations Copier Blob ou Abandonner la copie Blob.

À 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 de l’un des types suivants : un objet blob de blocs, un objet blob d’ajout, un objet blob de pages, un objet blob d’instantané ou une version d’objet 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 fournies par le module client de Stockage Azure pour Go pour 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 :

Copier un objet blob à partir d’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 (recommandé), une signature d’accès partagé (SAP) ou une clé de compte. Pour une opération alternative de copie synchrone, consultez Copier un objet blob depuis une URL d’objet source avec Go.

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 suppose que vous fournissez votre propre SAP. 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. Nous définissons également le niveau d’accès pour l’objet blob de destination sur Cool en utilisant le struct StartCopyFromURLOptions.

func copyFromSourceAsync(srcBlob *blockblob.Client, destBlob *blockblob.Client) {
    // Lease the source blob during copy to prevent other clients from modifying it
    blobLeaseClient, err := lease.NewBlobClient(srcBlob, nil)
    handleError(err)

    _, err = blobLeaseClient.AcquireLease(context.TODO(), int32(60), nil)
    handleError(err)

    // Retrieve the SAS token for the source blob and append it to the URL
    sas := "<sas-token>"
    url := srcBlob.URL() + "?" + sas

    // Set copy options
    copyOptions := blob.StartCopyFromURLOptions{
        Tier: to.Ptr(blob.AccessTierCool),
    }

    // Copy the blob from the source URL to the destination blob
    startCopy, err := destBlob.StartCopyFromURL(context.TODO(), url, &copyOptions)
    handleError(err)

    // If startCopy.CopyStatus returns a status of "pending", the operation has started asynchronously
    // You can optionally add logic to poll the copy status and wait for the operation to complete
    // Example:
    copyStatus := *startCopy.CopyStatus
    for copyStatus == blob.CopyStatusTypePending {
        time.Sleep(time.Second * 2)

        properties, err := destBlob.GetProperties(context.TODO(), nil)
        handleError(err)

        copyStatus = *properties.CopyStatus
    }

    // Release the lease on the source blob
    _, err = blobLeaseClient.ReleaseLease(context.TODO(), nil)
    handleError(err)
}

L’exemple suivant montre un exemple d’utilisation :

// TODO: replace <storage-account-name> placeholders with actual storage account names
srcURL := "https://<src-storage-account-name>.blob.core.windows.net/"
destURL := "https://<dest-storage-account-name>.blob.core.windows.net/"

credential, err := azidentity.NewDefaultAzureCredential(nil)
handleError(err)

srcClient, err := azblob.NewClient(srcURL, credential, nil)
handleError(err)
destClient, err := azblob.NewClient(destURL, credential, nil)
handleError(err)

srcBlob := srcClient.ServiceClient().NewContainerClient("source-container").NewBlockBlobClient("source-blob")
destBlob := destClient.ServiceClient().NewContainerClient("destination-container").NewBlockBlobClient("destination-blob-1")

copyFromSourceAsync(srcBlob, destBlob)

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 objet blob depuis une URL d’objet source accessible :

func copyFromExternalSourceAsync(srcURL string, destBlob *blockblob.Client) {
    // Set copy options
    copyOptions := blob.StartCopyFromURLOptions{
        Tier: to.Ptr(blob.AccessTierCool),
    }

    // Copy the blob from the source URL to the destination blob
    startCopy, err := destBlob.StartCopyFromURL(context.TODO(), srcURL, &copyOptions)
    handleError(err)

    // If startCopy.CopyStatus returns a status of "pending", the operation has started asynchronously
    // You can optionally add logic to poll the copy status and wait for the operation to complete
    // Example:
    copyStatus := *startCopy.CopyStatus
    for copyStatus == blob.CopyStatusTypePending {
        time.Sleep(time.Second * 2)

        properties, err := destBlob.GetProperties(context.TODO(), nil)
        handleError(err)

        copyStatus = *properties.CopyStatus
    }
}

L’exemple suivant montre un exemple d’utilisation :

externalURL := "<source-url>"

destBlob = destClient.ServiceClient().NewContainerClient("destination-container").NewBlockBlobClient("destination-blob-2")

copyFromExternalSourceAsync(externalURL, destBlob)

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 GetProperties et vérifier l’état de la copie.

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

func checkCopyStatus(destBlob *blockblob.Client) {
    // Retrieve the properties from the destination blob
    properties, err := destBlob.GetProperties(context.TODO(), nil)
    handleError(err)

    copyID := *properties.CopyID
    copyStatus := *properties.CopyStatus

    fmt.Printf("Copy operation %s is %s\n", copyID, copyStatus)
}

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 :

func abortCopy(destBlob *blockblob.Client) {
    // Retrieve the copy ID from the destination blob
    properties, err := destBlob.GetProperties(context.TODO(), nil)
    handleError(err)

    copyID := *properties.CopyID
    copyStatus := *properties.CopyStatus

    // Abort the copy operation if it's still pending
    if copyStatus == blob.CopyStatusTypePending {
        _, err := destBlob.AbortCopyFromURL(context.TODO(), copyID, nil)
        handleError(err)

        fmt.Printf("Copy operation %s aborted\n", copyID)
    }
}

Ressources

Pour en savoir plus sur la copie d’objets blob avec une planification asynchrone en utilisant le module client Stockage Blob Azure pour Go, consultez les ressources qui suivent.

Exemples de code

Opérations de l'API REST

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

Ressources du module client