共用方式為

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

  • 發行項

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

必要條件

設定您的環境

如果您沒有現有的專案，本節說明如何設定專案以使用適用於 .NET 的 Azure Blob 儲存體 客戶端連結庫。 這些步驟包括套件安裝、新增 using 指示詞，以及建立授權的客戶端物件。 如需詳細資訊，請參閱開始使用 Azure Blob 儲存體 和 .NET。

安裝套件

從您的專案目錄中，使用 dotnet add package 命令安裝 Azure Blob 儲存體和 Azure 身分識別客戶端程式庫的套件。 需要 Azure.Identity 套件才能對 Azure 服務進行無密碼連線。

dotnet add package Azure.Storage.Blobs
dotnet add package Azure.Identity

新增 using 指示詞

using將這些指示字新增至程式碼檔案頂端：

using Azure.Identity;
using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
using Azure.Storage.Blobs.Specialized;

本文中的某些程式代碼範例可能需要其他 using 指示詞。

建立用戶端物件

若要將應用程式連線到 Blob 記憶體，請建立 BlobServiceClient 的實例。 下列範例示範如何使用 來建立客戶端物件 DefaultAzureCredential 以進行授權：

public BlobServiceClient GetBlobServiceClient(string accountName)
{
    BlobServiceClient client = new(
        new Uri($"https://{accountName}.blob.core.windows.net"),
        new DefaultAzureCredential());

    return client;
}

您也可以在 .NET 應用程式中註冊服務用戶端以進行 相依性插入 。 若要深入了解如何建立及管理用戶端物件，請參閱建立和管理與資料資源互動的用戶端端物件 (部分機器翻譯)。

授權

授權機制必須具有使用容器屬性或元數據的必要許可權。 若要使用 Microsoft Entra ID 進行授權（建議使用），您需要 Azure RBAC 內建角色記憶體 Blob 數據讀取器或更新版本的取得作業，以及設定作業的記憶體 Blob 數據參與者或更高版本。 若要深入瞭解，請參閱設定 Blob 屬性（REST API）、取得 Blob 屬性（REST API）、設定 Blob 元數據（REST API）或取得 Blob 元數據（REST API）的授權指引。

關於屬性和中繼資料

  • 系統屬性：系統屬性存在於每個 Blob 儲存體資源上。 其中一些可以讀取或設定，另一些則是唯讀的。 實際上，某些系統屬性會對應至特定標準 HTTP 標頭。 適用於 .NET 的 Azure 儲存體用戶端程式庫會為您維護這些屬性。

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

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

注意

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

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

設定和擷取屬性

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

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

public static async Task SetBlobPropertiesAsync(BlobClient blob)
{
    Console.WriteLine("Setting blob properties...");

    try
    {
        // Get the existing properties
        BlobProperties properties = await blob.GetPropertiesAsync();

        BlobHttpHeaders headers = new BlobHttpHeaders
        {
            // Set the MIME ContentType every time the properties 
            // are updated or the field will be cleared
            ContentType = "text/plain",
            ContentLanguage = "en-us",

            // Populate remaining headers with 
            // the pre-existing properties
            CacheControl = properties.CacheControl,
            ContentDisposition = properties.ContentDisposition,
            ContentEncoding = properties.ContentEncoding,
            ContentHash = properties.ContentHash
        };

        // Set the blob's properties.
        await blob.SetHttpHeadersAsync(headers);
    }
    catch (RequestFailedException e)
    {
        Console.WriteLine($"HTTP error code {e.Status}: {e.ErrorCode}");
        Console.WriteLine(e.Message);
        Console.ReadLine();
    }
}

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

private static async Task GetBlobPropertiesAsync(BlobClient blob)
{
    try
    {
        // Get the blob properties
        BlobProperties properties = await blob.GetPropertiesAsync();

        // Display some of the blob's property values
        Console.WriteLine($" ContentLanguage: {properties.ContentLanguage}");
        Console.WriteLine($" ContentType: {properties.ContentType}");
        Console.WriteLine($" CreatedOn: {properties.CreatedOn}");
        Console.WriteLine($" LastModified: {properties.LastModified}");
    }
    catch (RequestFailedException e)
    {
        Console.WriteLine($"HTTP error code {e.Status}: {e.ErrorCode}");
        Console.WriteLine(e.Message);
        Console.ReadLine();
    }
}

設定及擷取中繼資料

您可以將中繼資料指定為 blob 或容器資源上的一個或多個成對的名稱和數值。 若要設定中繼資料，請將名稱-值組新增至資源上的 Metadata 集合。 然後，呼叫下列其中一個方法來寫入值：

下列程式碼範例會在 Blob 上設定中繼資料。 其中一個值是使用集合的 Add 方法設定。 其他值是使用隱含的索引鍵/值語法來設定。

public static async Task AddBlobMetadataAsync(BlobClient blob)
{
    Console.WriteLine("Adding blob metadata...");

    try
    {
        IDictionary<string, string> metadata =
           new Dictionary<string, string>();

        // Add metadata to the dictionary by calling the Add method
        metadata.Add("docType", "textDocuments");

        // Add metadata to the dictionary by using key/value syntax
        metadata["category"] = "guidance";

        // Set the blob's metadata.
        await blob.SetMetadataAsync(metadata);
    }
    catch (RequestFailedException e)
    {
        Console.WriteLine($"HTTP error code {e.Status}: {e.ErrorCode}");
        Console.WriteLine(e.Message);
        Console.ReadLine();
    }
}

下列程式碼範例會在 Blob 上讀取中繼資料。

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

public static async Task ReadBlobMetadataAsync(BlobClient blob)
{
    try
    {
        // Get the blob's properties and metadata.
        BlobProperties properties = await blob.GetPropertiesAsync();

        Console.WriteLine("Blob metadata:");

        // Enumerate the blob's metadata.
        foreach (var metadataItem in properties.Metadata)
        {
            Console.WriteLine($"\tKey: {metadataItem.Key}");
            Console.WriteLine($"\tValue: {metadataItem.Value}");
        }
    }
    catch (RequestFailedException e)
    {
        Console.WriteLine($"HTTP error code {e.Status}: {e.ErrorCode}");
        Console.WriteLine(e.Message);
        Console.ReadLine();
    }
}

資源

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

REST API 操作

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

用戶端程式庫資源