Copier un objet blob avec une planification asynchrone à l’aide de JavaScript ou De TypeScript

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

Prérequis

• Les exemples de cet article supposent que vous disposez déjà d'un projet configuré pour fonctionner avec la bibliothèque client Azure Blob Storage pour JavaScript. Pour en savoir plus sur la configuration de votre projet, y compris l'installation de packages, l'importation de modules et la création d'un objet client autorisé pour travailler avec des ressources de données, consultez Démarrer avec Stockage Blob Azure et JavaScript.
• Le mécanisme d’autorisation doit disposer des autorisations nécessaires pour effectuer une opération de copie ou pour abandonner une copie en attente. Pour en savoir plus, consultez les conseils d’autorisation pour l’opération d’API REST suivante :
  • Copy Blob
  • Abort Copy 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é.

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 JavaScript 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 :

• BlobClient.beginCopyFromURL

La méthode beginCopyFromURL retourne un observateur d’opération durable qui vous permet d’attendre indéfiniment jusqu’à ce que la copie soit terminée.

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

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.

async function copyAcrossStorageAccountsAsync(sourceBlob, destinationBlob, blobServiceClient) {
  
  // Lease the source blob to prevent changes during the copy operation
  const sourceBlobLease = new BlobLeaseClient(sourceBlob);

  // Create a SAS token that's valid for 1 hour
  const sasToken = await generateUserDelegationSAS(sourceBlob, blobServiceClient);
  const sourceBlobSASURL = sourceBlob.url + "?" + sasToken;

  try {
    await sourceBlobLease.acquireLease(-1);

    // Start the copy operation and wait for it to complete
    const copyPoller = await destinationBlob.beginCopyFromURL(sourceBlobSASURL);
    await copyPoller.pollUntilDone();
  } catch (error) {
    // Handle the exception
  } finally {
    // Release the lease once the copy operation completes
    await sourceBlobLease.releaseLease();
  }
}

async function generateUserDelegationSAS(sourceBlob, blobServiceClient) {
  
  // Get a user delegation key for the Blob service that's valid for 1 hour, as an example
  const delegationKeyStart = new Date();
  const delegationKeyExpiry = new Date(Date.now() + 3600000);
  const userDelegationKey = await blobServiceClient.getUserDelegationKey(
    delegationKeyStart,
    delegationKeyExpiry
  );

  // Create a SAS token that's valid for 1 hour, as an example
  const sasTokenStart = new Date();
  const sasTokenExpiry = new Date(Date.now() + 3600000);
  const blobName = sourceBlob.name;
  const containerName = sourceBlob.containerName;
  const sasOptions = {
    blobName,
    containerName,
    permissions: BlobSASPermissions.parse("r"),
    startsOn: sasTokenStart,
    expiresOn: sasTokenExpiry,
    protocol: SASProtocol.HttpsAndHttp
  };

  const sasToken = generateBlobSASQueryParameters(
    sasOptions,
    userDelegationKey,
    blobServiceClient.accountName
  ).toString();

  return sasToken.toString();
}

async function copyAcrossStorageAccountsAsync(
  sourceBlob: BlockBlobClient,
  destinationBlob: BlockBlobClient,
  blobServiceClient: BlobServiceClient
): Promise<void> {
  const sourceBlobLease = new BlobLeaseClient(sourceBlob);

  // Create a SAS token that's valid for 1 hour
  const sasToken = await generateUserDelegationSAS(sourceBlob, blobServiceClient);
  const sourceBlobSASURL: string = sourceBlob.url + '?' + sasToken;

  try {
    await sourceBlobLease.acquireLease(-1);

    const copyPoller = await destinationBlob.beginCopyFromURL(sourceBlobSASURL);
    await copyPoller.pollUntilDone();
  } catch (error) {
    console.log(error);
  } finally {
    await sourceBlobLease.releaseLease();
  }
}

async function generateUserDelegationSAS(
  sourceBlob: BlockBlobClient,
  blobServiceClient: BlobServiceClient
): Promise<string> {
  // Get a user delegation key for the Blob service that's valid for 1 hour, as an example
  const delegationKeyStart = new Date();
  const delegationKeyExpiry = new Date(Date.now() + 3600000);
  const userDelegationKey = await blobServiceClient.getUserDelegationKey(
    delegationKeyStart,
    delegationKeyExpiry
  );

  // Create a SAS token that's valid for 1 hour, as an example
  const sasTokenStart = new Date();
  const sasTokenExpiry = new Date(Date.now() + 3600000);
  const blobName = sourceBlob.name;
  const containerName = sourceBlob.containerName;
  const sasOptions = {
    blobName,
    containerName,
    permissions: BlobSASPermissions.parse("r"),
    startsOn: sasTokenStart,
    expiresOn: sasTokenExpiry,
    protocol: SASProtocol.HttpsAndHttp
  };

  const sasToken = generateBlobSASQueryParameters(
    sasOptions,
    userDelegationKey,
    blobServiceClient.accountName
  ).toString();

  return sasToken.toString();
}

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.

async function copyFromExternalSource(sourceURL, destinationBlob) {
  
  const copyPoller = await destinationBlob.beginCopyFromURL(sourceURL);
  await copyPoller.pollUntilDone();
}

async function copyFromExternalSource(sourceURL: string,
  destinationBlob: BlockBlobClient
): Promise<void> {
  try {
    const copyPoller = await destinationBlob.beginCopyFromURL(sourceURL);
    await copyPoller.pollUntilDone();
  } catch (error) {
    console.log(error);
  }
}

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 d’une opération de copie en attente :

async function checkCopyStatus(destinationBlob) {
  
  const properties = await destinationBlob.getProperties();
  console.log(properties.copyStatus);
}

async function checkCopyStatus(destinationBlob: BlockBlobClient): Promise<void> {
  const properties = await destinationBlob.getProperties();
  console.log(properties.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 :

• BlobClient.abortCopyFromURL

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 :

async function abortCopy(destinationBlob) {
  
  const properties = await destinationBlob.getProperties();

  // Check the copy status and abort if pending
  if (properties.copyStatus === "pending") {
    await destinationBlob.abortCopyFromURL(properties.copyId);
  }
}

async function abortCopy(destinationBlob: BlockBlobClient): Promise<void> {
  const properties = await destinationBlob.getProperties();

  // Check the copy status and abort if pending
  if (properties.copyStatus === "pending") {
    await destinationBlob.abortCopyFromURL(properties.copyId?.toString()!);
  }
}

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 JavaScript, consultez les ressources suivantes.

Exemples de code

• Consultez des exemples de code JavaScript et TypeScript de cet article (GitHub)

Opérations de l'API REST

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

• Copy Blob (API REST)
• Abort Copy Blob (API REST)

Ressources de bibliothèque cliente

• Documentation de référence sur la bibliothèque cliente
• Code source de la bibliothèque de client
• Package (npm)

Contenu connexe

• Cet article fait partie du guide du développeur Stockage Blob pour JavaScript/Typescript. Pour en savoir plus, consultez la liste complète des articles du guide du développeur sur Générer votre application JavaScript/Typescript.