Compartir vía

Copia de un blob con programación asincrónica mediante JavaScript o TypeScript

  • Artículo

En este artículo, se muestra cómo copiar un blob con programación asincrónica mediante la biblioteca cliente de Azure Storage para JavaScript. Puede copiar un blob desde un origen dentro de la misma cuenta de almacenamiento, desde un origen en una cuenta de almacenamiento diferente o desde cualquier objeto accesible recuperado a través de una solicitud HTTP GET en una dirección URL determinada. También puede anular una operación de copia pendiente.

Los métodos de la biblioteca cliente descritos en este artículo usan la operación de la API de REST Copiar blob y se pueden usar cuando desee realizar una copia con programación asincrónica. Para la mayoría de los escenarios de copia en los que desee mover datos a una cuenta de almacenamiento y tener una dirección URL para el objeto de origen, consulte Copiar un blob desde una dirección URL de objeto de origen con JavaScript.

Requisitos previos

  • Los ejemplos de este artículo asumen que ya tiene un proyecto configurado para trabajar con la librería cliente Azure Blob Storage para JavaScript. Para obtener más información sobre la configuración del proyecto, incluida la instalación de paquetes, la importación de módulos y la creación de un objeto cliente autorizado para trabajar con recursos de datos, consulte Introducción a Azure Blob Storage y JavaScript.
  • El mecanismo de autorización debe tener permisos para realizar una operación de copia, o para abortar una copia pendiente. Para obtener más información, consulte la guía de autorización para la siguiente operación de la API de REST:

Acerca de la copia de blobs con programación asincrónica

La operación Copy Blob puede finalizar de forma asincrónica y se realiza en función del mejor esfuerzo, lo que significa que no se garantiza que la operación se inicie inmediatamente o se complete dentro de un período de tiempo especificado. La operación de copia se programa en segundo plano y se realiza cuando el servidor tiene recursos disponibles. La operación se puede completar sincrónicamente si la copia se produce dentro de la misma cuenta de almacenamiento.

Una operación Copy Blob puede realizar cualquiera de las siguientes acciones:

  • Copie un blob de origen en un blob de destino con un nombre diferente. El blob de destino puede ser un blob existente del mismo tipo de blob (en bloques, anexos o en páginas), o puede ser un nuevo blob creado por la operación de copia.
  • Copie un blob de origen en un blob de destino con el mismo nombre, lo que reemplaza el blob de destino. Este tipo de operación de copia quita los bloques sin confirmar y sobrescribe los metadatos del blob de destino.
  • Copie un archivo de origen del servicio Azure File en un blob de destino. El blob de destino puede ser un blob en bloques existente o un nuevo blob de ese tipo creado por la operación de copia. No se admite la copia de archivos a blobs en páginas o blobs en anexos.
  • Copie una instantánea sobre su blob base. Si se mueve una instantánea a la posición del blob, puede restaurar una versión anterior de un blob.
  • Copie una instantánea en un blob de destino con otro nombre. El blob resultante de destino es un blob en el que se puede escribir y no una instantánea.

Para obtener más información sobre la operación Copy Blob, incluida la información sobre las propiedades, las etiquetas de índice, los metadatos y la facturación, consulte Comentarios sobre la copia de blobs.

Copiar un blob con programación asincrónica

En esta sección, se proporciona información general sobre los métodos proporcionados por la biblioteca cliente de Azure Storage para JavaScript para realizar una operación de copia con programación asincrónica.

Los métodos siguientes encapsulan la operación de la API de REST Copiar blob y comienzan una copia asincrónica de los datos del blob de origen:

El método beginCopyFromURL devuelve un sondeo de operación de larga duración que permite esperar indefinidamente hasta que se complete la copia.

Copiar un blob desde un origen dentro de Azure

