使用 JAVA 管理 Blob 屬性和中繼資料

• .NET
• Java
• JavaScript
• Python
• Go

除了包含的資料之外，Blob 還支援系統屬性和使用者定義的中繼資料。 此文章說明如何使用適用於 JAVA 的 Azure 儲存體用戶端程式庫，來管理系統屬性和使用者定義的中繼資料。

必要條件

• 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.storage.blob.*;
import com.azure.storage.blob.models.*;

import java.util.*;

授權

授權機制必須含有處理容器屬性或中繼資料的必要權限。 若要使用 Microsoft Entra ID 進行授權 (建議)，您需要 Azure RBAC 內建角色儲存體體 Blob 資料讀取器或更新版本，才能取得作業，以及儲存體 Blob 資料參與者或更新版本，才能設定作業。 若要深入了解，請參閱設定 Blob 屬性 (REST API) 的授權指引、取得 Blob 屬性、設定 Blob 中繼資料 (REST API)，或取得 Blob 中繼資料 (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 儲存體資源上。 其中一些可以讀取或設定，另一些則是唯讀的。 實際上，某些系統屬性會對應至特定標準 HTTP 標頭。 適用於 JAVA 的 Azure 儲存體用戶端程式庫會為您維護這些屬性。

• 使用者定義的中繼資料：使用者定義的中繼資料是由您為 Blob 儲存體資源所指定一或多個成對的名稱和數值所組成。 您可以使用中繼資料來儲存資源的額外值。 中繼資料值僅供您自己使用，並不會影響資源的運作方式。

  中繼資料名稱/值組是有效的 HTTP 標頭，所以應該遵守控管 HTTP 標頭的所有限制。 如需有關中繼資料命名需求的詳細資訊，請參閱中繼資料名稱。

注意

Blob 索引標記也提供將任意使用者定義索引鍵/值屬性與 Azure Blob 儲存體資源一起儲存的功能。 雖然與中繼資料類似，但是只有 Blob 索引標記會自動編製索引，並且可讓原生 Blob 服務進行搜尋。 除非您利用個別服務 (例如 Azure 搜尋服務)，否則中繼資料無法進行編製索引和查詢。

若要深入了解此功能，請參閱使用 Blob 索引來管理和尋找 Azure Blob 儲存體上的資料。

設定和擷取屬性

若要在 Blob 上設定屬性，請使用下列方法：

• setHTTPHeaders

下列程式碼範例會在 Blob 上設定 ContentType 和 ContentLanguage 系統屬性。

未明確設定的任何屬性都會被清除。 下列程式碼範例會先取得 Blob 上現有的屬性，然後將其用來填入未更新的標頭。

public void setBlobProperties(BlobClient blobClient) {
    BlobProperties properties = blobClient.getProperties();

    // Set the ContentLanguage and ContentType headers, and populate the remaining
    // headers from the existing properties
    BlobHttpHeaders blobHeaders = new BlobHttpHeaders()
            .setContentLanguage("en-us")
            .setContentType("text/plain")
            .setCacheControl(properties.getCacheControl())
            .setContentDisposition(properties.getContentDisposition())
            .setContentEncoding(properties.getContentEncoding())
            .setContentMd5(properties.getContentMd5());

    blobClient.setHttpHeaders(blobHeaders);
    System.out.println("Set HTTP headers completed");
}

若要擷取 Blob 上的屬性，請使用下列方法：

• getProperties

下列程式碼範例會取得 Blob 的系統屬性，並顯示部分值：

public void getBlobProperties(BlobClient blobClient) {
    BlobProperties properties = blobClient.getProperties();

    System.out.printf("BlobType: %s%n", properties.getBlobType());
    System.out.printf("BlobSize: %d%n", properties.getBlobSize());
    System.out.printf("ContentLanguage: %s%n", properties.getContentLanguage());
    System.out.printf("ContentType: %s%n", properties.getContentType());
}

設定及擷取中繼資料

您可以將中繼資料指定為 blob 或容器資源上的一個或多個成對的名稱和數值。 若要設定中繼資料，請使用下列方法傳送 Map 物件，其中包含成對的名稱和數值：

• setMetadata

下列程式碼範例會在 Blob 上設定中繼資料：

public void addBlobMetadata(BlobClient blobClient) {
    Map<String, String> metadata = new HashMap<String, String>();
    metadata.put("docType", "text");
    metadata.put("category", "reference");

    try {
        blobClient.setMetadata(metadata);
        System.out.printf("Set metadata completed %n");
    } catch (UnsupportedOperationException error) {
        System.out.printf("Failure while setting metadata %n");
    }
}

若要擷取中繼資料，請在您的 Blob 上呼叫 getProperties 方法，以填入中繼資料集合，然後讀取這些值，如以下範例所示。 getProperties 方法會藉由呼叫取得 Blob 屬性作業和取得 Blob 中繼資料作業來擷取 Blob 屬性和中繼資料。

下列程式碼範例會讀取 Blob 上的中繼資料，並列印每個索引鍵/值組：

public void readBlobMetadata(BlobClient blobClient) {
    // Get blob properties and metadata
    BlobProperties properties = blobClient.getProperties();

    System.out.printf("Blob metadata: %n");
    properties.getMetadata().entrySet().forEach(metadataItem -> {
        System.out.printf(" %s = %s%n", metadataItem.getKey(), metadataItem.getValue());
    });
}

資源

若要深入了解如何使用適用於 JAVA 的 Azure Blob 儲存體用戶端程式庫來管理系統屬性和使用者定義中繼資料，請參閱下列資源。

程式碼範例

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

REST API 操作

適用於 JAVA 的 Azure SDK 包含建置在 Azure REST API 上的程式庫，可讓您透過熟悉的 Java 範例與 REST API 作業進行互動。 用於管理系統屬性與使用者定義中繼資料的用戶端程式庫方法會使用下列 REST API 作業：

• 設定 Blob 屬性 (REST API)
• 取得 Blob 屬性 (REST API)
• 設定 Blob 中繼資料 (REST API)
• 取得 Blob 中繼資料 (REST API)

用戶端程式庫資源

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

相關內容

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