使用 Go 管理 Blob 属性和元数据

项目
09/04/2024

除 Blob 包含的数据外，它们还支持系统属性和用户定义的元数据。本文介绍如何使用适用于 Go 的 Azure 存储客户端模块管理系统属性和用户定义的元数据。

先决条件

Azure 订阅 - 创建试用订阅。
Azure 存储帐户 - 创建存储帐户
Go 1.18+

设置你的环境

如果没有现有项目，请查看本部分，其中介绍了如何设置项目来使用适用于 Go 的 Azure Blob 存储客户端模块。步骤包括模块安装、添加 import 路径以及创建授权的客户端对象。有关详细信息，请参阅 Azure Blob 存储和 Go 入门。

安装模块

使用以下命令安装 azblob 模块：

go get github.com/Azure/azure-sdk-for-go/sdk/storage/azblob

若要使用 Microsoft Entra ID 进行身份验证（建议），请使用以下命令安装 azidentity 模块：

go get github.com/Azure/azure-sdk-for-go/sdk/azidentity

添加导入路径

在代码文件中添加以下导入路径：

import (
    "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
	"github.com/Azure/azure-sdk-for-go/sdk/storage/azblob"
)

这些导入路径代表了开始之前需要满足的最低要求。本文中的某些代码示例可能需要其他导入路径。有关具体详细信息和示例用法，请参阅代码示例。

创建客户端对象

若要将应用连接到 Blob 存储，请使用 azblob.NewClient 创建客户端对象。以下示例演示如何使用 DefaultAzureCredential 创建客户端对象进行授权：

func getServiceClientTokenCredential(accountURL string) *azblob.Client {
    // Create a new service client with token credential
    credential, err := azidentity.NewDefaultAzureCredential(nil)
    handleError(err)

    client, err := azblob.NewClient(accountURL, credential, nil)
    handleError(err)

    return client
}

授权

授权机制必须具有处理容器属性或元数据所需的权限。若要使用 Microsoft Entra ID 进行授权（建议），需具有 Azure RBAC 内置角色“存储 Blob 数据读取者”或更高级别的角色以便能够执行获取操作，并具有“存储 Blob 数据参与者”或更高级别的角色以便能够执行设置操作。有关详细信息，请参阅设置 Blob 属性 (REST API)、获取 Blob 属性 (REST API)、设置 Blob 元数据 (REST API) 或获取 Blob 元数据 (REST API) 的授权指南。

关于属性和元数据

系统属性：系统属性存在于每个 Blob 存储资源上。其中一些属性是可以读取或设置的，而另一些属性是只读的。事实上，有些系统属性与某些标准 HTTP 标头对应。适用于 Go 的 Azure 存储客户端库将为你维护这些属性。
用户定义的元数据：用户定义元数据包含一个或多个你为 Blob 存储资源指定的名称/值对对。可以使用元数据存储资源的其他值。元数据值仅用于你自己的目的，不会影响资源的行为方式。

元数据名称/值对是有效的 HTTP 标头，因此应当遵循所有控制 HTTP 标头的限制。有关元数据命名要求的详细信息，请参阅元数据名称。

注意

使用 Blob 索引标记，还可以将任意用户定义的键/值属性与 Azure Blob 存储资源一起存储。虽然与元数据类似，但只会自动为 Blob 索引标记编制索引，并由本机的 blob 服务进行搜索。除非使用了单独的服务（如 Azure 搜索），否则无法对元数据进行索引和查询。

若要详细了解此功能，请参阅通过 Blob 索引（预览版）管理和查找 Azure Blob 存储上的数据。

设置和检索属性

若要设置 Blob 的属性，请从 Blob 客户端对象调用以下方法：

SetHTTPHeaders

清除未显式设置的任何属性。若要保留任何现有属性，可以先检索 Blob 属性，然后使用它们填充未更新的标头。

以下代码示例设置 Blob 上的 BlobContentType 和 BlobContentLanguage 系统属性，同时保留现有属性：