Si va a copiar un blob dentro de la misma cuenta de almacenamiento, la operación se puede completar de forma sincrónica. El acceso al blob de origen se puede autorizar mediante Microsoft Entra ID, una firma de acceso compartido (SAS) o una clave de cuenta. Para obtener una operación de copia sincrónica alterativa, consulte Copiar un blob desde una dirección URL de objeto de origen con JavaScript.

Si el origen de copia es un blob en otra cuenta de almacenamiento, la operación se puede completar de forma asincrónica. El blob de origen debe ser público o autorizado a través del token de SAS. El token de SAS debe incluir el permiso Lectura (“r”). Para más información sobre los tokens de SAS, consulte Delegación del acceso con firmas de acceso compartido.

En el ejemplo siguiente se muestra un escenario para copiar un blob de origen desde otra cuenta de almacenamiento con programación asincrónica. En este ejemplo, se crea una dirección URL de blob de origen con un token de SAS de delegación de usuarios anexado. En el ejemplo se muestra cómo generar el token de SAS mediante la biblioteca cliente, aunque también puede proporcionar el suyo propio. En este ejemplo también se muestra cómo conceder el blob de origen durante la operación de copia para evitar cambios en el blob desde un cliente diferente. La operación Copy Blob guarda el valor ETag del blob de origen cuando se inicia la operación de copia. Si el valor ETag se cambia antes de que finalice la operación de copia, se produce un error en la operación.

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();
}

Nota:

Los tokens de SAS de delegación de usuarios ofrecen mayor seguridad, ya que se firman con credenciales de Microsoft Entra en lugar de con una clave de cuenta. Para crear un token de SAS de delegación de usuarios, la entidad de seguridad de Microsoft Entra necesita los permisos adecuados. Para conocer los requisitos de autorización, consulte Obtención de la clave de delegación de usuarios.

Copiar un blob desde un origen externo a Azure

Puede realizar una operación de copia en cualquier objeto de origen que se pueda recuperar a través de solicitudes HTTP GET en una dirección URL determinada, incluyendo los objetos accesibles de fuera de Azure. En el ejemplo siguiente se muestra un escenario para copiar un blob desde una dirección URL de objeto de origen accesible.

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

Comprobación del estado de una operación de copia

Para comprobar el estado de una operación asincrónica de Copy Blob, puede sondear el método getProperties y comprobar el estado de la copia.

El siguiente ejemplo de código muestra cómo comprobar el estado de una operación de copia pendiente:

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

Anulación de una operación de copia

La anulación de una operación Copy Blob pendiente da como resultado un blob de destino de longitud cero. Sin embargo, los nuevos valores de los metadatos del blob de destino se copian del blob de origen o se establecen explícitamente durante la operación de copia. Para conservar los metadatos originales anteriores a la copia, cree una instantánea del blob de destino antes de llamar a uno de los métodos de copia.

Para anular una operación de copia pendiente, llame a la siguiente operación:

Estos métodos encapsulan la operación de la API de RESTAnular copia de blob, que cancela una operación Copy Blob pendiente. El siguiente ejemplo de código muestra cómo anular una operación Copy Blob pendiente:

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);
  }
}

Recursos

Para obtener más información sobre cómo descargar blobs con programación asincrónica usando la biblioteca cliente de Azure Blob Storage para JavaScript, consulte los recursos siguientes.

Ejemplos de código

Operaciones de API REST

El SDK de Azure para JavaScript contiene bibliotecas que se crean a partir de la API REST de Azure, lo que le permite interactuar con las operaciones de API REST a través de paradigmas conocidos de JavaScript. Los métodos de biblioteca cliente descritos en este artículo usan las siguientes operaciones de la API de REST:

Recursos de la biblioteca cliente

Contenido relacionado

  • Este artículo forma parte de la guía para desarrolladores de Blob Storage para JavaScript/TypeScript. Para obtener más información, consulte la lista completa de artículos de la guía para desarrolladores en Compilación de la aplicación JavaScript/TypeScript.