Partager via

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

  • Article

Cet article explique comment copier un blob avec la planification asynchrone à l’aide de la Bibliothèque de client Stockage Azure pour .NET. 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 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. 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 blob à partir d’une URL d’objet source avec .NET.

Prérequis

Paramétrer votre environnement

Si vous n’avez pas de projet existant, cette section vous montre comment configurer un projet pour travailler avec la bibliothèque de client Stockage Blob Azure pour .NET. Les étapes comprennent l’installation du package, l’ajout de directives using et la création d’un objet client autorisé. Pour plus d’informations, consultez Prise en main du Stockage Blob Azure et de .NET.

Installer des packages

À partir du répertoire du projet, installez les packages des bibliothèques de client Stockage Blob Azure et Azure Identity à l’aide de la commande dotnet add package. Le package Azure.Identity est nécessaire pour les connexions sans mot de passe aux services Azure.

dotnet add package Azure.Storage.Blobs
dotnet add package Azure.Identity

Ajoutez des directives using.

Ajoutez ces directives using au début de votre fichier de code :

using Azure.Identity;
using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
using Azure.Storage.Blobs.Specialized;

Certains exemples de code de cet article peuvent nécessiter des directives using supplémentaires.

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 :

public BlobServiceClient GetBlobServiceClient(string accountName)
{
    BlobServiceClient client = new(
        new Uri($"https://{accountName}.blob.core.windows.net"),
        new DefaultAzureCredential());

    return client;
}

Vous pouvez inscrire un client de service pour l’injection de dépendances dans une application .NET.

Vous pouvez également créer des objets clients pour des conteneurs ou des objets blob spécifiques. 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.

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

À 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é.

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 la bibliothèque de client de Stockage Azure pour .NET 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 :

Les méthodes StartCopyFromUri et StartCopyFromUriAsync retournent un objet CopyFromUriOperation contenant des informations sur l’opération de copie. Ces méthodes sont utilisées lorsque vous souhaitez planifier une opération de copie de manière asynchrone.

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 à l’objet blob source peut être autorisé via Microsoft Entra ID, une signature d’accès partagé (SAP) 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 .NET.

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.

//-------------------------------------------------
// Copy a blob from a different storage account
//-------------------------------------------------
public static async Task CopyAcrossStorageAccountsAsync(
    BlobClient sourceBlob,
    BlockBlobClient destinationBlob)
{
    // Lease the source blob to prevent changes during the copy operation
    BlobLeaseClient sourceBlobLease = new(sourceBlob);

    // Create a Uri object with a SAS token appended - specify Read (r) permissions
    Uri sourceBlobSASURI = await GenerateUserDelegationSAS(sourceBlob);

    try
    {
        await sourceBlobLease.AcquireAsync(BlobLeaseClient.InfiniteLeaseDuration);

        // Start the copy operation and wait for it to complete
        CopyFromUriOperation copyOperation = await destinationBlob.StartCopyFromUriAsync(sourceBlobSASURI);
        await copyOperation.WaitForCompletionAsync();
    }
    catch (RequestFailedException ex)
    {
        // Handle the exception
    }
    finally
    {
        // Release the lease once the copy operation completes
        await sourceBlobLease.ReleaseAsync();
    }
}

async static Task<Uri> GenerateUserDelegationSAS(BlobClient sourceBlob)
{
    BlobServiceClient blobServiceClient =
        sourceBlob.GetParentBlobContainerClient().GetParentBlobServiceClient();

    // Get a user delegation key for the Blob service that's valid for 1 day
    UserDelegationKey userDelegationKey =
        await blobServiceClient.GetUserDelegationKeyAsync(DateTimeOffset.UtcNow,
                                                          DateTimeOffset.UtcNow.AddDays(1));

    // Create a SAS token that's also valid for 1 day
    BlobSasBuilder sasBuilder = new BlobSasBuilder()
    {
        BlobContainerName = sourceBlob.BlobContainerName,
        BlobName = sourceBlob.Name,
        Resource = "b",
        StartsOn = DateTimeOffset.UtcNow,
        ExpiresOn = DateTimeOffset.UtcNow.AddDays(1)
    };

    // Specify read permissions for the SAS
    sasBuilder.SetPermissions(BlobSasPermissions.Read);

    // Add the SAS token to the blob URI
    BlobUriBuilder blobUriBuilder = new BlobUriBuilder(sourceBlob.Uri)
    {
        // Specify the user delegation key
        Sas = sasBuilder.ToSasQueryParameters(userDelegationKey,
                                              blobServiceClient.AccountName)
    };

    return blobUriBuilder.ToUri();
}

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.

//-------------------------------------------------
// Copy a blob from an external source
//-------------------------------------------------
public static async Task CopyFromExternalSourceAsync(
    string sourceLocation,
    BlockBlobClient destinationBlob)
{
    Uri sourceUri = new(sourceLocation);

    // Start the copy operation and wait for it to complete
    CopyFromUriOperation copyOperation = await destinationBlob.StartCopyFromUriAsync(sourceUri);
    await copyOperation.WaitForCompletionAsync();
}

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

Pour vérifier l’état d’une opération Copy Blob, vous pouvez appeler UpdateStatusAsync et analyser la réponse pour obtenir la valeur de l’en-tête x-ms-copy-status.

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

public static async Task CheckCopyStatusAsync(CopyFromUriOperation copyOperation)
{
    // Check for the latest status of the copy operation
    Response response = await copyOperation.UpdateStatusAsync();

    // Parse the response to find x-ms-copy-status header
    if (response.Headers.TryGetValue("x-ms-copy-status", out string value))
        Console.WriteLine($"Copy status: {value}");
}

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’une des opérations suivantes :

Ces méthodes encapsulent l’opération d’API REST Abort Copy Blob, 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 :

public static async Task AbortBlobCopyAsync(
    CopyFromUriOperation copyOperation,
    BlobClient destinationBlob)
{
    // Check for the latest status of the copy operation
    Response response = await copyOperation.UpdateStatusAsync();

    // Parse the response to find x-ms-copy-status header
    if (response.Headers.TryGetValue("x-ms-copy-status", out string value))
    {
        if (value == "pending")
        {
            await destinationBlob.AbortCopyFromUriAsync(copyOperation.Id);
            Console.WriteLine($"Copy operation {copyOperation.Id} aborted");
        }
    }
}

Ressources

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

Exemples de code

Opérations de l'API REST

Le Kit de développement logiciel (SDK) Azure pour .NET 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 .NET 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 du développeur Stockage Blob pour .NET. Pour en savoir plus, consultez la liste complète des articles du guide du développeur dans Générer votre application .NET.