快速入门:使用 Go 上传、下载和列出 BlobQuickstart: Upload, download, and list blobs using Go

本快速入门介绍如何使用 Go 编程语言上传、下载和列出 Azure Blob 存储的容器中的块 Blob。In this quickstart, you learn how to use the Go programming language to upload, download, and list block blobs in a container in Azure Blob storage.

必备条件Prerequisites

若要访问 Azure 存储,需要一个 Azure 订阅。To access Azure Storage, you'll need an Azure subscription. 如果还没有订阅,请在开始前创建一个 1 元试用帐户If you don't already have a subscription, create a 1rmb trial account before you begin.

对 Azure 存储进行的所有访问都要通过存储帐户完成。All access to Azure Storage takes place through a storage account. 对于本快速入门,请使用 Azure 门户、Azure PowerShell 或 Azure CLI 创建存储帐户。For this quickstart, create a storage account using the Azure portal, Azure PowerShell, or Azure CLI. 有关如何创建存储帐户的帮助,请参阅创建存储帐户For help creating a storage account, see Create a storage account.

请确保已安装下述额外的必备组件:Make sure you have the following additional prerequisites installed:

  • Go 1.8 或更高版本Go 1.8 or above

  • 使用以下命令安装用于 Go 的 Azure 存储 Blob SDKAzure Storage Blob SDK for Go, using the following command:

    go get -u github.com/Azure/azure-storage-blob-go/azblob
    

    备注

    确保将 URL 中的 Azure 大写,以免在使用该 SDK 时出现与大小写相关的导入问题。Make sure that you capitalize Azure in the URL to avoid case-related import problems when working with the SDK. 另请在导入语句中将 Azure 大写。Also capitalize Azure in your import statements.

下载示例应用程序Download the sample application

本快速入门中使用的示例应用程序是基本的 Go 应用程序。The sample application used in this quickstart is a basic Go application.

使用 git 可将应用程序的副本下载到开发环境。Use git to download a copy of the application to your development environment.

git clone https://github.com/Azure-Samples/storage-blobs-go-quickstart 

此命令会将存储库克隆到本地 git 文件夹。This command clones the repository to your local git folder. 若要打开用于 Blob 存储的 Go 示例,请查找 storage-quickstart.go 文件。To open the Go sample for Blob storage, look for storage-quickstart.go file.

从 Azure 门户复制凭据Copy your credentials from the Azure portal

此示例应用程序需要对存储帐户访问进行授权。The sample application needs to authorize access to your storage account. 以连接字符串形式将存储帐户凭据提供给应用程序。Provide your storage account credentials to the application in the form of a connection string. 若要查看存储帐户凭据,请执行以下操作:To view your storage account credentials:

  1. Azure 门户中转到自己的存储帐户。In to the Azure portal go to your storage account.

  2. 在存储帐户概述的“设置” 部分中,选择“访问密钥” 以显示你的帐户访问密钥和连接字符串。In the Settings section of the storage account overview, select Access keys to display your account access keys and connection string.

  3. 请记下存储帐户的名称,进行授权时,需提供该名称。Note the name of your storage account, which you'll need for authorization.

  4. 找到“key1”下面的“密钥”值,选择“复制”复制该帐户密钥。 Find the Key value under key1, and select Copy to copy the account key.

    显示如何从 Azure 门户复制帐户密钥的屏幕截图

配置存储连接字符串Configure your storage connection string

此解决方案要求将存储帐户名称和密钥安全地存储在运行示例的计算机的本地环境变量中。This solution requires your storage account name and key to be securely stored in environment variables local to the machine running the sample. 根据操作系统按照下面的一个示例创建环境变量。Follow one of the examples below depending on your operating System to create the environment variables.

export AZURE_STORAGE_ACCOUNT="<youraccountname>"
export AZURE_STORAGE_ACCESS_KEY="<youraccountkey>"

运行示例Run the sample

此示例在当前文件夹中创建一个测试文件,将该测试文件上传到 Blob 存储,在容器中列出 Blob,然后将文件下载到缓冲区中。This sample creates a test file in the current folder, uploads the test file to Blob storage, lists the blobs in the container, and downloads the file into a buffer.

