Teilen über

Kopieren eines Blobs mit asynchroner Planung mithilfe von Java

  • Artikel

In diesem Artikel wird gezeigt, wie Sie ein Blob mit asynchroner Planung mithilfe der Azure Storage-Clientbibliothek für Java 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 Java.

Voraussetzungen

Erstellen Ihrer Umgebung

Wenn Sie nicht über ein vorhandenes Projekt verfügen, wird in diesem Abschnitt gezeigt, wie Sie ein Projekt für die Arbeit mit der Azure Blob Storage-Clientbibliothek für Java einrichten. Weitere Informationen finden Sie unter Erste Schritte mit Azure Blob Storage mit Java.

Um die Codebeispiele in diesem Artikel zu verwenden, führen Sie die folgenden Schritte zum Einrichten Ihres Projekts aus.

Hinweis

In diesem Artikel wird das Maven-Buildtool verwendet, um den Beispielcode zu erstellen und auszuführen. Andere Buildtools (beispielsweise Gradle) können ebenfalls mit dem Azure SDK für Java verwendet werden.

Installieren von Paketen

Öffnen Sie die Datei pom.xml in Ihrem Text-Editor. Installieren Sie die Pakete durch Einbeziehen der BOM-Datei oder Einbeziehen einer direkten Abhängigkeit.

Hinzufügen von Importanweisungen

Fügen Sie die folgenden import -Anweisungen ein:

import com.azure.core.util.polling.*;
import com.azure.storage.blob.*;
import com.azure.storage.blob.models.*;
import com.azure.storage.blob.options.*;
import com.azure.storage.blob.sas.BlobSasPermission;
import com.azure.storage.blob.sas.BlobServiceSasSignatureValues;
import com.azure.storage.blob.specialized.*;

import java.time.*;
import java.util.*;

Autorisierung

Der Autorisierungsmechanismus muss über die benötigten Berechtigungen zum Ausführen eines Kopiervorgangs oder zum Abbrechen einer ausstehenden Kopie verfügen. Für die Autorisierung mit Microsoft Entra ID (empfohlen) variiert die integrierte Azure RBAC-Rolle mit den geringsten Berechtigungen je nach verschiedenen Faktoren. Weitere Informationen finden Sie im Autorisierungsleitfaden für Copy Blob (REST API) oder Abort Copy Blob (REST API).

Erstellen eines Clientobjekts

Um eine App mit Blob Storage zu verbinden, erstellen Sie eine Instanz von BlobServiceClient.

Im folgenden Beispiel wird BlobServiceClientBuilder verwendet, um ein BlobServiceClient-Objekt mithilfe von DefaultAzureCredential zu erstellen, und zeigt, wie Container- und Blob-Clients erstellt werden, falls erforderlich:

// Azure SDK client builders accept the credential as a parameter
// TODO: Replace <storage-account-name> with your actual storage account name
BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
        .endpoint("https://<storage-account-name>.blob.core.windows.net/")
        .credential(new DefaultAzureCredentialBuilder().build())
        .buildClient();

// If needed, you can create a BlobContainerClient object from the BlobServiceClient
BlobContainerClient containerClient = blobServiceClient
        .getBlobContainerClient("<container-name>");

// If needed, you can create a BlobClient object from the BlobContainerClient
BlobClient blobClient = containerClient
        .getBlobClient("<blob-name>");

Weitere Informationen zum Erstellen und Verwalten von Clientobjekten finden Sie unter Erstellen und Verwalten von Clientobjekten, die mit Datenressourcen interagieren.

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 Java bereitgestellten Methoden zur Ausführung eines Kopiervorgangs mit asynchroner Planung.

Die folgende Methode umschließt den REST-API-Vorgang Copy Blob und startet einen asynchronen Kopiervorgang von Daten aus dem Quellblob:

Die beginCopy-Methode gibt einen SyncPoller zurück, um den Fortschritt des Kopiervorgangs abzufragen. Der Antworttyp der Abfrage ist BlobCopyInfo. Die beginCopy-Methode wird verwendet, wenn Sie bei einem Kopiervorgang die asynchrone Planung verwenden möchten.

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

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.

