Kopieren eines Blobs mit asynchroner Planung mithilfe von JavaScript oder TypeScript

In diesem Artikel wird gezeigt, wie Sie ein Blob mit asynchroner Planung mithilfe der Azure Storage-Clientbibliothek für JavaScript kopieren. Sie können ein Blob aus einer Quelle innerhalb desselben Speicherkontos, aus einer Quelle in einem anderen Speicherkonto oder aus einem beliebigen zugänglichen Objekt kopieren, das über eine HTTP GET-Anforderung für eine bestimmte URL abgerufen wird. Sie können einen ausstehenden Kopiervorgang auch abbrechen.

Bei den in diesem Artikel behandelten Clientbibliotheksmethoden wird der REST-API-Vorgang Copy Blob verwendet, und sie können verwendet werden, wenn Sie einen Kopiervorgang mit asynchroner Planung ausführen möchten. Informationen zu den meisten Kopierszenarien, in denen Sie Daten in ein Speicherkonto verschieben möchten und eine URL für das Quellobjekt haben, finden Sie unter Kopieren eines Blobs über eine Quellobjekt-URL mit JavaScript.

Voraussetzungen

• Bei den Beispielen in diesem Artikel wird davon ausgegangen, dass Sie bereits ein Projekt eingerichtet haben, das mit der Azure Blob Storage Clientbibliothek für JavaScript arbeitet. Informationen zum Einrichten Ihres Projekts, einschließlich der Paketinstallation, dem Importieren von Modulen und dem Erstellen eines autorisierten Clientobjekts für die Verwendung mit Datenressourcen, finden Sie unter Erste Schritte mit Azure Blob Storage und JavaScript.
• Der Autorisierungsmechanismus muss über Berechtigungen zum Ausführen eines Kopiervorgangs oder zum Abbrechen einer ausstehenden Kopie verfügen. Weitere Informationen finden Sie im Autorisierungsleitfaden für die folgenden REST-API-Vorgänge:
  • Copy Blob
  • Abort Copy Blob

Informationen zum Kopieren von Blobs mit asynchroner Planung

Der Copy Blob-Vorgang kann asynchron abgeschlossen werden und wird auf Grundlage der besten Leistung ausgeführt, d. h., es wird nicht garantiert, dass der Vorgang sofort beginnt oder innerhalb eines bestimmten Zeitrahmens abgeschlossen wird. Der Kopiervorgang wird im Hintergrund geplant und ausgeführt, sobald der Server über verfügbare Ressourcen verfügt. Der Vorgang kann synchron abgeschlossen werden, wenn der Kopiervorgang innerhalb desselben Speicherkontos erfolgt.

Ein Vorgang vom Typ Copy Blob kann jede der folgenden Aktionen ausführen:

• Kopieren Sie ein Quellblob in ein Zielblob mit einem anderen Namen. Das Zielblob kann ein vorhandenes Blob desselben Blobtyps (Blockblob, Anfügeblob oder Seitenblob) sein, oder es kann sich um ein neues Blob handeln, das durch den Kopiervorgang erstellt wurde.
• Kopieren Sie ein Quellblob in ein Zielblob mit demselben Namen. Dadurch wird das Zielblob ersetzt. Diese Art von Kopiervorgang entfernt alle Blöcke ohne Commit und überschreibt die Metadaten des Zielblobs.
• Kopieren Sie eine Quelldatei im Azure-Dateidienst in ein Zielblob. Das Zielblob kann ein vorhandenes Blockblob oder ein neues Blockblob sein, das durch den Kopiervorgang erstellt wurde. Das Kopieren von Dateien in Seitenblobs oder Anfügeblobs wird nicht unterstützt.
• Kopieren Sie eine Momentaufnahme über das zugehörige Basis-Blob. Indem Sie eine Momentaufnahme zu einem Basis-Blob heraufstufen, können Sie eine frühere Version eines Blobs wiederherstellen.
• Kopieren Sie eine Momentaufnahme in ein Zielblob mit einem anderen Namen. Das resultierende Zielblob ist ein beschreibbares Blob und keine Momentaufnahme.

Weitere Informationen zum Copy Blob-Vorgang, einschließlich Informationen zu Eigenschaften, Indextags, Metadaten und Abrechnung, finden Sie unter Bemerkungen.

Kopieren eines Blobs mit asynchroner Planung

Dieser Abschnitt enthält einen Überblick über die von der Azure Storage-Clientbibliothek für JavaScript bereitgestellten Methoden zur Ausführung eines Kopiervorgangs mit asynchroner Planung.

Die folgenden Methoden umschließen den REST-API-Vorgang Copy Blob und starten einen asynchronen Kopiervorgang von Daten aus dem Quellblob:

• BlobClient.beginCopyFromURL

Die beginCopyFromURL-Methode gibt einen zeitintensiven Poller zurück, mit dem Sie unbegrenzt warten können, bis der Kopiervorgang abgeschlossen ist.