若要运行此示例,请发出以下命令:To run the sample, issue the following command:

go run storage-quickstart.go

以下输出是运行应用程序时返回的输出的示例:The following output is an example of the output returned when running the application:

Azure Blob storage quick start sample
Creating a container named quickstart-5568059279520899415
Creating a dummy file to test the upload and download
Uploading the file with blob name: 630910657703031215
Blob name: 630910657703031215
Downloaded the blob: hello world
this is a blob
Press the enter key to delete the sample files, example container, and exit the application.

按键继续时,示例程序会删除存储容器和文件。When you press the key to continue, the sample program deletes the storage container and the files.

提示

还可以使用工具(如 Azure 存储资源管理器)查看 Blob 存储中的文件。You can also use a tool such as the Azure Storage Explorer to view the files in Blob storage. Azure 存储资源管理器是免费的跨平台工具,可用于访问存储帐户信息。Azure Storage Explorer is a free cross-platform tool that allows you to access your storage account information.

了解示例代码Understand the sample code

接下来逐步介绍示例代码,以便展示其工作方式。Next, we walk through the sample code so that you can understand how it works.

创建 ContainerURL 和 BlobURL 对象Create ContainerURL and BlobURL objects

首先要做的是创建 ContainerURL 和 BlobURL 对象的引用,此类对象用于访问和管理 Blob 存储。The first thing to do is to create the references to the ContainerURL and BlobURL objects used to access and manage Blob storage. 此类对象提供 Create、Upload 和 Download 之类的低级 API,用于发出 REST API。These objects offer low-level APIs such as Create, Upload, and Download to issue REST APIs.

  • 使用 SharedKeyCredential 结构来存储凭据。Use SharedKeyCredential struct to store your credentials.

  • 使用凭据和选项创建一个管道Create a Pipeline using the credentials and options. 该管道用于指定重试策略、日志记录、HTTP 响应有效负载的反序列化等事项。The pipeline specifies things like retry policies, logging, deserialization of HTTP response payloads, and more.

  • 实例化一个新的 ContainerURL 和一个新的 BlobURL 对象,以便在容器上运行操作 (Create) 和在 Blob 上运行操作(Upload 和 Download)。Instantiate a new ContainerURL, and a new BlobURL object to run operations on container (Create) and blobs (Upload and Download).

有了 ContainerURL 之后,即可实例化指向 Blob 的 BlobURL 对象,并执行上传、下载、复制之类的操作。Once you have the ContainerURL, you can instantiate the BlobURL object that points to a blob, and perform operations such as upload, download, and copy.

重要

容器名称必须为小写。Container names must be lowercase. 有关容器名称和 blob 名称的详细信息,请参阅命名和引用容器、Blob 和元数据See Naming and Referencing Containers, Blobs, and Metadata for more information about container and blob names.

本部分创建一个新的容器。In this section, you create a new container. 容器名为 quickstartblobs-[随机字符串]The container is called quickstartblobs-[random string].

// From the Azure portal, get your storage account name and key and set environment variables.
accountName, accountKey := os.Getenv("AZURE_STORAGE_ACCOUNT"), os.Getenv("AZURE_STORAGE_ACCESS_KEY")
if len(accountName) == 0 || len(accountKey) == 0 {
    log.Fatal("Either the AZURE_STORAGE_ACCOUNT or AZURE_STORAGE_ACCESS_KEY environment variable is not set")
}

// Create a default request pipeline using your storage account name and account key.
credential, err := azblob.NewSharedKeyCredential(accountName, accountKey)
if err != nil {
    log.Fatal("Invalid credentials with error: " + err.Error())
}
p := azblob.NewPipeline(credential, azblob.PipelineOptions{})

// Create a random string for the quick start container
containerName := fmt.Sprintf("quickstart-%s", randomString())

// From the Azure portal, get your storage account blob service URL endpoint.
URL, _ := url.Parse(
    fmt.Sprintf("https://%s.blob.core.chinacloudapi.cn/%s", accountName, containerName))

