Copia de un blob con programación asincrónica mediante .NET
En este artículo se muestra cómo copiar un blob con programación asincrónica mediante la biblioteca cliente de Azure Storage para .NET. 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 desea mover datos a una cuenta de almacenamiento y tener una dirección URL para el objeto de origen, consulte Copia de un blob desde una dirección URL de objeto de origen con .NET.
Requisitos previos
- En este artículo se supone que ya tiene un proyecto configurado para trabajar con la biblioteca cliente de Azure Blob Storage para .NET. Para obtener información sobre cómo configurar el proyecto, incluida la instalación de paquetes, la adición de directivas de
usingy la autorización de un objeto de cliente, consulte Introducción a Azure Storage y Java. - 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.
Copia de 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 .NET 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:
Los métodos StartCopyFromUri y StartCopyFromUriAsync devuelven un objeto CopyFromUriOperation que contiene información sobre la operación de copia. Estos métodos se usan cuando se desea una programación asincrónica para una operación de 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 .NET.
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.
//-------------------------------------------------
// 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();
}
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.
//-------------------------------------------------
// 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();
}
Comprobación del estado de una operación de copia
Para comprobar el estado de una operación Copy Blob, puede llamar a UpdateStatusAsync y analizar la respuesta para obtener el valor del encabezado x-ms-copy-status.
En el ejemplo de código siguiente se muestra cómo comprobar el estado de una operación de copia:
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}");
}
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 una de las siguientes operaciones:
Estos métodos encapsulan la operación de la API de RESTAnular copia de blob, que cancela una operación Copy Blob pendiente. En el ejemplo de código siguiente se muestra cómo anular una operación Copy Blob pendiente:
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");
}
}
}
Recursos
Para obtener más información sobre cómo descargar blobs usando la biblioteca cliente de Azure Blob Storage para .NET, consulte los recursos siguientes.
Operaciones de API REST
El SDK de Azure para .NET 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 .NET. Los métodos de biblioteca cliente descritos en este artículo usan las siguientes operaciones de la API de REST:
- Blob de copia (API de REST)
- Anular blob de copia (API de REST)