使用 C++ 针对 Azure 文件进行开发

提示

尝试 Azure 存储资源管理器

Azure 存储资源管理器是 Microsoft 免费提供的独立应用,适用于在 Windows、macOS 和 Linux 上以可视方式处理 Azure 存储数据。

适用于

文件共享类型 SMB NFS
标准文件共享 (GPv2)、LRS/ZRS Yes No
标准文件共享 (GPv2)、GRS/GZRS Yes No
高级文件共享 (FileStorage)、LRS/ZRS Yes No

关于本教程

本教程将介绍如何使用 C++ 针对 Azure 文件存储执行基本操作。 如果你不熟悉 Azure 文件存储,请先了解后续部分中的概念,以便理解相关示例。 涵盖的部分示例包括:

  • 创建和删除 Azure 文件共享
  • 创建和删除目录
  • 上传、下载和删除文件
  • 设置和列出文件的元数据

注意

由于 Azure 文件可以通过 SMB 进行访问,因此可以编写简单的应用程序,通过标准的 C++ I/O 类和函数来访问 Azure 文件共享。 本文将介绍如何编写使用 Azure 存储 C++ SDK 的应用程序,该 SDK 使用 文件 REST API 与 Azure 文件通信。

先决条件

设置

本部分逐步指导如何准备一个项目,使其与适用于 C++ 的 Azure Blob 存储客户端库 v12 配合使用。

安装包

vcpkg install 命令将安装适用于 C++ 的 Azure 存储 Blob SDK 和所需的依赖项:

vcpkg.exe install azure-storage-files-shares-cpp:x64-windows

有关详细信息,请访问 GitHub 以获取并生成适用于 C++ 的 Azure SDK

创建项目

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

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

从 Azure 门户复制凭据

当示例应用程序向 Azure 存储发出请求时,必须对其进行授权。 若要对请求进行授权,请将存储帐户凭据以连接字符串形式添加到应用程序中。 若要查看存储帐户凭据,请按以下步骤操作:

  1. 登录 Azure 门户

  2. 找到自己的存储帐户。

  3. 在存储帐户菜单窗格中的“安全性 + 网络”下,选择“访问密钥” 。 在这里,可以查看帐户访问密钥以及每个密钥的完整连接字符串。

    Screenshot that shows where the access key settings are in the Azure portal

  4. 在“访问密钥”窗格中,选择“显示密钥” 。

  5. 在“key1”部分,找到“连接字符串”值 。 选择“复制到剪贴板”图标来复制该连接字符串。 在下一部分,你要将此连接字符串值添加到某个环境变量。

    Screenshot showing how to copy a connection string from the Azure portal

配置存储连接字符串

在复制连接字符串后,请将其写入到运行该应用程序的本地计算机上的新环境变量。 若要设置环境变量,请打开控制台窗口,并遵照适用于操作系统的说明。 将 <yourconnectionstring> 替换为实际的连接字符串。

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

在 Windows 中添加环境变量后,必须启动命令窗口的新实例。

重新启动程序

添加环境变量后,重启需要读取环境变量的任何正在运行的程序。 例如,先重启开发环境或编辑器,然后再继续操作。

代码示例

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

添加包含文件

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

  1. 在 Visual Studio 中打开 FilesShareQuickstartV12.sln 解决方案文件。
  2. 在 Visual Studio 中打开 FilesShareQuickstartV12.cpp 源文件。
  3. 删除 main 中自动生成的所有代码。
  4. 添加 #include 语句。
#include <iostream>
#include <stdlib.h>
#include <vector>

#include <azure/storage/files/shares.hpp>

获取连接字符串

下面的代码从配置存储连接字符串中创建的环境变量中检索存储帐户的连接字符串。

main() 中添加此代码:

// Retrieve the connection string for use with the application. The storage
        // connection string is stored in an environment variable on the machine
        // running the application called AZURE_STORAGE_CONNECTION_STRING.
        // Note that _MSC_VER is set when using MSVC compiler.
        static const char* AZURE_STORAGE_CONNECTION_STRING = "AZURE_STORAGE_CONNECTION_STRING";
#if !defined(_MSC_VER)
        const char* connectionString = std::getenv(AZURE_STORAGE_CONNECTION_STRING);