// Create a ContainerURL object that wraps the container URL and a request
// pipeline to make requests.
containerURL := azblob.NewContainerURL(*URL, p)

// Create the container
fmt.Printf("Creating a container named %s\n", containerName)
ctx := context.Background() // This example uses a never-expiring context
_, err = containerURL.Create(ctx, azblob.Metadata{}, azblob.PublicAccessNone)
handleErrors(err)

将 blob 上传到容器Upload blobs to the container

Blob 存储支持块 blob、追加 blob 和页 blob。Blob storage supports block blobs, append blobs, and page blobs. 块 blob 是最常用的 blob,此快速入门中使用的便是它。Block blobs are the most commonly used, and that is what is used in this quickstart.

若要将文件上传到 Blob,请使用 os.Open 打开该文件。To upload a file to a blob, open the file using os.Open. 然后即可使用一个 REST API(Upload (PutBlob)、StageBlock/CommitBlockList (PutBlock/PutBlockList))将该文件上传到指定的路径。You can then upload the file to the specified path using one of the REST APIs: Upload (PutBlob), StageBlock/CommitBlockList (PutBlock/PutBlockList).

另外,也可使用 SDK 提供的高级 API,这是在低级 REST API 的基础上生成的。Alternatively, the SDK offers high-level APIs that are built on top of the low-level REST APIs. 例如,UploadFileToBlockBlob 函数使用 StageBlock (PutBlock) 操作以区块方式同时上传一个文件,以便优化吞吐量。As an example, UploadFileToBlockBlob function uses StageBlock (PutBlock) operations to concurrently upload a file in chunks to optimize the throughput. 如果文件小于 256 MB,则会改用 Upload (PutBlob) 通过单个事务完成传输。If the file is less than 256 MB, it uses Upload (PutBlob) instead to complete the transfer in a single transaction.

以下示例将文件上传到名为 quickstartblobs-[randomstring] 的容器。The following example uploads the file to your container called quickstartblobs-[randomstring].

// Create a file to test the upload and download.
fmt.Printf("Creating a dummy file to test the upload and download\n")
data := []byte("hello world this is a blob\n")
fileName := randomString()
err = ioutil.WriteFile(fileName, data, 0700)
handleErrors(err)

// Here's how to upload a blob.
blobURL := containerURL.NewBlockBlobURL(fileName)
file, err := os.Open(fileName)
handleErrors(err)

// You can use the low-level Upload (PutBlob) API to upload files. Low-level APIs are simple wrappers for the Azure Storage REST APIs.
// Note that Upload can upload up to 256MB data in one shot. Details: https://docs.microsoft.com/rest/api/storageservices/put-blob
// To upload more than 256MB, use StageBlock (PutBlock) and CommitBlockList (PutBlockList) functions. 
// Following is commented out intentionally because we will instead use UploadFileToBlockBlob API to upload the blob
// _, err = blobURL.Upload(ctx, file, azblob.BlobHTTPHeaders{ContentType: "text/plain"}, azblob.Metadata{}, azblob.BlobAccessConditions{})
// handleErrors(err)

// The high-level API UploadFileToBlockBlob function uploads blocks in parallel for optimal performance, and can handle large files as well.
// This function calls StageBlock/CommitBlockList for files larger 256 MBs, and calls Upload for any file smaller
fmt.Printf("Uploading the file with blob name: %s\n", fileName)
_, err = azblob.UploadFileToBlockBlob(ctx, file, blobURL, azblob.UploadToBlockBlobOptions{
    BlockSize:   4 * 1024 * 1024,
    Parallelism: 16})
handleErrors(err)

列出容器中的 BlobList the blobs in a container

