使用 JAVA 上傳區塊 Blob

發行項
03/24/2024

本文說明如何使用適用於 JAVA 的 Azure 儲存體用戶端程式庫來上傳區塊 BLOb。您可以從檔案路徑、資料流、二進位物件或文字字串將資料上傳至區塊 Blob。您也可以使用索引標籤上傳 Blob。

必要條件

本文假設您已設定了專案來使用適用於 JAVA 的 Azure Blob 儲存體用戶端程式庫。若要了解如何設定專案，包括套件安裝、新增 import 指示詞以及建立授權的用戶端物件，請參閱開始使用 Azure 儲存體和 Java。
授權機制必須具有執行上傳作業的權限。若要深入了解，請參閱下列 REST API 作業的授權指導：
- Put Blob \(英文\)
- 放置區塊

將資料上傳至區塊 Blob

若要從資料流或二進位物件上傳區塊 Blob，請使用下列方法：

上傳

若要從檔案路徑上傳區塊 Blob，請使用下列方法：

uploadFromFile

可以使用 BlobClient 或 BlockBlobClient 物件來呼叫每一個方法。

從本機檔案路徑上傳區塊 Blob

下列範例會使用 BlobClient 物件，將檔案上傳至區塊 Blob：

public void uploadBlobFromFile(BlobContainerClient blobContainerClient) {
    BlobClient blobClient = blobContainerClient.getBlobClient("sampleBlob.txt");

    try {
        blobClient.uploadFromFile("filepath/local-file.png");
    } catch (UncheckedIOException ex) {
        System.err.printf("Failed to upload from file: %s%n", ex.getMessage());
    }
}

從資料流上傳區塊 Blob

下列範例會藉由建立 ByteArrayInputStream 物件並上傳該資料流物件來上傳區塊 Blob：

public void uploadBlobFromStream(BlobContainerClient blobContainerClient) {
    BlockBlobClient blockBlobClient = blobContainerClient.getBlobClient("sampleBlob.txt").getBlockBlobClient();
    String sampleData = "Sample data for blob";
    try (ByteArrayInputStream dataStream = new ByteArrayInputStream(sampleData.getBytes())) {
        blockBlobClient.upload(dataStream, sampleData.length());
    } catch (IOException ex) {
        ex.printStackTrace();
    }
}

從 BinaryData 物件上傳區塊 Blob

下列範例會使用 BlobClient 物件，將 BinaryData 上傳至區塊 Blob：

public void uploadDataToBlob(BlobContainerClient blobContainerClient) {
    // Create a BlobClient object from BlobContainerClient
    BlobClient blobClient = blobContainerClient.getBlobClient("sampleBlob.txt");
    String sampleData = "Sample data for blob";
    blobClient.upload(BinaryData.fromString(sampleData));
}

使用設定選項上傳區塊 Blob

您可以在上傳 Blob 時定義用戶端程式庫設定選項。也可調整這些選項以改善效能、增強可靠性，並將成本最佳化。下列程式碼範例示範如何在呼叫上傳方法時，使用 BlobUploadFromFileOptions 來定義設定選項。如果您不是從檔案上傳，則可以在上傳方法上使用 BlobParallelUploadOptions 來設定類似的選項。

指定上傳時的資料傳輸選項

您可以在 ParallelTransferOptions 中設定值，以提升資料傳輸作業的效能。您可以根據應用程式的需求來為上傳調整下列值：

blockSize：每個要求可傳輸的區塊大小上限。您可以使用 setBlockSizeLong 方法來設定此值。
maxSingleUploadSize：如果資料的大小小於或等於此值，則會單次上傳而不會分成區塊上傳。如果資料是以單次上傳，則會忽略區塊大小。您可以使用 setMaxSingleUploadSizeLong 方法來設定此值。
maxConcurrency：在任何指定時間作為單一平行傳輸一部分發出的平行要求的數目上限。您可以使用 setMaxConcurrency 方法來設定此值。

請確定您有下列 import 指示詞，以使用 ParallelTransferOptions 進行上傳：

import com.azure.storage.blob.models.*;

下列程式碼範例顯示如何設定 ParallelTransferOptions 值，並將選項包含作為 BlobUploadFromFileOptions 執行個體的一部分。此範例中提供的值並非用於建議目的。若要正確調整這些值，您需要考慮應用程式的特定需求。