public void copyBlobAcrossStorageAccounts(BlobClient sourceBlob, BlockBlobClient destinationBlob) {
    // Lease the source blob during copy to prevent other clients from modifying it
    BlobLeaseClient lease = new BlobLeaseClientBuilder()
            .blobClient(sourceBlob)
            .buildClient();

    // Create a SAS token for the source blob or use an existing one
    String sasToken = generateUserDelegationSAS(
            sourceBlob.getContainerClient().getServiceClient(),
            sourceBlob);

    // Get the source blob URL and append the SAS token
    String sourceBlobSasURL = sourceBlob.getBlobUrl() + "?" + sasToken;

    try {
        // Specifying -1 creates an infinite lease
        lease.acquireLease(-1);

        // Start the copy operation and wait for it to complete
        final SyncPoller<BlobCopyInfo, Void> poller = destinationBlob.beginCopy(
                sourceBlobSasURL,
                Duration.ofSeconds(2));
        PollResponse<BlobCopyInfo> response = poller.waitUntil(LongRunningOperationStatus.SUCCESSFULLY_COMPLETED);
    } finally {
        // Release the lease once the copy operation completes
        lease.releaseLease();
    }
}

public String generateUserDelegationSAS(BlobServiceClient blobServiceClient, BlobClient sourceBlob) {
    // Get a user delegation key
    OffsetDateTime delegationKeyStartTime = OffsetDateTime.now();
    OffsetDateTime delegationKeyExpiryTime = OffsetDateTime.now().plusDays(1);
    UserDelegationKey key = blobServiceClient.getUserDelegationKey(
        delegationKeyStartTime,
        delegationKeyExpiryTime);

    // Create a SAS token that's valid for one day, as an example
    OffsetDateTime expiryTime = OffsetDateTime.now().plusDays(1);

    // Set the Read (r) permission on the SAS token
    BlobSasPermission permission = new BlobSasPermission().setReadPermission(true);

    BlobServiceSasSignatureValues sasValues = new BlobServiceSasSignatureValues(expiryTime, permission)
            .setStartTime(OffsetDateTime.now());

    // Create a SAS token that's valid for one day
    String sasToken = sourceBlob.generateUserDelegationSas(sasValues, key);

    return sasToken;
}

Hinweis

SAS-Token für die Benutzerdelegierung bieten mehr Sicherheit, da sie mit Microsoft Entra-Anmeldeinformationen anstelle eines Kontoschlüssels signiert sind. Um ein SAS-Token für die Benutzerdelegierung zu erstellen, benötigt der Microsoft Entra-Sicherheitsprinzipal entsprechende Berechtigungen. Informationen zu den Berechtigungsanforderungen finden Sie unter Benutzerdelegierungsschlüssel abrufen.

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.

public void copyFromExternalSourceAsyncScheduling(String sourceURL, BlockBlobClient destinationBlob) {
    // Start the copy operation and wait for it to complete
    final SyncPoller<BlobCopyInfo, Void> poller = destinationBlob.beginCopy(
            sourceURL,
            Duration.ofSeconds(2));
    PollResponse<BlobCopyInfo> response = poller.waitUntil(LongRunningOperationStatus.SUCCESSFULLY_COMPLETED);
}

Überprüfen des Status eines Kopiervorgangs

Wenn Sie den Status eines Copy Blob-Vorgangs überprüfen möchten, können Sie getCopyStatus für das BlobCopyInfo-Objekt abrufen, das von SyncPoller zurückgegeben wurde.

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

public void checkCopyStatus(BlobCopyInfo copyInfo) {
    // Check the status of the copy operation 
    System.out.printf("Copy status", copyInfo.getCopyStatus());
}

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 die folgende Methode auf:

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:

public void abortCopy(BlobCopyInfo copyInfo, BlobClient destinationBlob) {
    // Check the copy status and abort if pending
    if (copyInfo.getCopyStatus() == CopyStatusType.PENDING) {
        destinationBlob.abortCopyFromUrl(copyInfo.getCopyId());
        System.out.printf("Copy operation %s has been aborted%n", copyInfo.getCopyId());
    }
}

Ressourcen

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

Codebeispiele

REST-API-Vorgänge

Das SDK für Java 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 Java-Paradigmen. Die Clientbibliotheksmethoden, die in diesem Artikel behandelt werden, verwenden die folgenden REST-API-Vorgänge:

Ressourcen zur Clientbibliothek

Zugehöriger Inhalt

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