Kopieren eines Blobs aus einer Quelle in Azure

Wenn Sie ein Blob innerhalb desselben Speicherkontos kopieren, kann der Vorgang synchron abgeschlossen werden. Der Zugriff auf den Quellblob kann über Microsoft Entra ID, Shared Access Signature (SAS) oder einen Kontoschlüssel autorisiert werden. Informationen zu einem alternativen synchronen Kopiervorgang finden Sie unter Kopieren eines Blobs aus einer Quellobjekt-URL mit JavaScript.

Wenn die Kopierquelle ein Blob in einem anderen Speicherkonto ist, kann der Vorgang asynchron abgeschlossen werden. Der Quellblob muss entweder öffentlich oder über ein SAS-Token autorisiert sein. Das SAS-Token muss die Berechtigung zum Lesen (Read ('r')) enthalten. Weitere Informationen zu SAS-Token finden Sie unter Gewähren von eingeschränktem Zugriff auf Azure Storage-Ressourcen mithilfe von SAS (Shared Access Signature).

Das folgende Beispiel zeigt ein Szenario für das Kopieren eines Quellblob aus einem anderen Speicherkonto mit asynchroner Planung. In diesem Beispiel wird eine Quellblob-URL mit einem angehängten SAS-Token für die Benutzerdelegierung erstellt. Das Beispiel zeigt, wie das SAS-Token mit Hilfe der Client-Bibliothek erzeugt wird. Sie können aber auch Ihr eigenes Token bereitstellen. Das Beispiel zeigt auch, wie der Quellblob während des Kopiervorgangs geleast werden kann, um Änderungen am Blob durch einen anderen Client zu verhindern. Der Copy Blob-Vorgang speichert den ETag-Wert des Quellblobs, wenn der Kopiervorgang gestartet wird. Wenn der ETag-Wert geändert wird, bevor der Kopiervorgang abgeschlossen ist, ist der Vorgang nicht erfolgreich.

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

Kopieren eines Blobs aus einer Quelle außerhalb von Azure

Sie können einen Kopiervorgang für jedes Quellobjekt ausführen, das über eine HTTP GET-Anforderung für eine bestimmte URL abgerufen werden kann, einschließlich zugänglicher Objekte außerhalb von Azure. Das folgende Beispiel zeigt ein Szenario zum Kopieren eines Blobs über eine URL für zugängliche Quellobjekte.

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

Überprüfen des Status eines Kopiervorgangs

Um den Status eines asynchronen Copy Blob-Vorgangs zu überprüfen, können Sie die getProperties-Methode abfragen und den Status des Kopiervorgangs überprüfen.

Das folgende Codebeispiel zeigt, wie der Status eines ausstehenden Kopiervorgangs überprüft wird:

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

Abbrechen eines Kopiervorgangs

Ein Abbrechen eines ausstehenden Copy Blob-Vorgangs führt zu einem Zielblob der Länge null. Die Metadaten für das Zielblob weisen jedoch die neuen Werte auf, die aus dem Quellblob kopiert oder explizit während des Kopiervorgangs festgelegt wurden. Zur Beibehaltung der ursprünglichen, vor dem Kopiervorgang vorliegenden Metadaten erstellen Sie eine Momentaufnahme des Zielblobs, bevor Sie eine der Kopiermethoden aufrufen.

Rufen Sie zum Abbrechen eines ausstehenden Kopiervorgangs den folgenden Vorgang auf:

• BlobClient.abortCopyFromURL

Diese Methode umschließt den REST-API-Vorgang Abort Copy Blob, wodurch ein ausstehender Copy Blob-Vorgang abgebrochen wird. Das folgende Codebeispiel zeigt, wie ein ausstehender Copy Blob-Vorgang abgebrochen wird:

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

Ressourcen

Weitere Informationen zum Kopieren von Blobs mit asynchroner Planung mithilfe der Azure Blob Storage-Clientbibliothek für JavaScript finden Sie in den folgenden Ressourcen.

Codebeispiele

• Anzeigen von Codebeispielen für JavaScript und TypeScript aus diesem Artikel (GitHub)

REST-API-Vorgänge

Das Azure SDK für JavaScript enthält Bibliotheken, die auf der zugrunde liegenden Azure-REST-API basieren und ermöglicht Ihnen dadurch die Interaktion mit REST-API-Vorgängen über vertraute JavaScript-Paradigmen. Die Clientbibliotheksmethoden, die in diesem Artikel behandelt werden, verwenden die folgenden REST-API-Vorgänge:

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

Ressourcen zur Clientbibliothek

• Referenzdokumentation zur Clientbibliothek
• Quellcode der Clientbibliothek
• Paket (npm)

Zugehöriger Inhalt

• Dieser Artikel ist Teil des Blob Storage-Entwicklerleitfadens für JavaScript/Typescript. Weitere Informationen finden Sie in der vollständigen Liste der Entwicklerleitfadenartikel unter Erstellen Ihrer JavaScript/Typescript-App.