Udostępnij za pośrednictwem

Kopiowanie obiektu blob z planowaniem asynchronicznym przy użyciu języka Java

  • Artykuł

W tym artykule pokazano, jak skopiować obiekt blob z planowaniem asynchronicznym przy użyciu biblioteki klienta usługi Azure Storage dla języka Java. Obiekt blob można skopiować ze źródła na tym samym koncie magazynu, ze źródła na innym koncie magazynu lub z dowolnego dostępnego obiektu pobranego za pośrednictwem żądania HTTP GET dla danego adresu URL. Możesz również przerwać oczekującą operację kopiowania.

Metody biblioteki klienta omówione w tym artykule korzystają z operacji kopiowania interfejsu API REST obiektów blob i mogą być używane, gdy chcesz wykonać kopię za pomocą planowania asynchronicznego. W przypadku większości scenariuszy kopiowania, w których chcesz przenieść dane na konto magazynu i mieć adres URL obiektu źródłowego, zobacz Kopiowanie obiektu blob z adresu URL obiektu źródłowego za pomocą języka Java.

Wymagania wstępne

Konfigurowanie środowiska

Jeśli nie masz istniejącego projektu, w tej sekcji pokazano, jak skonfigurować projekt do pracy z biblioteką klienta usługi Azure Blob Storage dla języka Java. Aby uzyskać więcej informacji, zobacz Rozpoczynanie pracy z usługami Azure Blob Storage i Java.

Aby pracować z przykładami kodu w tym artykule, wykonaj następujące kroki, aby skonfigurować projekt.

Uwaga

W tym artykule użyto narzędzia kompilacji maven do skompilowania i uruchomienia przykładowego kodu. Inne narzędzia kompilacji, takie jak Gradle, współpracują również z zestawem Azure SDK dla języka Java.

Instalowanie pakietów

pom.xml Otwórz plik w edytorze tekstów. Zainstaluj pakiety, dołączając plik BOM lub uwzględniając bezpośrednią zależność.

Dodawanie instrukcji importu

Dodaj następujące instrukcje import:

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.*;

Autoryzacja

Mechanizm autoryzacji musi mieć uprawnienia niezbędne do wykonania operacji kopiowania lub przerwania oczekującej kopii. W przypadku autoryzacji przy użyciu identyfikatora Entra firmy Microsoft (zalecane) najmniej uprzywilejowana rola wbudowana RBAC platformy Azure różni się w zależności od kilku czynników. Aby dowiedzieć się więcej, zobacz wskazówki autoryzacji dotyczące kopiowania obiektów blob (interfejs API REST) lub Abort Copy Blob (INTERFEJS API REST) .

Tworzenie obiektu klienta

Aby połączyć aplikację z usługą Blob Storage, utwórz wystąpienie klasy BlobServiceClient.

W poniższym przykładzie użyto obiektu BlobServiceClientBuilder do skompilowania BlobServiceClient obiektu przy użyciu metody DefaultAzureCredentiali pokazano, jak utworzyć klientów kontenerów i obiektów blob, w razie potrzeby:

// 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>");

Aby dowiedzieć się więcej na temat tworzenia obiektów klienta i zarządzania nimi, zobacz Tworzenie obiektów klienta korzystających z zasobów danych i zarządzanie nimi.

Informacje o kopiowaniu obiektów blob za pomocą planowania asynchronicznego

Operacja Copy Blob może zakończyć się asynchronicznie i jest wykonywana na podstawie najlepszego nakładu pracy, co oznacza, że operacja nie gwarantuje natychmiastowego uruchomienia ani ukończenia w określonym przedziale czasu. Operacja kopiowania jest zaplanowana w tle i wykonywana jako serwer ma dostępne zasoby. Operacja może zakończyć się synchronicznie, jeśli kopia występuje na tym samym koncie magazynu.

Operacja Copy Blob może wykonać dowolną z następujących akcji:

  • Skopiuj źródłowy obiekt blob do docelowego obiektu blob o innej nazwie. Docelowy obiekt blob może być istniejącym obiektem blob tego samego typu obiektu blob (blok, dołączanie lub strona) albo może być nowym obiektem blob utworzonym przez operację kopiowania.
  • Skopiuj źródłowy obiekt blob do docelowego obiektu blob o takiej samej nazwie, który zastępuje docelowy obiekt blob. Ten typ operacji kopiowania usuwa wszystkie niezatwierdzone bloki i zastępuje metadane docelowego obiektu blob.
  • Skopiuj plik źródłowy w usłudze Azure File do docelowego obiektu blob. Docelowy obiekt blob może być istniejącym blokowym obiektem blob lub może być nowym blokowym obiektem blob utworzonym przez operację kopiowania. Kopiowanie z plików do stronicowych obiektów blob lub uzupełnialnych obiektów blob nie jest obsługiwane.
  • Skopiuj migawkę na podstawowy obiekt blob. Promując migawkę do pozycji podstawowego obiektu blob, można przywrócić starszą wersję obiektu blob.
  • Skopiuj migawkę do docelowego obiektu blob o innej nazwie. Wynikowy docelowy obiekt blob jest zapisywalnym obiektem blob, a nie migawką.

Aby dowiedzieć się więcej o Copy Blob operacji, w tym o właściwościach, tagach indeksu, metadanych i rozliczeniach, zobacz Kopiowanie uwag dotyczących obiektu blob.

Kopiowanie obiektu blob za pomocą planowania asynchronicznego

