Azure/azure-sdk-for-cpp

# Azure SDK for C++ [](https://dev.azure.com/azure-sdk/public/_build/latest?definitionId=1611&branchName=main) 此仓库用于 Azure SDK for C++ 的活跃开发。对于 SDK 的使用者，我们建议访问我们的[开发者文档](https://azure.github.io/azure-sdk-for-cpp)。 ## 入门指南 Azure SDK for C++ 兼容多种开发环境和工具。以下说明将使用 [Visual Studio](https://visualstudio.microsoft.com/) 或 [VSCode](https://code.visualstudio.com/) 作为 IDE，使用 [CMake](https://cmake.org/) 进行构建自动化，并使用 [vcpkg](https://vcpkg.io/) 作为我们的包管理器。 ### 前置条件 - 一个 Azure 订阅。注册[免费试用](https://azure.microsoft.com/pricing/free-trial/)或使用您的 [MSDN 订阅者权益](https://azure.microsoft.com/pricing/member-offers/msdn-benefits-details/)。 - [一个 C++ 编译器](https://code.visualstudio.com/docs/languages/cpp#_install-a-compiler)。 ### 开发环境和工具设置 - [Visual Studio, CMake 和 vcpkg](https://learn.microsoft.com/vcpkg/get_started/get-started-vs/) - [VS Code, CMake 和 vcpkg](https://learn.microsoft.com/vcpkg/get_started/get-started-vscode/) ### 安装库 - 打开一个终端 - **Visual Studio:** 打开 Developer Command Prompt：**Tools > Commandline > Developer Command Prompt** - **VSCode:** 在 VSCode 中打开一个新的终端：**Terminal > New Terminal** - 使用以下命令添加 `azure-identity-cpp` 和 `azure-storage-blobs-cpp` 库： ``` vcpkg add port azure-identity-cpp azure-storage-blobs-cpp ``` - 您的 `vcpkg.json` 现在应该包含： ``` { "dependencies": [ "azure-identity-cpp", "azure-storage-blobs-cpp" ] } ``` ### 配置 CMake 项目文件 - 将 `CMakeLists.txt` 的内容替换为以下内容： ``` cmake_minimum_required(VERSION 3.10) project(HelloWorld) find_package(azure-identity-cpp CONFIG REQUIRED) find_package(azure-storage-blobs-cpp CONFIG REQUIRED) add_executable(HelloWorld helloworld.cpp) target_link_libraries(HelloWorld PRIVATE Azure::azure-identity Azure::azure-storage-blobs) ``` ### 在 Visual Studio MSBuild (.vcxproj) 项目中安装 Azure SDK 包 这是一个关于如何在 Visual Studio 的 MSBuild 项目中使用 vcpkg 安装 Azure SDK 包的演示视频：https://aka.ms/azsdk/cpp/gettingstarted-vcpkg-msbuild-video 有关更多详细信息，请参阅 [vcpkg 文档](https://learn.microsoft.com/vcpkg/get_started/get-started-msbuild?pivots=shell-cmd)。 ### 其他安装和配置方法 - [CMake 项目和 fetch content](https://github.com/Azure/azure-sdk-for-cpp/tree/main/samples/integration/cmake-fetch-content/) - [如何使用 beta 包](https://github.com/Azure/azure-sdk-for-cpp/tree/main/samples/integration/beta-packages-vcpkg/) ### 在您的应用程序中使用 SDK 使用 SDK 时，大多数场景的**入口点**是一个对应于 Azure 服务的顶级客户端类型。例如，向 Blob 存储发送请求可以通过 `Azure::Storage::Blobs::BlobClient` API 完成。客户端类型上的所有 API 都向云服务发送 HTTP 请求，并返回一个 HTTP `Response`。 所需的 Azure C++ SDK 头文件位于 `` 文件夹中，其中包含对应于每个服务的子文件夹。同样，所有类型和 API 都可以在 `Azure::` 命名空间中找到。例如，要使用 `Azure::Core` 中的功能，请在应用程序的开头包含以下头文件 `#include `。 这是一个帮助您入门的示例应用程序： ``` #include // Include the necessary SDK headers #include #include // Add appropriate using namespace directives using namespace Azure::Storage; using namespace Azure::Storage::Blobs; // Secrets should be stored & retrieved from secure locations such as Azure::KeyVault. For // convenience and brevity of samples, the secrets are retrieved from environment variables. std::string GetEndpointUrl() { return std::getenv("AZURE_STORAGE_ACCOUNT_URL"); } std::string GetAccountName() { return std::getenv("AZURE_STORAGE_ACCOUNT_NAME"); } std::string GetAccountKey() { return std::getenv("AZURE_STORAGE_ACCOUNT_KEY"); } int main() { std::string endpointUrl = GetEndpointUrl(); std::string accountName = GetAccountName(); std::string accountKey = GetAccountKey(); try { auto sharedKeyCredential = std::make_shared(accountName, accountKey); auto blockBlobClient = BlockBlobClient(endpointUrl, sharedKeyCredential); // Create some data to upload into the blob. std::vector data = {1, 2, 3, 4}; Azure::Core::IO::MemoryBodyStream stream(data); Azure::Response response = blockBlobClient.Upload(stream); Models::UploadBlockBlobResult model = response.Value; std::cout << "Last modified date of uploaded blob: " << model.LastModified.ToString() << std::endl; } catch (const Azure::Core::RequestFailedException& e) { std::cout << "Status Code: " << static_cast(e.StatusCode) << ", Reason Phrase: " << e.ReasonPhrase << std::endl; std::cout << e.what() << std::endl; return 1; } return 0; } ``` ### 构建并运行项目 - **Visual Studio:** 在 Visual Studio 中按 `Ctrl+Shift+B` 构建项目。然后点击运行播放按钮。 - **VSCode:** 使用 `Ctrl+Shift+P` 打开命令面板并运行 `CMake: Build` 命令。选择 `default` CMake 预设。然后启动项目。 ## 核心 Core 概念 了解 `Azure Core` 库中的关键概念对于入门非常有帮助，所有客户端库都利用了该库，无论您想使用哪种 Azure 服务。 `Azure Core` 的主要共享概念包括： - 通过 `Response` 访问任何 SDK 客户端操作返回模型的 HTTP 响应详细信息。 - 通过基础异常类型 `RequestFailedException` 以一致的方式报告服务请求错误的异常。 - Azure SDK 凭证 (`TokenCredential`) 的抽象。 - 通过 `BodyStream` 及其派生类型处理流数据和输入/输出 (I/O)。 - 通过 `Operation` 轮询长时间运行的操作。 - 通过 `PagedResponse` 返回集合。 - HTTP 管道和 HTTP 策略（如重试和日志记录），可通过服务客户端特定选项进行配置。 - 可替换的 HTTP 传输层，用于通过网络发送请求和接收响应。 #### `Response ` 模型类型 许多客户端库操作从 API 调用中**返回**模板化的 `Azure::Core::Response` 类型。此类型允许您从 Azure 服务 API 进行的服务请求调用中获取原始 HTTP 响应，以及操作结果以获取更多特定于 API 的详细信息。这是模板化的 `T` 操作结果，可以使用 `Value` 字段从响应中提取。 ``` // Azure service operations return a Response templated type. Azure::Response propertiesResponse = blockBlobClient.GetProperties(); // You can get the T, from the returned Response, // which is typically named with a Result suffix in the type name. Models::BlobProperties propertiesModel = propertiesResponse.Value; // Now you can look at API specific members on the result object that is returned. std::cout << "The size of the blob is: " << propertiesModel.BlobSize << std::endl; ``` #### 长时间运行的操作 某些操作需要很长时间才能完成，需要轮询其状态。启动长时间运行的操作的方法返回 `Operation` 类型。 您可以间歇性地在返回的 `Operation` 上使用循环内的 `Poll()` 方法来轮询操作是否已完成，并在操作未完成（使用 `IsDone()`）时使用 `Value()` 跟踪操作进度。您的每次轮询的自定义逻辑可以放在该循环中，例如记录进度。或者，如果您只想等待操作完成，可以使用 `PollUntilDone()`。 ``` std::string sourceUri = ""; // Typically, long running operation APIs have names that begin with Start. StartBlobCopyOperation operation = blockBlobClient.StartCopyFromUri(sourceUri); // Waits for the operation to finish, checking for status every 1 second. auto copyResponse = operation.PollUntilDone(std::chrono::milliseconds(1000)); auto propertiesModel = copyResponse.Value; // Now you can look at API specific members on the result object that is returned. if (propertiesModel.CopySource.HasValue()) { std::cout << "The source of the copied blob is: " << propertiesModel.CopySource.Value() << std::endl; } ``` #### `Azure::Core::Context` 大多数 Azure SDK 服务客户端方法接受一个可选的 `Azure::Core::Context` 参数，该参数用于启用操作的取消或为操作设定绝对截止时间。 当您希望为操作分配时间限制以确保其在“合理”的时间范围内完成时，这非常有用。例如，下面的代码片段将在 5 秒后取消 Blob 客户端上传。 ``` Azure::Core::Context cancelledIn5s{ std::chrono::system_clock::now() + std::chrono::seconds(5)}; auto containerClient = BlobContainerClient::CreateFromConnectionString( GetConnectionString(), containerName + std::to_string(i)); containerClient.CreateIfNotExists({}, cancelledIn5s); for (int j = 0; j < 3; ++j) { BlockBlobClient blobClient = containerClient.GetBlockBlobClient(blobName + std::to_string(j)); blobClient.UploadFrom( reinterpret_cast(blobContent.data()), blobContent.size(), {}, cancelledIn5s); } ``` `Context` 对象也可以使用 `Cancel()` 方法直接取消。 `Context` 对象形成有向树，其中子上下文可以从父上下文创建。 上下文树是单向且非循环的。 这些是可以在 `Context` 对象上执行的基本操作： * 使用键/值对从父上下文创建子上下文。这对于将元数据与上下文关联很有用。 * 使用截止时间从父上下文创建子上下文。这对于设置超时很有用。 * 取消上下文。这将取消该上下文及其所有子上下文。请注意，无法取消已取消的上下文。 * 检查上下文是否已取消。 当一个上下文是从另一个上下文复制而来时，复制的上下文将与原始上下文共享状态。 这意味着如果原始上下文被取消，复制的上下文也将被取消。 `Context` 的取消是永久性操作。一旦上下文被取消，就无法取消其取消状态。 当客户端操作因 `Azure::Core::OperationCancelledException` 而失败时，通常是由于 `Context` 被取消。应用程序可以捕获并处理此异常。 #### 公共、私有和内部类型 在大多数情况下，Azure SDK for C++ 中定义的 API 分为三类： - **公共**：这些是旨在供 SDK 使用者使用的类型。 它们是公共 API 的一部分并且是稳定的。将尽可能避免对这些类型进行破坏性更改。 所有公共类型和函数都位于 `Azure` 根命名空间中。 - **内部**：这些是 SDK 内部包使用的类型。 它们旨在供组成 Azure SDK 的包使用。它们并非旨在供 SDK 使用者使用。 在特定约束下，允许对这些类型进行破坏性更改。这些类型位于 `_internal` 终端命名空间内的 `Azure` 命名空间中（例如，`Azure::Core::Http::Policies::_internal::RequestActivityPolicy`）。 - **私有**：这些是单个 Azure SDK 包内部使用的类型。 它们不旨在供 SDK 使用者或其他 SDK 包使用。允许对这些类型进行破坏性更改。 这些类型位于 `_detail` 终端命名空间内的 `Azure` 命名空间中。 在源代码树中，内部类型通常在名为 "internal" 的目录中声明，而私有类型通常在名为 "private" 的目录中声明。 #### 与 Azure SDK for C++ 交互 在静态初始化阶段完成之前，不应访问静态 SDK 成员，也不应调用 SDK 函数。 #### Visual Studio - CMakeSettings.json 通过 Visual Studio 构建应用程序时，您可以创建和更新 `CMakeSettings.json` 文件并包含以下属性，以让 Visual Studio 知道包的安装位置以及需要使用的 triplet： ``` { "configurations": [ { "cmakeToolchain": "/vcpkg/scripts/buildsystems/vcpkg.cmake", "variables": [ { "name": "VCPKG_TARGET_TRIPLET", "value": "x64-windows", "type": "STRING" } ] } ] } ``` ### Azure 要求 要调用 Azure 服务，您首先必须拥有一个 Azure 订阅。注册[免费试用](https://azure.microsoft.com/pricing/free-trial/)或使用您的 [MSDN 订阅者权益](https://azure.microsoft.com/pricing/member-offers/msdn-benefits-details/)。 ## 可用包 每个服务可能有多个可用的库。这些库遵循 [Azure SDK Design Guidelines for C++](https://azure.github.io/azure-sdk/cpp_introduction.html) 并共享许多核心功能，例如 HTTP 重试、日志记录、传输协议、身份验证协议等，因此一旦您学会如何在某个客户端库中使用这些功能，您就会知道如何在其他客户端库中使用它们。您可以在 [Azure::Core](https://github.com/Azure/azure-sdk-for-cpp/blob/main/sdk/core/azure-core/README.md) 了解这些共享功能。 可以通过其文件夹、包和命名空间使用的命名来识别客户端库。每个都以 `azure` 开头，后跟服务类别，然后是服务名称。例如 `azure-storage-blobs`。 有关可用包的完整列表，请参阅[最新可用包](https://azure.github.io/azure-sdk/releases/latest/#c)页面。 ### Vcpkg 以下 SDK 库版本在 [vcpkg](https://github.com/microsoft/vcpkg) 上可用： - `azure-core-cpp` - `azure-identity-cpp` - `azure-security-attestation-cpp` - `azure-security-keyvault-certificates-cpp` - `azure-security-keyvault-keys-cpp` - `azure-security-keyvault-secrets-cpp` - `azure-storage-blobs-cpp` - `azure-storage-files-datalake-cpp` - `azure-storage-files-shares-cpp` - `azure-storage-queues-cpp` ## OpenSSL 版本 Azure SDK for C++ 中的多个包使用 OpenSSL 库。默认情况下，Azure SDK 将使用 VCPKG 仓库中最新版本的 OpenSSL。 ### 使用特定版本的 OpenSSL 如果您需要使用特定版本的 OpenSSL，可以使用 vcpkg 自定义 ports 功能来指定要使用的 OpenSSL 版本。 例如，如果您想使用 OpenSSL 1.1.1，您应该在 vcpkg.json 文件旁边创建一个名为 `vcpkg-custom-ports` 的文件夹。 导航到您克隆的 vcpkg vcpkg 仓库并执行 "git checkout 3b3bd424827a1f7f4813216f6b32b6c61e386b2e" - 这会将您的仓库重置为 vcpkg 中 OpenSSL 1.1.1 的最后一个版本。 然后，将 vcpkg 仓库中 `ports/openssl` 文件夹的内容复制到您之前创建的 `vcpkg-custom-ports` 文件夹中： ``` cd git checkout 3b3bd424827a1f7f4813216f6b32b6c61e386b2e cd ports cp -r openssl ``` 这会将 OpenSSL 1.1.1n 的端口信息复制到您的 vcpkg-custom-ports 目录。 完成后，您可以使用 vcpkg 工具安装 OpenSSL 1.1.1n 的自定义端口： ``` vcpkg install --overlay-ports= ``` 如果您使用 CMAKE 进行构建，可以使用以下命令行开关指示 CMAKE 应用覆盖端口： ``` cmake -DVCPKG_MANIFEST_MODE=ON -DVCPKG_OVERLAY_PORTS= -DVCPKG_MANIFEST_DIR= ``` 此外，如果您需要从动态链接库/共享对象使用 OpenSSL，您可以设置 VCPKG triplet 以反映您希望使用动态条目构建库。根据您是想使用静态还是动态版本的 OpenSSL，将 VCPKG_您可以将环境变量设置为 `x64-windows-static` 或 `x64-windows-dynamic`。 同样，您可以使用 x64-linux-dynamic 和 x64-linux-static triplet 来指定将库作为共享对象或动态库使用。 ### 使用系统包管理器安装 OpenSSL 如果您使用的 Linux 发行版使用系统包管理器来安装库，您可以使用系统包管理器来安装 OpenSSL。 vcpkg 团队有一个[功能](https://devblogs.microsoft.com/cppblog/using-system-package-manager-dependencies-with-vcpkg/)，允许您使用系统包管理器来安装依赖项。 ## 需要帮助 - 如需参考文档，请访问 [Azure SDK for C++ 文档](https://azure.github.io/azure-sdk-for-cpp)。 - 如需教程、示例、快速入门和其他文档，请访问 [Azure for C++ Developers](https://learn.microsoft.com/azure/)。 - 通过 [GitHub Issues](https://github.com/Azure/azure-sdk-for-cpp/issues/new/choose) 提交问题。 ## 浏览仓库 ### Main 分支 main 分支包含具有新功能和错误修复的最新代码。它**不**代表最新发布的 **beta** 或 **GA** SDK。 ### 发布分支（Release tagging） 对于我们发布的每个包，都会创建一个唯一的 Git 标签，其中包含包的名称和版本，以标记生成该包的代码提交。此标签将通过修补程序分支进行维护，以及用于调试特定 beta 或稳定版本的代码。 发布标签的格式为 `_`。有关更多信息，请参阅[我们的分支策略](https://github.com/Azure/azure-sdk/blob/main/docs/policies/repobranching.md#release-tagging)。 ### 贡献者其他有用链接 世界各地的许多人都帮助改进了这个项目。您需要查看： - [对于仓库贡献者来说，哪些是好的首个问题？](https://github.com/azure/azure-sdk-for-cpp/issues?q=is%3Aopen+is%3Aissue+label%3A%22up+for+grabs%22) - [如何构建和测试您的更改](https://github.com/Azure/azure-sdk-for-cpp/blob/main/CONTRIBUTING.md#developer-guide) - [您如何实现更改！](https://github.com/Azure/azure-sdk-for-cpp/blob/main/CONTRIBUTING.md#pull-requests) - 详细 [Azure SDK for C++ wiki](https://github.com/azure/azure-sdk-for-cpp/wiki) 中的常见问题 (FAQ) 和概念主题。 ### 报告安全问题和安全漏洞 安全问题和漏洞应通过电子邮件私下报告给 Microsoft Security Response Center (MSRC) 。您应该在 24 小时内收到回复。如果由于某种原因您没有收到，请通过电子邮件跟进以确保我们收到了您的原始消息。更多信息，包括 MSRC PGP 密钥，可以在 [Security TechCenter](https://www.microsoft.com/msrc/faqs-report-an-issue) 中找到。 ### 数据收集 该软件可能会收集有关您和您使用该软件的信息，并将其发送给 Microsoft。Microsoft 可能会使用此信息来提供服务并改进我们的产品和服务。您可以按照下文所述关闭遥测。您可以在帮助文档和 Microsoft 的[隐私声明](https://go.microsoft.com/fwlink/?LinkID=824704)中了解更多关于数据收集和使用的信息。有关 Azure SDK 收集的数据的更多信息，请访问[遥测指南](https://azure.github.io/azure-sdk/general_azurecore.html#telemetry-policy)页面。 ### 遥测配置 遥测收集默认开启。 要选择退出，您可以在客户端构建时禁用遥测。在您的应用程序中创建自定义 HTTP 策略使您能够访问随每个请求发送的标头，从而允许您删除包含客户端遥测的 `User-Agent` 标头。要使用该策略，您需要将其作为客户端创建的一部分添加到特定客户端的选项中。这将禁用客户端中所有方法的 Azure SDK 遥测。您需要为创建的每个客户端注册该策略。 示例策略实现如下所示： ``` class RemoveUserAgentPolicy : public HttpPolicy { private: std::unique_ptr Send( Request& request, NextHttpPolicy nextPolicy, Context const& context) const override { // Set your own User-Agent header or set an empty one to suppress telemetry request.SetHeader("User-Agent", ""); return nextPolicy.Send(request, context); } std::unique_ptr Clone() const override { return std::make_unique(*this); } }; ``` 要将其与客户端一起使用，您需要将其注册为客户端选项的一部分，以便在每个操作中运行： ``` Uri serviceEndpoint = ""; std::shared_ptr credential = std::make_shared(); BlobClientOptions clientOptions; clientOptions.PerOperationPolicies.emplace_back(std::make_unique()); BlobServiceClient client(serviceEndpoint, credential, clientOptions); ``` 您还可以通过设置应用程序标识符来自定义遥测信息，该标识符将被添加到 User-Agent 标头的前面： ``` // Add application ID to client options for telemetry BlobClientOptions clientOptions; clientOptions.Telemetry.ApplicationId = "MyApplication/1.0.0"; auto blobServiceClient = BlobServiceClient::CreateFromConnectionString(connectionString, clientOptions); ``` ### 许可证 Azure SDK for C++ 根据 [MIT](https://github.com/Azure/azure-sdk-for-cpp/blob/main/LICENSE.txt) 许可证授权。 ### 商标 该项目可能包含项目、产品或服务的商标或徽标。授权使用 Microsoft 商标或徽标须遵守并必须遵循 [Microsoft 商标与品牌指南](https://www.microsoft.com/legal/intellectualproperty/trademarks/usage/general)。在修改版本的项目中使用 Microsoft 商标或徽标不得引起混淆或暗示 Microsoft 赞助。任何第三方商标或徽标的使用受制于这些第三方的政策。