Sdílet prostřednictvím

Kopírování objektu blob s asynchronním plánováním pomocí Javy

  • Článek

Tento článek ukazuje, jak zkopírovat objekt blob s asynchronním plánováním pomocí klientské knihovny Azure Storage pro Javu. Objekt blob můžete zkopírovat ze zdroje ve stejném účtu úložiště, ze zdroje v jiném účtu úložiště nebo z libovolného přístupného objektu načteného prostřednictvím požadavku HTTP GET na dané adrese URL. Můžete také přerušit čekající operaci kopírování.

Metody klientské knihovny popsané v tomto článku používají operaci copy blob REST API a lze ji použít, když chcete provést kopírování s asynchronním plánováním. Ve většině scénářů kopírování, ve kterých chcete přesunout data do účtu úložiště a mít adresu URL zdrojového objektu, najdete v tématu Kopírování objektu blob ze zdrojové adresy URL objektu pomocí Javy.

Požadavky

Nastavení prostředí

Pokud nemáte existující projekt, v této části se dozvíte, jak nastavit projekt pro práci s klientskou knihovnou Azure Blob Storage pro Javu. Další informace najdete v tématu Začínáme se službou Azure Blob Storage a Javou.

Pokud chcete pracovat s příklady kódu v tomto článku, nastavte projekt pomocí následujícího postupu.

Poznámka:

Tento článek používá nástroj pro sestavení Maven k sestavení a spuštění ukázkového kódu. Další nástroje sestavení, jako je Gradle, také pracují se sadou Azure SDK pro Javu.

Instalace balíčků

Otevřete soubor v textovém pom.xml editoru. Nainstalujte balíčky zahrnutím souboru kusovníku nebo zahrnutím přímé závislosti.

Přidání příkazů importu

Přidejte následující příkazy 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.*;

Autorizace

Autorizační mechanismus musí mít potřebná oprávnění k provedení operace kopírování nebo k přerušení čekající kopie. Pro autorizaci pomocí Microsoft Entra ID (doporučeno) se nejméně privilegovaná předdefinovaná role Azure RBAC liší v závislosti na několika faktorech. Další informace najdete v pokynech k autorizaci pro kopírování objektů blob (REST API) nebo přerušení kopírování objektu blob (REST API).

Vytvoření objektu klienta

Pokud chcete připojit aplikaci ke službě Blob Storage, vytvořte instanci BlobServiceClient.

Následující příklad používá BlobServiceClientBuilder k sestavení BlobServiceClient objektu pomocí DefaultAzureCredentiala ukazuje, jak vytvořit kontejner a klienty objektů blob v případě potřeby:

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

Další informace o vytváření a správě klientských objektů najdete v tématu Vytváření a správa klientských objektů, které pracují s datovými prostředky.

Kopírování objektů blob pomocí asynchronního plánování

Operace Copy Blob se může dokončit asynchronně a provádí se na základě maximálního úsilí, což znamená, že není zaručeno, že se operace spustí okamžitě nebo dokončí v zadaném časovém rámci. Operace kopírování se naplánuje na pozadí a provede se tak, jak má server dostupné prostředky. Operace může být dokončena synchronně, pokud se kopie vyskytuje ve stejném účtu úložiště.

Copy Blob Operace může provádět některou z následujících akcí:

  • Zkopírujte zdrojový objekt blob do cílového objektu blob s jiným názvem. Cílovým objektem blob může být existující objekt blob stejného typu objektu blob (blok, připojení nebo stránka), nebo může být novým objektem blob vytvořeným operací kopírování.
  • Zkopírujte zdrojový objekt blob do cílového objektu blob se stejným názvem, který nahradí cílový objekt blob. Tento typ operace kopírování odebere všechny nepotvrzené bloky a přepíše metadata cílového objektu blob.
  • Zkopírujte zdrojový soubor ve službě Azure File Service do cílového objektu blob. Cílovým objektem blob může být existující objekt blob bloku nebo může být nový objekt blob bloku vytvořený operací kopírování. Kopírování ze souborů do objektů blob stránky nebo doplňovacích objektů blob se nepodporuje.
  • Zkopírujte snímek nad jeho základní objekt blob. Zvýšením úrovně snímku na pozici základního objektu blob můžete obnovit starší verzi objektu blob.
  • Zkopírujte snímek do cílového objektu blob s jiným názvem. Výsledný cílový objekt blob je zapisovatelný objekt blob, nikoli snímek.

Další informace o Copy Blob operaci, včetně informací o vlastnostech, značkách indexu, metadatech a fakturaci, najdete v tématu Kopírování poznámek k objektům blob.

Kopírování objektu blob s asynchronním plánováním