#else
        // Use getenv_s for MSVC
        size_t requiredSize;
        getenv_s(&requiredSize, NULL, NULL, AZURE_STORAGE_CONNECTION_STRING);
        if (requiredSize == 0) {
            throw std::runtime_error("missing connection string from env.");
        }
        std::vector<char> value(requiredSize);
        getenv_s(&requiredSize, value.data(), value.size(), AZURE_STORAGE_CONNECTION_STRING);
        std::string connectionStringStr = std::string(value.begin(), value.end());
        const char* connectionString = connectionStringStr.c_str();
#endif

创建文件共享

通过调用 CreateFromConnectionString 函数来创建 ShareClient 类的实例。 然后调用 CreateIfNotExists,在存储帐户中创建实际的文件共享。

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

using namespace Azure::Storage::Files::Shares;

std::string shareName = "sample-share";

// Initialize a new instance of ShareClient
auto shareClient = ShareClient::CreateFromConnectionString(connectionString, shareName);

// Create the files share. This will do nothing if the files share already exists.
std::cout << "Creating files share: " << shareName << std::endl;
shareClient.CreateIfNotExists();

将文件上传到文件共享

以下代码片段:

  1. 声明一个包含“Hello Azure!”的字符串。
  2. 获取对 ShareFileClient 对象的引用,方法是获取根 ShareDirectoryClient,然后对创建文件共享部分中创建的文件共享调用 GetFileClient
  3. 调用 UploadFrom 函数,将字符串上传到文件。 如果该文件尚不存在,此函数将创建该文件;如果该文件存在,则更新该文件。

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

std::string fileName = "sample-file";
uint8_t fileContent[] = "Hello Azure!";

// Create the ShareFileClient
ShareFileClient fileClient = shareClient.GetRootDirectoryClient().GetFileClient(fileName);

// Upload the file
std::cout << "Uploading file: " << fileName << std::endl;
fileClient.UploadFrom(fileContent, sizeof(fileContent));

设置文件的元数据

通过调用 ShareFileClient.SetMetadata 函数来设置文件的元数据属性。

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

Azure::Storage::Metadata fileMetadata = { {"key1", "value1"}, {"key2", "value2"} };
fileClient.SetMetadata(fileMetadata);

列出文件的元数据

通过调用 ShareFileClient.GetProperties 函数来获取文件的元数据属性。 元数据位于返回的 ValueMetadata 字段下。 元数据是一个键值对,类似于设置文件的元数据中的示例。

// Retrieve the file properties
auto properties = fileClient.GetProperties().Value;
std::cout << "Listing blob metadata..." << std::endl;
for (auto metadata : properties.Metadata)
{
    std::cout << metadata.first << ":" << metadata.second << std::endl;
}

下载文件

列出文件的元数据中检索文件的属性后,使用上传的文件的属性创建一个新的 std::vector<uint8_t> 对象。 通过调用 ShareFileClient 基类中的 DownloadTo 函数,将前面创建的文件下载到新的 std::vector<uint8_t> 对象。 最后,显示下载的文件数据。

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

std::vector<uint8_t> fileDownloaded(properties.FileSize);
fileClient.DownloadTo(fileDownloaded.data(), fileDownloaded.size());

std::cout << "Downloaded file contents: " << std::string(fileDownloaded.begin(), fileDownloaded.end()) << std::endl;

删除文件

以下代码通过调用 ShareFileClient.Delete 函数,从 Azure 存储文件共享中删除 Blob。

std::cout << "Deleting file: " << fileName << std::endl;
fileClient.DeleteIfExists();

删除文件共享

以下代码使用 ShareClient.Delete 删除整个文件共享,从而清理应用创建的资源。

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

std::cout << "Deleting files share: " << shareName << std::endl;
shareClient.DeleteIfExists();

运行代码

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

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

Azure Files Shares storage v12 - C++ quickstart sample
Creating files share: sample-share
Uploading file: sample-file
Listing file metadata...
key1:value1
key2:value2
Downloaded file contents: Hello Azure!
Deleting file: sample-file
Deleting files share: sample-share

后续步骤

在本快速入门中,你已了解如何使用 C++ 上传、下载和列出文件。 此外,你还了解了如何创建和删除 Azure 存储文件共享。

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