func setBlobProperties(client *azblob.Client, containerName string, blobName string) {
    // Reference the blob as a client object
    blobClient := client.ServiceClient().NewContainerClient(containerName).NewBlobClient(blobName)

    // Get the existing blob properties
    resp, err := blobClient.GetProperties(context.TODO(), nil)
    handleError(err)

    // Set the new blob properties and include existing properties
    _, err = blobClient.SetHTTPHeaders(context.TODO(), blob.HTTPHeaders{
        BlobContentType:        to.Ptr("text/plain"),
        BlobContentLanguage:    to.Ptr("en-us"),
        BlobContentEncoding:    resp.ContentEncoding,
        BlobContentDisposition: resp.ContentDisposition,
        BlobCacheControl:       resp.CacheControl,
    }, nil)
    handleError(err)
}

若要检索 Blob 的属性，请从 Blob 客户端对象调用以下方法：

GetProperties

以下代码示例获取 blob 的系统属性并显示一些值：

func getBlobProperties(client *azblob.Client, containerName string, blobName string) {
    // Reference the blob as a client object
    blobClient := client.ServiceClient().NewContainerClient(containerName).NewBlobClient(blobName)

    // Get the blob properties
    resp, err := blobClient.GetProperties(context.TODO(), nil)
    handleError(err)

    // Print the blob properties
    fmt.Printf("Content type: %v\n", *resp.ContentType)
    fmt.Printf("Content language: %v\n", *resp.ContentLanguage)
}

设置和检索元数据

可将元数据指定为 Blob 或容器资源上的一个或多个名称/值对。若要设置元数据，请从 Blob 客户端对象使用以下方法来发送包含名称/值对的映射：

SetMetadata

以下代码示例在 blob 上设置元数据：

func setBlobMetadata(client *azblob.Client, containerName string, blobName string) {
    // Reference the blob as a client object
    blobClient := client.ServiceClient().NewContainerClient(containerName).NewBlobClient(blobName)

    // Set the blob metadata
    var metadata = make(map[string]*string)
    metadata["key1"] = to.Ptr("value1")
    metadata["key2"] = to.Ptr("value2")

    _, err := blobClient.SetMetadata(context.TODO(), metadata, nil)
    handleError(err)
}

若要检索元数据，请从 Blob 客户端对象调用 GetProperties 方法，并访问响应中的 Metadata 字段。 GetProperties 方法通过调用获取 Blob 属性操作和获取 Blob 元数据操作来检索 blob 属性和元数据。

下面的代码示例读取有关 blob 的元数据并打印每个键/值对：

func getBlobMetadata(client *azblob.Client, containerName string, blobName string) {
    // Reference the blob as a client object
    blobClient := client.ServiceClient().NewContainerClient(containerName).NewBlobClient(blobName)

    // Get the blob properties, which includes metadata
    resp, err := blobClient.GetProperties(context.TODO(), nil)
    handleError(err)

    // Print the blob metadata
    for k, v := range resp.Metadata {
        fmt.Printf("%v: %v\n", k, *v)
    }
}

注意

本指南中的代码示例旨在帮助你开始使用 Azure Blob 存储和 Go。你应该修改错误处理和 Context 值以满足应用程序的需求。

资源

若要详细了解如何使用适用于 Go 的 Azure Blob 存储客户端模块来管理系统属性和用户定义的元数据，请参阅以下资源。

代码示例

查看本文中的代码示例 (GitHub)

REST API 操作

Azure SDK for Go 包含基于 Azure REST API 而生成的库，允许你通过熟悉的 Go 范式来与 REST API 操作进行交互。用于管理系统属性和用户定义的元数据的客户端库方法使用以下 REST API 操作：

客户端模块资源

本文是适用于 Go 的 Blob 存储开发人员指南的一部分。若要了解详细信息，请参阅构建 Go 应用中的完整开发人员指南文章列表。

通过