Copiare un BLOB con pianificazione asincrona usando JavaScript o TypeScript

Questo articolo illustra come copiare un BLOB con pianificazione asincrona usando la libreria client di Archiviazione di Azure per JavaScript. È possibile copiare un BLOB da un'origine all'interno dello stesso account di archiviazione, da un'origine in un account di archiviazione diverso o da qualsiasi oggetto accessibile recuperato tramite una richiesta HTTP GET in un determinato URL. È anche possibile interrompere un'operazione di copia in sospeso.

I metodi della libreria client illustrati in questo articolo usano l'operazione API REST Copia BLOB e possono essere usati quando si vuole eseguire una copia con pianificazione asincrona. Per la maggior parte degli scenari di copia in cui si desidera spostare i dati in un account di archiviazione e avere un URL per l'oggetto di origine, vedere Copiare un BLOB da un URL dell'oggetto di origine con JavaScript.

Prerequisiti

• Gli esempi in questo articolo presuppongono che sia già stato configurato un progetto per l'uso con la libreria client di Archiviazione BLOB di Azure per JavaScript. Per informazioni sulla configurazione del progetto, incluse l'installazione del pacchetto, l'importazione di moduli e la creazione di un oggetto client autorizzato per l'uso con le risorse dati, consultare Introduzione ad Archivio BLOB di Azure e JavaScript.
• Il meccanismo di autorizzazione deve disporre delle autorizzazioni per eseguire un'operazione di copia o per interrompere una copia in sospeso. Per altre informazioni, vedere le linee guida per l'autorizzazione per l'operazione API REST seguente:
  • Copy Blob
  • Abort Copy Blob

Informazioni sulla copia di BLOB con pianificazione asincrona

L'operazione Copy Blob può terminare in modo asincrono e viene eseguita secondo il criterio del massimo sforzo, il che significa che non sono garantiti l'avvio immediato dell'operazione o il completamento entro un intervallo di tempo specificato. L'operazione di copia viene pianificata in background ed eseguita non appena il server ha risorse disponibili. L'operazione può essere completata in modo sincrono se la copia avviene all'interno dello stesso account di archiviazione.

Un'operazione Copy Blob può eseguire una delle azioni seguenti:

• Copiare un BLOB di origine in un BLOB di destinazione con un nome diverso. Il BLOB di destinazione può essere un BLOB esistente dello stesso tipo (BLOB in blocchi, di accodamento o di pagine) oppure può trattarsi di un nuovo BLOB creato dall'operazione di copia.
• Copiare un BLOB di origine in un BLOB di destinazione con lo stesso nome, sostituendo così il BLOB di destinazione. Questo tipo di operazione di copia rimuove i blocchi non sottoposti a commit e sovrascrive i metadati del BLOB di destinazione.
• Copiare un file di origine nel servizio file di Azure in un BLOB di destinazione. Il BLOB di destinazione può essere un BLOB in blocchi esistente o può trattarsi di un nuovo BLOB in blocchi creato dall'operazione di copia. La copia da file a BLOB di pagine o BLOB di accodamento non è supportata.
• Copiare uno snapshot sul relativo BLOB di base. Promuovendo uno snapshot alla posizione del BLOB di base, è possibile ripristinare la versione precedente di un BLOB.
• Copiare uno snapshot in un BLOB di destinazione con un nome diverso. Il BLOB di destinazione risultante è un BLOB scrivibile, non uno snapshot.

Per altre informazioni sull'operazione Copy Blob, incluse le informazioni sulle proprietà, i tag di indice, i metadati e la fatturazione, vedere le osservazioni sull'operazione Copy Blob.

Copiare un BLOB con pianificazione asincrona

Questa sezione offre una panoramica dei metodi forniti dalla libreria client di Archiviazione di Azure per JavaScript per eseguire un'operazione di copia con pianificazione asincrona.

I metodi seguenti eseguono il wrapping dell'operazione API REST Copia BLOB e avviano una copia asincrona dei dati dal BLOB di origine:

• BlobClient.beginCopyFromURL

Il metodo beginCopyFromURL restituisce un poller dell'operazione a esecuzione prolungata che consente di attendere a tempo indeterminato fino al completamento della copia.

