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

  • Article

Cet article explique comment copier un blob avec une planification asynchrone à l’aide de la bibliothèque de client Stockage Azure pour Java. 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 Java.

Prérequis

Paramétrer votre environnement

Si vous n’avez pas de projet existant, cette section vous montre comment configurer un projet pour qu’il fonctionne avec la bibliothèque de client Stockage Blob Azure pour Java. Pour plus d’informations, consultez Bien démarrer avec Stockage Blob Azure et Java.

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

Remarque

Cet article utilise l’outil de génération Maven pour générer et exécuter l’exemple de code. D’autres outils de génération, comme Gradle, fonctionnent également avec le Kit de développement logiciel (SDK) Azure pour Java.

Installer des packages

Ouvrez le fichier pom.xml dans votre éditeur de texte. Installez les packages en incluant le fichier de marque d’ordre d’octet ou en incluant une dépendance directe.

Ajouter des instructions import

Ajoutez les instructions import suivantes :

import com.azure.core.util.polling.*;
import com.azure.storage.blob.*;
import com.azure.storage.blob.models.*;
import com.azure.storage.blob.options.*;
import com.azure.storage.blob.sas.BlobSasPermission;
import com.azure.storage.blob.sas.BlobServiceSasSignatureValues;
import com.azure.storage.blob.specialized.*;

import java.time.*;
import java.util.*;

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 utilise BlobServiceClientBuilder pour générer un objet BlobServiceClient en utilisant DefaultAzureCredential, et montre comment créer si nécessaire des clients de conteneur et de blob :

// Azure SDK client builders accept the credential as a parameter
// TODO: Replace <storage-account-name> with your actual storage account name
BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
        .endpoint("https://<storage-account-name>.blob.core.windows.net/")
        .credential(new DefaultAzureCredentialBuilder().build())
        .buildClient();

// If needed, you can create a BlobContainerClient object from the BlobServiceClient
BlobContainerClient containerClient = blobServiceClient
        .getBlobContainerClient("<container-name>");

// If needed, you can create a BlobClient object from the BlobContainerClient
BlobClient blobClient = containerClient
        .getBlobClient("<blob-name>");

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

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 Java afin d’effectuer une opération de copie avec une planification asynchrone.

La méthode suivante inclut l’opération d’API REST Copier un blob dans un wrapper et commence une copie asynchrone des données à partir du blob source :

La méthode beginCopy retourne un SyncPoller pour interroger la progression de l’opération de copie. Le type de réponse à l’interrogation est BlobCopyInfo. La méthode beginCopy est utilisée lorsque vous souhaitez planifier une opération de copie 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é (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 Java.

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.

public void copyBlobAcrossStorageAccounts(BlobClient sourceBlob, BlockBlobClient destinationBlob) {
    // Lease the source blob during copy to prevent other clients from modifying it
    BlobLeaseClient lease = new BlobLeaseClientBuilder()
            .blobClient(sourceBlob)
            .buildClient();

    // Create a SAS token for the source blob or use an existing one
    String sasToken = generateUserDelegationSAS(
            sourceBlob.getContainerClient().getServiceClient(),
            sourceBlob);

    // Get the source blob URL and append the SAS token
    String sourceBlobSasURL = sourceBlob.getBlobUrl() + "?" + sasToken;

    try {
        // Specifying -1 creates an infinite lease
        lease.acquireLease(-1);

        // Start the copy operation and wait for it to complete
        final SyncPoller<BlobCopyInfo, Void> poller = destinationBlob.beginCopy(
                sourceBlobSasURL,
                Duration.ofSeconds(2));
        PollResponse<BlobCopyInfo> response = poller.waitUntil(LongRunningOperationStatus.SUCCESSFULLY_COMPLETED);
    } finally {
        // Release the lease once the copy operation completes
        lease.releaseLease();
    }
}

public String generateUserDelegationSAS(BlobServiceClient blobServiceClient, BlobClient sourceBlob) {
    // Get a user delegation key
    OffsetDateTime delegationKeyStartTime = OffsetDateTime.now();
    OffsetDateTime delegationKeyExpiryTime = OffsetDateTime.now().plusDays(1);
    UserDelegationKey key = blobServiceClient.getUserDelegationKey(
        delegationKeyStartTime,
        delegationKeyExpiryTime);

    // Create a SAS token that's valid for one day, as an example
    OffsetDateTime expiryTime = OffsetDateTime.now().plusDays(1);

    // Set the Read (r) permission on the SAS token
    BlobSasPermission permission = new BlobSasPermission().setReadPermission(true);

    BlobServiceSasSignatureValues sasValues = new BlobServiceSasSignatureValues(expiryTime, permission)
            .setStartTime(OffsetDateTime.now());

    // Create a SAS token that's valid for one day
    String sasToken = sourceBlob.generateUserDelegationSas(sasValues, key);

    return sasToken;
}

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.

public void copyFromExternalSourceAsyncScheduling(String sourceURL, BlockBlobClient destinationBlob) {
    // Start the copy operation and wait for it to complete
    final SyncPoller<BlobCopyInfo, Void> poller = destinationBlob.beginCopy(
            sourceURL,
            Duration.ofSeconds(2));
    PollResponse<BlobCopyInfo> response = poller.waitUntil(LongRunningOperationStatus.SUCCESSFULLY_COMPLETED);
}

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

Pour vérifier l’état d’une opération Copy Blob, vous pouvez appeler getCopyStatus sur l’objet BlobCopyInfo retourné par SyncPoller.

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

public void checkCopyStatus(BlobCopyInfo copyInfo) {
    // Check the status of the copy operation 
    System.out.printf("Copy status", copyInfo.getCopyStatus());
}

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 la méthode 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 :

public void abortCopy(BlobCopyInfo copyInfo, BlobClient destinationBlob) {
    // Check the copy status and abort if pending
    if (copyInfo.getCopyStatus() == CopyStatusType.PENDING) {
        destinationBlob.abortCopyFromUrl(copyInfo.getCopyId());
        System.out.printf("Copy operation %s has been aborted%n", copyInfo.getCopyId());
    }
}

Ressources

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

Exemples de code

Opérations de l'API REST

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