你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn

快速入门:适用于 C++ 的 Azure Blob 存储客户端库

适用于 C++ 的 Azure Blob 存储客户端库入门。 Azure Blob 存储是 Microsoft 提供的适用于云的对象存储解决方案。 请按照以下步骤安装程序包并试用基本任务的示例代码。

| API 参考文档 | 库源代码 | 示例 |

先决条件

设置

本部分逐步指导如何准备一个项目,使其与适用于 C++ 的 Azure Blob 存储客户端库配合使用。 获取适用于 C++ 的 Azure SDK 的最简单方法是使用 vcpkg 包管理器。

安装包

使用 vcpkg install 命令安装适用于 C++ 的 Azure Blob 存储库和必要的依赖项:

vcpkg.exe install azure-storage-blobs-cpp

与 Azure 服务的无密码连接需要 Azure 标识库:

vcpkg.exe install azure-identity-cpp

有关项目设置和使用适用于 C++ 的 Azure SDK 的详细信息,请参阅适用于 C++ 的 Azure SDK 自述文件

创建项目

在 Visual Studio 中,创建新的名为“BlobQuickstart”的适用于 Windows 的 C++ 控制台应用程序。

Visual Studio dialog for configuring a new C++ Windows console app

对象模型

Azure Blob 存储最适合存储巨量的非结构化数据。 非结构化数据是不遵循特定数据模型或定义的数据(如文本或二进制数据)。 Blob 存储提供了三种类型的资源:

  • 存储帐户
  • 存储帐户中的容器
  • 容器中的 blob

以下图示显示了这些资源之间的关系。

Diagram of Blob Storage architecture

使用以下 C++ 类与这些资源进行交互:

  • BlobServiceClientBlobServiceClient 类可用于操纵 Azure 存储资源和 blob 容器。
  • BlobContainerClientBlobContainerClient 类可用于操纵 Azure 存储容器及其 blob。
  • BlobClientBlobClient 类可用于操纵 Azure 存储 blob。 这是所有专用 blob 类的基类。
  • BlockBlobClientBlockBlobClient 类可用于操纵 Azure 存储块 blob。

代码示例

这些示例代码片段演示如何使用适用于 C++ 的 Azure Blob 存储客户端库执行以下任务:

添加包含文件

从项目目录中执行以下操作:

  1. 在 Visual Studio 中打开 BlobQuickstart.sln 解决方案文件
  2. 在 Visual Studio 中,打开 BlobQuickstart.cpp 源文件
  3. 删除自动生成的 main 中的所有代码
  4. 添加 #includeusing namespace 语句
#include <iostream>
#include <azure/core.hpp>
#include <azure/identity/default_azure_credential.hpp>
#include <azure/storage/blobs.hpp>

using namespace Azure::Identity;
using namespace Azure::Storage::Blobs;

向 Azure 进行身份验证并授权访问 Blob 数据

对 Azure Blob 存储的应用程序请求必须获得授权。 要在代码中实现与 Azure 服务(包括 Blob 存储)的无密码连接,推荐使用 azure-identity 客户端库提供的 DefaultAzureCredential 类。

你还可以使用帐户访问密钥授权对 Azure Blob 存储的请求。 但是,应谨慎使用此方法。 开发人员必须尽量避免在不安全的位置公开访问密钥。 具有访问密钥的任何人都可以授权针对存储帐户的请求,并且实际上有权访问所有数据。 DefaultAzureCredential 提供比帐户密钥更好的管理和安全优势,来实现无密码身份验证。 以下示例演示了这两个选项。

Azure 标识库跨 Azure SDK 提供 Microsoft Entra 令牌身份验证支持。 它提供了一组 TokenCredential 实现,可用于构造支持 Microsoft Entra 令牌身份验证的 Azure SDK 客户端。 DefaultAzureCredential 支持多种身份验证方法,并确定应在运行时使用哪种方法。

将角色分配至 Microsoft Entra 用户帐户

在本地开发时,请确保访问 Blob 数据的用户帐户具有正确的权限。 需有“存储 Blob 数据参与者”角色才能读取和写入 Blob 数据。 若要为你自己分配此角色,需要具有“用户访问管理员”角色,或者具有包含 Microsoft.Authorization/roleAssignments/write 操作的其他角色。 可使用 Azure 门户、Azure CLI 或 Azure PowerShell 向用户分配 Azure RBAC 角色。 可以在范围概述页上详细了解角色分配的可用范围。

在此方案中,你将为用户帐户分配权限(范围为存储帐户)以遵循最低权限原则。 这种做法仅为用户提供所需的最低权限,并创建更安全的生产环境。

以下示例将“存储 Blob 数据参与者”角色分配给用户帐户,该角色提供对存储帐户中 Blob 数据的读取和写入访问权限。

重要

在大多数情况下,角色分配在 Azure 中传播需要一两分钟的时间,但极少数情况下最多可能需要 8 分钟。 如果在首次运行代码时收到身份验证错误,请稍等片刻再试。

  1. 在 Azure 门户中,使用主搜索栏或左侧导航找到存储帐户。

  2. 在存储帐户概述页的左侧菜单中选择“访问控制 (IAM)”。

  3. 在“访问控制 (IAM)”页上,选择“角色分配”选项卡。

  4. 从顶部菜单中选择“+ 添加”,然后从出现的下拉菜单中选择“添加角色分配”。

    A screenshot showing how to assign a role.

  5. 使用搜索框将结果筛选为所需角色。 在此示例中,搜索“存储 Blob 数据参与者”并选择匹配的结果,然后选择“下一步”。

  6. 在“访问权限分配对象”下,选择“用户、组或服务主体”,然后选择“+ 选择成员”。

  7. 在对话框中,搜索 Microsoft Entra ID 用户名(通常是 user@domain 电子邮件地址),然后选中对话框底部的“选择”。

  8. 选择“查看 + 分配”转到最后一页,然后再次选择“查看 + 分配”完成该过程。

