使用 Go 上传块 blob

项目
11/11/2024

本文介绍如何使用适用于 Go 的 Azure 存储客户端模块上传 blob。可以通过文件路径、流、二进制对象或文本字符串将数据上传到块 Blob。还可以上传带有索引标记的 Blob。

先决条件

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
}

授权

授权机制必须具有上传 blob 所需的权限。若要使用 Microsoft Entra ID 进行授权（建议），需要 Azure RBAC 内置角色“存储 Blob 数据参与者”或更高级别的角色。若要了解详细信息，请参阅有关放置 Blob (REST API) 和放置块 (REST API) 的授权指南。

将数据上传到块 Blob

若要上传 blob，请从客户端对象调用以下任一方法：

若要执行上传，客户端库可以使用放置 Blob 或一系列放置块调用，后跟 Put Block List。此行为取决于对象的总体大小和数据传输选项的设置方式。

通过本地文件路径上传块 Blob

以下示例会将本地文件上传到块 blob：

func uploadBlobFile(client *azblob.Client, containerName string, blobName string) {
    // Open the file for reading
    file, err := os.OpenFile("path/to/sample/file", os.O_RDONLY, 0)
    handleError(err)

    defer file.Close()

    // Upload the file to the specified container with the specified blob name
    _, err = client.UploadFile(context.TODO(), containerName, blobName, file, nil)
    handleError(err)
}

通过流式传输上传块 Blob

以下示例将创建一个 Reader 实例，并且会像处理字节流那样从字符串中进行读取。然后将该流上传到块 blob：

func uploadBlobStream(client *azblob.Client, containerName string, blobName string) {
    data := "Hello, world!"
    blobContentReader := strings.NewReader(data)

    // Upload the file to the specified container with the specified blob name
    _, err := client.UploadStream(context.TODO(), containerName, blobName, blobContentReader, nil)
    handleError(err)
}

将二进制数据上传到块 Blob

以下示例将二进制数据上传到块 blob：

func uploadBlobBuffer(client *azblob.Client, containerName string, blobName string) {
    // Create a buffer with the content of the file to upload
    data := []byte("Hello, world!")

    // Upload the data to a block blob
    _, err := client.UploadBuffer(context.TODO(), containerName, blobName, data, nil)
    handleError(err)
}

上传带有索引标记的块 blob

以下示例上传设置了索引标记的块 blob：

func uploadBlobWithIndexTags(client *azblob.Client, containerName string, blobName string) {
    // Create a buffer with the content of the file to upload
    data := []byte("Hello, world!")

    // Upload the data to a block blob with index tags
    _, err := client.UploadBuffer(context.TODO(), containerName, blobName, data, &azblob.UploadBufferOptions{
        Tags: map[string]string{
            "key1": "value1",
            "key2": "value2",
        },
    })
    handleError(err)
}

使用配置选项上传块 blob

上传 blob 时，可以定义客户端库配置选项。可以优化这些选项以提高性能、增强可靠性和优化成本。以下代码示例演示如何定义上传操作的配置选项。

指定用于上传的数据传输选项

你可以设置上传 blob 时的配置选项，以优化性能。以下配置选项可用于上传操作：

BlockSize：上传块 blob 时每个块的大小。默认值为 4 MB。
Concurrency：上传期间要使用的并行连接的最大数目。默认值为 5。

使用以下方法上传时，可以使用这些配置选项：

Upload 方法不支持这些选项，并会在单个请求中上传数据。

若要详细了解 Blob 存储的传输大小限制，请参阅 Blob 存储的缩放目标。

下面的代码示例演示如何使用 UploadFileOptions 指定数据传输选项。此示例中提供的值不作为建议。若要正确优化这些值，需要考虑应用的特定需求。

func uploadBlobWithTransferOptions(client *azblob.Client, containerName string, blobName string) {
    // Open the file for reading
    file, err := os.OpenFile("path/to/sample/file", os.O_RDONLY, 0)
    handleError(err)

    defer file.Close()

    // Upload the data to a block blob with transfer options
    _, err = client.UploadFile(context.TODO(), containerName, blobName, file,
        &azblob.UploadFileOptions{
            BlockSize:   int64(4 * 1024 * 1024), // 4 MiB
            Concurrency: uint16(2),
        })
    handleError(err)
}

若要详细了解如何优化数据传输选项，请参阅优化 Go 的上传和下载性能。

注意

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

资源

若要详细了解如何使用适用于 Go 的 Azure Blob 存储客户端模块上传 Blob，请参阅以下资源。

代码示例

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

REST API 操作

Azure SDK for Go 包含基于 Azure REST API 而生成的库，从而允许你通过熟悉的 Go 范式与 REST API 操作进行交互。用于上传 blob 的客户端库方法使用以下 REST API 操作：

放置 Blob (REST API)
放置块 (REST API)

客户端模块资源

请参阅

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

通过