共用方式為

使用 .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 應用程式中註冊相依性插入的服務用戶端。

您也可以為特定容器或 Blob 建立客戶端物件。 若要深入了解如何建立及管理用戶端物件，請參閱建立和管理與資料資源互動的用戶端端物件 (部分機器翻譯)。

授權

授權機制必須含有處理容器屬性或中繼資料的必要權限。 若要使用 Microsoft Entra ID 進行授權 (建議)，您需要 Azure RBAC 內建角色儲存體體 Blob 資料讀取器或更新版本，才能取得作業，以及儲存體 Blob 資料參與者或更新版本，才能設定作業。 若要深入了解，請參閱設定 Blob 屬性 (REST API) 的授權指引、取得 Blob 屬性、設定 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 作業：

用戶端程式庫資源

相關內容

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