使用 .NET 管理容器属性和元数据Manage container properties and metadata with .NET

除 Blob 容器包含的数据外,它们还支持系统属性和用户定义的元数据。Blob containers support system properties and user-defined metadata, in addition to the data they contain. 本文介绍如何使用用于 .NET 的 Azure 存储客户端库管理系统属性和用户定义元数据。This article shows how to manage system properties and user-defined metadata with the Azure Storage client library for .NET.

关于属性和元数据About properties and metadata

  • 系统属性:系统属性存在于每个 Blob 存储资源上。System properties: System properties exist on each Blob storage resource. 其中一些属性是可以读取或设置的,而另一些属性是只读的。Some of them can be read or set, while others are read-only. 事实上,有些系统属性与某些标准 HTTP 标头对应。Under the covers, some system properties correspond to certain standard HTTP headers. 用于 .NET 的 Azure 存储客户端库将维护这些属性。The Azure Storage client library for .NET maintains these properties for you.

  • 用户定义的元数据:用户定义元数据包含一个或多个你为 Blob 存储资源指定的名称/值对对。User-defined metadata: User-defined metadata consists of one or more name-value pairs that you specify for a Blob storage resource. 可以使用元数据存储资源的其他值。You can use metadata to store additional values with the resource. 元数据值仅用于你自己的目的,不会影响资源的行为方式。Metadata values are for your own purposes only, and do not affect how the resource behaves.

元数据名称/值对是有效的 HTTP 标头,因此应当遵循所有控制 HTTP 标头的限制。Metadata name/value pairs are valid HTTP headers, and so should adhere to all restrictions governing HTTP headers. 元数据名称必须是有效的 HTTP 标头名称和有效的 C# 标识符,只能包含 ASCII 字符,并且应当区分大小写。Metadata names must be valid HTTP header names and valid C# identifiers, may contain only ASCII characters, and should be treated as case-insensitive. 包含非 ASCII 字符的元数据值应当是 Base64 编码的或 URL 编码的。Metadata values containing non-ASCII characters should be Base64-encoded or URL-encoded.

检索容器属性Retrieve container properties

若要检索容器属性,请调用以下方法之一:To retrieve container properties, call one of the following methods:

以下代码示例提取容器的系统属性并将一些属性值写入到控制台窗口:The following code example fetches a container's system properties and writes some property values to a console window:

private static async Task ReadContainerPropertiesAsync(BlobContainerClient container)
{
    try
    {
        // Fetch some container properties and write out their values.
        var properties = await container.GetPropertiesAsync();
        Console.WriteLine($"Properties for container {container.Uri}");
        Console.WriteLine($"Public access level: {properties.Value.PublicAccess}");
        Console.WriteLine($"Last modified time in UTC: {properties.Value.LastModified}");
    }
    catch (RequestFailedException e)
    {
        Console.WriteLine($"HTTP error code {e.Status}: {e.ErrorCode}");
        Console.WriteLine(e.Message);
        Console.ReadLine();
    }
}

设置和检索元数据Set and retrieve metadata

可将元数据指定为 Blob 或容器资源上的一个或多个名称/值对。You can specify metadata as one or more name-value pairs on a blob or container resource. 若要设置元数据,请将名称/值对添加到 IDictionary 对象,然后调用下述方法之一来写入值:To set metadata, add name-value pairs to an IDictionary object, and then call one of the following methods to write the values:

元数据的名称必须符合 C# 标识符命名约定。The name of your metadata must conform to the naming conventions for C# identifiers. 元数据名称保留创建时使用的大小写,但在设置或读取时不区分大小写。Metadata names preserve the case with which they were created, but are case-insensitive when set or read. 如果为一个资源提交了两个或更多个同名的元数据标头,则 Blob 存储会用逗号将这两个值分隔并连接起来,然后返回 HTTP 响应代码“200 (正常)”。If two or more metadata headers with the same name are submitted for a resource, Blob storage comma-separates and concatenates the two values and return HTTP response code 200 (OK).

以下代码示例在容器上设置元数据。The following code example sets metadata on a container.

public static async Task AddContainerMetadataAsync(BlobContainerClient container)
{
    try
    {
        IDictionary<string, string> metadata =
           new Dictionary<string, string>();

        // Add some metadata to the container.
        metadata.Add("docType", "textDocuments");
        metadata.Add("category", "guidance");

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

若要检索元数据,请调用以下方法之一:To retrieve metadata, call one of the following methods:

然后读取值,如下面的示例所示。Then, read the values, as shown in the example below.

public static async Task ReadContainerMetadataAsync(BlobContainerClient container)
{
    try
    {
        var properties = await container.GetPropertiesAsync();

        // Enumerate the container's metadata.
        Console.WriteLine("Container metadata:");
        foreach (var metadataItem in properties.Value.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 进行开发的资源Resources for development with .NET

下面的链接为使用适用于 .NET 的 Azure 存储客户端库的开发人员提供了有用的资源。The links below provide useful resources for developers using the Azure Storage client library for .NET.

Azure 存储通用 APIAzure Storage common APIs

Blob 存储 APIBlob storage APIs

.NET 工具.NET tools

另请参阅See also