Ta sekcja zawiera omówienie metod udostępnianych przez bibliotekę klienta usługi Azure Storage dla języka Java w celu wykonania operacji kopiowania przy użyciu planowania asynchronicznego.

Poniższa metoda opakowuje operację interfejsu API REST kopiowania obiektów blob i rozpoczyna asynchroniczną kopię danych ze źródłowego obiektu blob:

Metoda beginCopy zwraca element SyncPoller w celu sondowania postępu operacji kopiowania. Typ odpowiedzi sondy to BlobCopyInfo. Metoda beginCopy jest używana w przypadku planowania asynchronicznego dla operacji kopiowania.

Kopiowanie obiektu blob ze źródła na platformie Azure

Jeśli kopiujesz obiekt blob na tym samym koncie magazynu, operacja może zakończyć się synchronicznie. Dostęp do źródłowego obiektu blob można autoryzować za pośrednictwem identyfikatora Firmy Microsoft, sygnatury dostępu współdzielonego (SAS) lub klucza konta. Aby uzyskać informacje na temat operacji kopiowania synchronicznego, zobacz Kopiowanie obiektu blob z adresu URL obiektu źródłowego za pomocą języka Java.

Jeśli źródło kopiowania jest obiektem blob na innym koncie magazynu, operacja może zakończyć się asynchronicznie. Źródłowy obiekt blob musi być publiczny lub autoryzowany za pośrednictwem tokenu SAS. Token SAS musi zawierać uprawnienie Odczyt ('r'). Aby dowiedzieć się więcej na temat tokenów SAS, zobacz Delegowanie dostępu za pomocą sygnatur dostępu współdzielonego.

Poniższy przykład przedstawia scenariusz kopiowania źródłowego obiektu blob z innego konta magazynu z asynchronicznym planowaniem. W tym przykładzie utworzymy źródłowy adres URL obiektu blob z dołączonym tokenem SAS delegowania użytkownika. W przykładzie pokazano, jak wygenerować token SAS przy użyciu biblioteki klienta, ale możesz również podać własne. W przykładzie pokazano również, jak dzierżawić źródłowy obiekt blob podczas operacji kopiowania, aby zapobiec zmianom obiektu blob z innego klienta. Operacja Copy Blob zapisuje ETag wartość źródłowego obiektu blob po uruchomieniu operacji kopiowania. Jeśli wartość zostanie zmieniona ETag przed zakończeniem operacji kopiowania, operacja zakończy się niepowodzeniem.

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

Uwaga

Tokeny SAS delegowania użytkownika zapewniają większe bezpieczeństwo, ponieważ są podpisane przy użyciu poświadczeń firmy Microsoft Entra zamiast klucza konta. Aby utworzyć token SAS delegowania użytkownika, podmiot zabezpieczeń firmy Microsoft entra potrzebuje odpowiednich uprawnień. Aby uzyskać wymagania dotyczące autoryzacji, zobacz Pobieranie klucza delegowania użytkownika.

Kopiowanie obiektu blob ze źródła spoza platformy Azure

Operację kopiowania można wykonać na dowolnym obiekcie źródłowym, który można pobrać za pośrednictwem żądania HTTP GET dla danego adresu URL, w tym obiektów dostępnych poza platformą Azure. Poniższy przykład przedstawia scenariusz kopiowania obiektu blob z dostępnego adresu URL obiektu źródłowego.

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

Sprawdzanie stanu operacji kopiowania

Aby sprawdzić stan operacji, możesz wywołać metodę Copy Blob getCopyStatus w obiekcie BlobCopyInfo zwróconym przez SyncPollerpolecenie .

Poniższy przykład kodu pokazuje, jak sprawdzić stan operacji kopiowania:

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

Przerywanie operacji kopiowania

Przerwanie oczekującej Copy Blob operacji powoduje utworzenie docelowego obiektu blob o zerowej długości. Jednak metadane docelowego obiektu blob mają nowe wartości skopiowane ze źródłowego obiektu blob lub ustawione jawnie podczas operacji kopiowania. Aby zachować oryginalne metadane przed kopią, przed wywołaniem jednej z metod kopiowania utwórz migawkę docelowego obiektu blob.

Aby przerwać oczekującą operację kopiowania, wywołaj następującą metodę:

Ta metoda opakowuje operację interfejsu API REST kopiowania obiektu blob abort, która anuluje oczekującą Copy Blob operację. Poniższy przykład kodu pokazuje, jak przerwać oczekującą Copy Blob operację:

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

Zasoby

Aby dowiedzieć się więcej na temat kopiowania obiektów blob przy użyciu biblioteki klienta usługi Azure Blob Storage dla języka Java, zobacz następujące zasoby.

Przykłady kodu

Operacje interfejsu API REST

Zestaw Azure SDK dla języka Java zawiera biblioteki, które bazują na interfejsie API REST platformy Azure, co umożliwia interakcję z operacjami interfejsu API REST za pomocą znanych paradygmatów języka Java. Metody biblioteki klienta opisane w tym artykule korzystają z następujących operacji interfejsu API REST:

Zasoby biblioteki klienta

Powiązana zawartość

  • Ten artykuł jest częścią przewodnika dla deweloperów usługi Blob Storage dla języka Java. Aby dowiedzieć się więcej, zobacz pełną listę artykułów z przewodnika dla deweloperów w temacie Tworzenie aplikacji Java.