Tato část obsahuje přehled metod poskytovaných klientskou knihovnou azure Storage pro Javu k provedení operace kopírování s asynchronním plánováním.

Následující metoda zabalí operaci rozhraní REST API pro kopírování objektů blob a zahájí asynchronní kopii dat ze zdrojového objektu blob:

Metoda beginCopy vrátí SyncPoller k dotazování průběhu operace kopírování. Typ odpovědi dotazu je BlobCopyInfo. Metoda beginCopy se používá, když chcete asynchronní plánování operace kopírování.

Kopírování objektu blob ze zdroje v Azure

Pokud kopírujete objekt blob ve stejném účtu úložiště, operace se může dokončit synchronně. Přístup ke zdrojovému objektu blob je možné autorizovat prostřednictvím ID Microsoft Entra, sdíleného přístupového podpisu (SAS) nebo klíče účtu. Operace alterativní synchronní kopírování najdete v tématu Kopírování objektu blob ze zdrojové adresy URL objektu pomocí Javy.

Pokud je zdrojem kopírování objekt blob v jiném účtu úložiště, může operace asynchronně dokončit. Zdrojový objekt blob musí být veřejný nebo autorizovaný prostřednictvím tokenu SAS. Token SAS musí obsahovat oprávnění ke čtení ('r' ). Další informace o tokenech SAS najdete v tématu Delegování přístupu pomocí sdílených přístupových podpisů.

Následující příklad ukazuje scénář kopírování zdrojového objektu blob z jiného účtu úložiště s asynchronním plánováním. V tomto příkladu vytvoříme adresu URL zdrojového objektu blob s připojeným tokenem SAS delegování uživatele. Příklad ukazuje, jak vygenerovat token SAS pomocí klientské knihovny, ale můžete také zadat vlastní. Příklad také ukazuje, jak zapůjčení zdrojového objektu blob během operace kopírování, aby se zabránilo změnám objektu blob z jiného klienta. Operace Copy Blob uloží ETag hodnotu zdrojového objektu blob při spuštění operace kopírování. ETag Pokud se hodnota změní před dokončením operace kopírování, operace selže.

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

Poznámka:

Tokeny SAS delegování uživatelů nabízejí větší zabezpečení, protože jsou podepsané pomocí přihlašovacích údajů Microsoft Entra místo klíče účtu. K vytvoření tokenu SAS delegování uživatele potřebuje objekt zabezpečení Microsoft Entra příslušná oprávnění. Požadavky na autorizaci najdete v tématu Získání klíče delegování uživatele.

Kopírování objektu blob ze zdroje mimo Azure

Operaci kopírování můžete provést u libovolného zdrojového objektu, který lze načíst prostřednictvím požadavku HTTP GET na danou adresu URL, včetně přístupných objektů mimo Azure. Následující příklad ukazuje scénář kopírování objektu blob z adresy URL přístupného zdrojového objektu.

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

Kontrola stavu operace kopírování

Chcete-li zkontrolovat stav Copy Blob operace, můžete volat getCopyStatus u objektu BlobCopyInfo vráceného objektem SyncPoller.

Následující příklad kódu ukazuje, jak zkontrolovat stav operace kopírování:

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

Přerušení operace kopírování

Přerušení čekající Copy Blob operace způsobí, že cílový objekt blob má nulovou délku. Metadata cílového objektu blob ale mají nové hodnoty zkopírované ze zdrojového objektu blob nebo explicitně nastavené během operace kopírování. Chcete-li zachovat původní metadata před kopií, vytvořte snímek cílového objektu blob před voláním jedné z metod kopírování.

Chcete-li přerušit čekající operaci kopírování, zavolejte následující metodu:

Tato metoda zabalí operaci Abort Copy Blob REST API, která zruší čekající Copy Blob operaci. Následující příklad kódu ukazuje, jak přerušit čekající Copy Blob operaci:

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

Zdroje informací

Další informace o kopírování objektů blob pomocí klientské knihovny azure Blob Storage pro Javu najdete v následujících zdrojích informací.

Ukázky kódu

Operace rozhraní REST API

Sada Azure SDK pro Javu obsahuje knihovny, které jsou postavené na rozhraní Azure REST API a umožňují interakci s operacemi rozhraní REST API prostřednictvím známých paradigmat Javy. Metody klientské knihovny popsané v tomto článku používají následující operace rozhraní REST API:

Prostředky klientské knihovny

Související obsah

  • Tento článek je součástí příručky pro vývojáře služby Blob Storage pro Javu. Další informace najdete v úplném seznamu článků příručky pro vývojáře na webu Sestavení aplikace v Javě.