Copiare un BLOB da un'origine in Azure

Se si copia un BLOB all'interno dello stesso account di archiviazione, l'operazione può essere completata in modo sincrono. L'accesso al BLOB di origine può essere autorizzato tramite Microsoft Entra ID, una firma di accesso condiviso (SAS) o una chiave dell'account. Per un'operazione di copia sincrona alterative, vedere Copiare un BLOB da un URL dell'oggetto di origine con JavaScript.

Se l'origine di copia è un BLOB in un account di archiviazione diverso, l'operazione può essere completata in modo asincrono. Il BLOB di origine deve essere pubblico o autorizzato tramite token di firma di accesso condiviso. Il token di firma di accesso condiviso deve includere l'autorizzazione di lettura ('r'). Per altre informazioni sui token di firma di accesso condiviso, vedere Delegare l'accesso con firme di accesso condiviso.

L'esempio seguente illustra uno scenario per la copia di un BLOB di origine da un account di archiviazione diverso con pianificazione asincrona. In questo esempio viene creato un URL del BLOB di origine con un token di firma di accesso condiviso di delega utente aggiunto. L'esempio mostra come generare il token di firma di accesso condiviso usando la libreria client, ma è anche possibile specificare il proprio. L'esempio mostra anche come creare un lease sul BLOB di origine durante l'operazione di copia per impedire modifiche al BLOB da un client diverso. L'operazione Copy Blob salva il valore ETag del BLOB di origine all'avvio dell'operazione di copia. Se il valore ETag viene modificato prima del completamento dell'operazione di copia, l'operazione non riesce.

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

Copiare un BLOB da un'origine all'esterno di Azure

È possibile eseguire un'operazione di copia su qualsiasi oggetto di origine recuperabile tramite una richiesta HTTP GET in un determinato URL, inclusi gli oggetti accessibili all'esterno di Azure. L'esempio seguente illustra uno scenario per la copia di un BLOB da un URL dell'oggetto di origine accessibile.

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

Controllare lo stato di un'operazione di copia

Per controllare lo stato di un'operazione Copy Blob asincrona, è possibile eseguire il polling del metodo getProperties e controllare lo stato della copia.

Nell'esempio di codice seguente viene illustrato come controllare lo stato di un'operazione di copia in sospeso:

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

Interrompere un'operazione di copia

L'interruzione di un'operazione Copy Blob in sospeso produce un BLOB di destinazione di lunghezza zero. Per i metadati del BLOB di destinazione, tuttavia, i nuovi valori verranno copiati dal BLOB di origine o impostati in modo esplicito durante l'operazione di copia. Per mantenere i metadati originali prima della copia, creare uno snapshot del BLOB di destinazione prima di chiamare uno dei metodi di copia.

Per interrompere un'operazione di copia in sospeso, chiamare l'operazione seguente:

• BlobClient.abortCopyFromURL

Questo metodo esegue il wrapping dell'operazione API REST Interrompi copia BLOB, che annulla un'operazione Copy Blob in sospeso. L'esempio di codice seguente illustra come interrompere un'operazione Copy Blob in sospeso:

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

Risorse

Per altre informazioni sulla copia di BLOB con la pianificazione asincrona tramite la libreria client di Archivio BLOB di Azure per JavaScript, vedere le risorse seguenti.

Esempi di codice

• Visualizzare esempi di codice JavaScript e TypeScript di questo articolo (GitHub)

Operazioni dell'API REST

Azure SDK per JavaScript contiene librerie basate sull'API REST di Azure che consentono di interagire con le operazioni dell'API REST tramite paradigmi noti di JavaScript. I metodi della libreria client illustrati in questo articolo usano le operazioni API REST seguenti:

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

Risorse della libreria client

• Documentazione di riferimento della libreria client
• Codice sorgente della libreria client
• Pacchetto (npm)

Contenuto correlato

• Questo articolo fa parte della guida per sviluppatori di Archiviazione BLOB per JavaScript/TypeScript. Per altre informazioni, vedere l'elenco completo degli articoli della guida per sviluppatori in Creare l'app JavaScript/TypeScript.