可以使用基于 ContainerURLListBlobs 方法获取容器中文件的列表。Get a list of files in the container using the ListBlobs method on a ContainerURL. ListBlobs 返回单个 Blob 段(最多 5000 个 Blob,从指定的标记开始计算)。ListBlobs returns a single segment of blobs (up to 5000) starting from the specified Marker. 使用空标记从头开始枚举。Use an empty Marker to start enumeration from the beginning. Blob 名称按字典中的顺序返回。Blob names are returned in lexicographic order. 获取一个段以后,对其进行处理,然后再次调用 ListBlobs,传递以前返回的标记。After getting a segment, process it, and then call ListBlobs again passing the previously returned Marker.

// List the container that we have created above
fmt.Println("Listing the blobs in the container:")
for marker := (azblob.Marker{}); marker.NotDone(); {
    // Get a result segment starting with the blob indicated by the current Marker.
    listBlob, err := containerURL.ListBlobsFlatSegment(ctx, marker, azblob.ListBlobsSegmentOptions{})
    handleErrors(err)

    // ListBlobs returns the start of the next segment; you MUST use this to get
    // the next segment (after processing the current result segment).
    marker = listBlob.NextMarker

    // Process the blobs returned in this result segment (if the segment is empty, the loop body won't execute)
    for _, blobInfo := range listBlob.Segment.BlobItems {
        fmt.Print(" Blob name: " + blobInfo.Name + "\n")
    }
}

下载 BlobDownload the blob

使用基于 BlobURL 的 Download 低级函数下载 Blob。Download blobs using the Download low-level function on a BlobURL. 这会返回一个 DownloadResponse 结构。This will return a DownloadResponse struct. 在结构上运行函数 Body,以便获取用于读取数据的 RetryReader 流。Run the function Body on the struct to get a RetryReader stream for reading data. 如果某个连接在读取时失败,则会发出其他的请求来重建连接并继续读取。If a connection fails while reading, it will make additional requests to re-establish a connection and continue reading. 如果在指定 RetryReaderOption 时将 MaxRetryRequests 设置为 0(默认设置),则会返回原始响应正文,不会进行重试。Specifying a RetryReaderOption's with MaxRetryRequests set to 0 (the default), returns the original response body and no retries will be performed. 另外,也可使用高级 API DownloadBlobToBufferDownloadBlobToFile 来简化代码。Alternatively, use the high-level APIs DownloadBlobToBuffer or DownloadBlobToFile to simplify your code.

以下代码使用 Download 函数下载 Blob。The following code downloads the blob using the Download function. Blob 的内容写入到缓冲区中,显示在控制台上。The contents of the blob is written into a buffer and shown on the console.

// Here's how to download the blob
downloadResponse, err := blobURL.Download(ctx, 0, azblob.CountToEnd, azblob.BlobAccessConditions{}, false)

// NOTE: automatically retries are performed if the connection fails
bodyStream := downloadResponse.Body(azblob.RetryReaderOptions{MaxRetryRequests: 20})

// read the body into a buffer
downloadedData := bytes.Buffer{}
_, err = downloadedData.ReadFrom(bodyStream)
handleErrors(err)

清理资源Clean up resources

如果不再需要本快速入门中上传的 Blob,可使用 Delete 方法删除整个容器。If you no longer need the blobs uploaded in this quickstart, you can delete the entire container using the Delete method.

// Cleaning up the quick start by deleting the container and the file created locally
fmt.Printf("Press enter key to delete the sample files, example container, and exit the application.\n")
bufio.NewReader(os.Stdin).ReadBytes('\n')
fmt.Printf("Cleaning up.\n")
containerURL.Delete(ctx, azblob.ContainerAccessConditions{})
file.Close()
os.Remove(fileName)

用于开发包含 Blob 的 Go 应用程序的资源Resources for developing Go applications with blobs

查看以下附加资源,了解如何使用 Blob 存储进行 Go 开发:See these additional resources for Go development with Blob storage:

后续步骤Next steps

本快速入门介绍了如何使用 Go 在本地磁盘和 Azure Blob 存储之间转移文件。In this quickstart, you learned how to transfer files between a local disk and Azure blob storage using Go. 有关 Azure 存储 Blob SDK 的详细信息,请查看源代码API 参考For more information about the Azure Storage Blob SDK, view the Source Code and API Reference.