使用 DefaultAzureCredential 登录并将应用代码连接到 Azure

可按照以下步骤授权访问存储帐户中的数据:

  1. 确保在存储帐户上向将角色分配到的同一 Microsoft Entra 帐户进行身份验证。 可以通过 Azure CLI 进行身份验证。 使用以下命令通过 Azure CLI 登录到 Azure:

    az login
    
  2. 若要使用 DefaultAzureCredential,请确保安装 azure-identity-cpp 包,并添加了以下 #include

    #include <azure/identity/default_azure_credential.hpp>
    
  3. 将此代码添加到 main() 末尾。 当代码在本地工作站上运行时,DefaultAzureCredential 使用 Azure CLI 的开发人员凭据向 Azure 进行身份验证。

    // Initialize an instance of DefaultAzureCredential
     auto defaultAzureCredential = std::make_shared<DefaultAzureCredential>();
    
     auto accountURL = "https://<storage-account-name>.blob.core.windows.net";
     BlobServiceClient blobServiceClient(accountURL, defaultAzureCredential);
    
  4. 确保更新 BlobServiceClient 对象的 URI 中的存储帐户名称。 可以在 Azure 门户的概述页上找到存储帐户名称。

    A screenshot showing how to find the storage account name.

    注意

    在生产环境中使用 C++ SDK 时,建议仅启用你知道应用程序将使用的凭据。 不应使用 DefaultAzureCredential,而是应使用特定凭据类型或使用 ChainedTokenCredential 和支持的凭据来授权。

创建容器

确定新容器的名称。 然后创建 BlobContainerClient 实例并创建容器。

重要

容器名称必须为小写。 有关命名容器和 Blob 的详细信息,请参阅命名和引用容器、Blob 和元数据

将此代码添加到 main() 的末尾:

std::string containerName = "myblobcontainer";
auto containerClient = blobServiceClient.GetBlobContainerClient("myblobcontainer");

// Create the container if it does not exist
std::cout << "Creating container: " << containerName << std::endl;
containerClient.CreateIfNotExists();

将 blob 上传到容器中

以下代码片段:

  1. 声明包含“Hello Azure!”的字符串
  2. 对在创建容器部分创建的容器调用 GetBlockBlobClient,获取对 BlockBlobClient 对象的引用。
  3. 调用 UploadFrom 函数,将字符串上传到 Blob。 此函数将创建 Blob(如果该 Blob 尚不存在),或者更新 Blob(如果该 Blob 已存在)。

将此代码添加到 main() 的末尾:

std::string blobName = "blob.txt";
uint8_t blobContent[] = "Hello Azure!";
// Create the block blob client
BlockBlobClient blobClient = containerClient.GetBlockBlobClient(blobName);

// Upload the blob
std::cout << "Uploading blob: " << blobName << std::endl;
blobClient.UploadFrom(blobContent, sizeof(blobContent));

列出容器中的 blob

通过调用 ListBlobs 函数,列出容器中的 blob。 只向容器添加了一个 blob,所以此操作只返回这一个 blob。

将此代码添加到 main() 的末尾:

std::cout << "Listing blobs..." << std::endl;
auto listBlobsResponse = containerClient.ListBlobs();
for (auto blobItem : listBlobsResponse.Blobs)
{
    std::cout << "Blob name: " << blobItem.Name << std::endl;
}

下载 Blob

获取上传的 Blob 的属性。 然后,使用上传的 blob 的属性,声明新的 std::vector<uint8_t> 对象并调整其大小。 通过在 BlobClient 基类中调用 DownloadTo 函数,将以前创建的 blob 下载到新的 std::vector<uint8_t> 对象。 最后,显示下载的 blob 数据。

将此代码添加到 main() 的末尾:

auto properties = blobClient.GetProperties().Value;
std::vector<uint8_t> downloadedBlob(properties.BlobSize);

blobClient.DownloadTo(downloadedBlob.data(), downloadedBlob.size());
std::cout << "Downloaded blob contents: " << std::string(downloadedBlob.begin(), downloadedBlob.end()) << std::endl;

删除 Blob

以下代码通过调用 BlobClient 函数,从 Azure Blob 存储容器中删除 blob。

std::cout << "Deleting blob: " << blobName << std::endl;
blobClient.Delete();

删除容器

以下代码使用 BlobContainerClient.Delete 来删除整个容器,从而清除该应用创建的资源。

将此代码添加到 main() 的末尾:

std::cout << "Deleting container: " << containerName << std::endl;
containerClient.Delete();

运行代码

此应用将创建一个容器,并将文本文件上传到 Azure Blob 存储。 示例随后列出容器中的 Blob,下载文件并显示文件内容。 最后,应用会删除 blob 和容器。

应用的输出类似于以下示例:

Azure Blob Storage - C++ quickstart sample
Creating container: myblobcontainer
Uploading blob: blob.txt
Listing blobs...
Blob name: blob.txt
Downloaded blob contents: Hello Azure!
Deleting blob: blob.txt
Deleting container: myblobcontainer

后续步骤

本快速入门介绍了如何使用 C++ 上传、下载和列出 Blob。 此外,还介绍了如何创建和删除 Azure Blob 存储容器。

若要查看 C++ Blob 存储示例,请继续参考以下内容: