使用 JAVA 上傳區塊 Blob

• .NET
• Java
• JavaScript
• Python
• Go

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

必要條件

• Azure 訂用帳戶 - 建立免費帳戶
• Azure 儲存體帳戶 - 建立儲存體帳戶
• JAVA 開發套件 (JDK) 第 8 版或更新版本 (建議使用第 17 版以獲得最佳體驗)
• 在此範例中，Apache Maven 用於專案管理

設定您的環境

如果沒有現有的專案，本章節會說明如何設定專案以使用適用於 JAVA 的 Azure Blob 儲存體用戶端程式庫。 如需詳細資訊，請參閱開始使用 Azure Blob 儲存體和 JAVA (部分機器翻譯)。

若要使用本文中的程式碼範例，請遵循下列步驟來設定您的專案。

注意

本文使用 Maven 建置工具來建置和執行範例程式碼。 Gradle 等其他建置工具也能與適用於 Java 的 Azure SDK 搭配運作。

安裝套件

在文字編輯器中開啟 pom.xml 檔案。 包含 BOM 檔案或包含直接相依性以安裝套件。

新增 import 陳述式

加入下列 import 陳述式：

import com.azure.core.http.rest.*;
import com.azure.core.util.BinaryData;
import com.azure.storage.blob.*;
import com.azure.storage.blob.models.*;
import com.azure.storage.blob.options.BlobUploadFromFileOptions;
import com.azure.storage.blob.specialized.*;

import java.io.ByteArrayInputStream;
import java.io.FileInputStream;
import java.io.IOException;
import java.io.UncheckedIOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Path;
import java.time.Duration;
import java.util.*;

授權

授權機制必須具有上傳 Blob 的必要權限。 如需使用 Microsoft Entra ID 授權 (建議使用)，您需要 Azure RBAC 內建角色儲存體 Blob 資料參與者或更高權限。 若要深入了解，請參閱放置 Blob (REST API) 和放置區塊 (REST API)的授權指引。

建立用戶端物件

若要將應用程式連線至 Blob 儲存體，請建立 BlobServiceClient類別的執行個體。

下列範例會使用 BlobServiceClientBuilder，使用 DefaultAzureCredential 建置 BlobServiceClient 物件，並視需要示範如何建立容器和 Blob 用戶端：

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

若要深入了解如何建立及管理用戶端物件，請參閱建立和管理與資料資源互動的用戶端端物件 (部分機器翻譯)。

將資料上傳至區塊 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，請參閱下列資源。

程式碼範例

• 檢視本文中的程式碼範例 (GitHub) (英文)

REST API 操作

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

• 放置 Blob (REST API)
• 放置區塊 (REST API)

用戶端程式庫資源

• 用戶端程式庫參考文件
• 用戶端程式庫原始程式碼
• 套件 (Maven) \(英文\)

另請參閱

• 使用 Blob 索引標籤來管理及尋找 Azure Blob 資料
• 使用 Blob 索引標籤來管理和尋找 Azure Blob 儲存體上的資料

相關內容

• 本文是適用於 JAVA 的 Blob 儲存體開發人員指南的一部分。 若要深入了解，請參閱位於建置 JAVA 應用程式 (部分機器翻譯) 的開發人員指南文章完整清單。