public void uploadBlockBlobWithTransferOptions(BlobContainerClient blobContainerClient, Path filePath) {
    String fileName = filePath.getFileName().toString();
    BlobClient blobClient = blobContainerClient.getBlobClient(fileName);

    ParallelTransferOptions parallelTransferOptions = new ParallelTransferOptions()
            .setBlockSizeLong((long) (4 * 1024 * 1024)) // 4 MiB block size
            .setMaxConcurrency(2)
            .setMaxSingleUploadSizeLong((long) 8 * 1024 * 1024); // 8 MiB max size for single request upload

    BlobUploadFromFileOptions options = new BlobUploadFromFileOptions(filePath.toString());
    options.setParallelTransferOptions(parallelTransferOptions);

    try {
        Response<BlockBlobItem> blockBlob = blobClient.uploadFromFileWithResponse(options, null, null);
    } catch (UncheckedIOException ex) {
        System.err.printf("Failed to upload from file: %s%n", ex.getMessage());
    }
}

若要深入了解如何微調資料傳輸選項，請參閱使用 JAVA 進行上傳和下載的效能微調。

使用索引標籤上傳區塊 Blob

Blob 索引標記會使用索引鍵/值標記屬性，將儲存體帳戶中的資料分類。這些標記會自動編製索引，並公開為可搜尋的多維度索引，以便輕鬆地尋找資料。

下列範例會使用 BlobUploadFromFileOptions，搭配索引標籤集上傳區塊 Blob：

public void uploadBlockBlobWithIndexTags(BlobContainerClient blobContainerClient, Path filePath) {
    String fileName = filePath.getFileName().toString();
    BlobClient blobClient = blobContainerClient.getBlobClient(fileName);

    Map<String, String> tags = new HashMap<String, String>();
    tags.put("Content", "image");
    tags.put("Date", "2022-01-01");

    Duration timeout = Duration.ofSeconds(10);

    BlobUploadFromFileOptions options = new BlobUploadFromFileOptions(filePath.toString());
    options.setTags(tags);

    try {
        // Create a new block blob, or update the content of an existing blob
        Response<BlockBlobItem> blockBlob = blobClient.uploadFromFileWithResponse(options, timeout, null);
    } catch (UncheckedIOException ex) {
        System.err.printf("Failed to upload from file: %s%n", ex.getMessage());
    }
}

在上傳時設定 Blob 的存取層

您可以使用 BlobUploadFromFileOptions 類別在上傳時設定 Blob 存取層。下列程式碼範例顯示如何在上傳 Blob 時設定存取層：

public void uploadBlobWithAccessTier(BlobContainerClient blobContainerClient, Path filePath) {
    String fileName = filePath.getFileName().toString();
    BlobClient blobClient = blobContainerClient.getBlobClient(fileName);

    BlobUploadFromFileOptions options = new BlobUploadFromFileOptions(filePath.toString())
            .setTier(AccessTier.COOL);

    try {
        Response<BlockBlobItem> blockBlob = blobClient.uploadFromFileWithResponse(options, null, null);
    } catch (UncheckedIOException ex) {
        System.err.printf("Failed to upload from file: %s%n", ex.getMessage());
    }
}

只有區塊 Blob 才能設定存取層。您可以將區塊 Blob 的存取層設定為 Hot、Cool、Cold 或 Archive。若要將存取層設定為 Cold，最低必須使用用戶端程式庫版本 12.21.0。

若要深入了解存取層，請參閱存取層概觀。

透過暫存區塊和認可，以上傳區塊 Blob

您可以手動暫存個別資料區塊，以進一步控制如何將上傳項目分割成區塊。當組成 Blob 的所有區塊都暫存時，您可以將這些區塊認可至 Blob 儲存體。您可以使用此方法，藉由平行上傳區塊來增強效能。

public void uploadBlocks(BlobContainerClient blobContainerClient, Path filePath, int blockSize) throws IOException {
    String fileName = filePath.getFileName().toString();
    BlockBlobClient blobClient = blobContainerClient.getBlobClient(fileName).getBlockBlobClient();

    FileInputStream fileStream = new FileInputStream(filePath.toString());
    List<String> blockIDArrayList = new ArrayList<>();
    byte[] buffer = new byte[blockSize];
    int bytesRead;

    while ((bytesRead = fileStream.read(buffer, 0, blockSize)) != -1) {

        try (ByteArrayInputStream stream = new ByteArrayInputStream(buffer)) {
            String blockID = Base64.getEncoder().encodeToString(UUID.randomUUID().toString().getBytes(StandardCharsets.UTF_8));

            blockIDArrayList.add(blockID);
            blobClient.stageBlock(blockID, stream, buffer.length);
        }
    }

    blobClient.commitBlockList(blockIDArrayList);

    fileStream.close();
}

資源

若要深入了解如何使用適用於 JAVA 的 Azure Blob 儲存體用戶端程式庫來上傳 Blob，請參閱下列資源。

REST API 操作

適用於 JAVA 的 Azure SDK 包含建置在 Azure REST API 上的程式庫，可讓您透過熟悉的 JAVA 範例與 REST API 作業進行互動。用來上傳 BLOb 的用戶端程式庫方法會使用下列 REST API 作業：

Share via