通过

用于C++的 Azure SDK 核心库

Azure：：Core （azure-core） 为以C++编写的新式 Azure SDK 客户端库提供共享基元、抽象和帮助程序。 这些库遵循 适用于C++的 Azure SDK 设计指南。

该库允许客户端库以一致的方式公开常见功能。 了解如何在一个客户端库中使用这些 API 后，你将了解如何在其他客户端库中使用这些 API。

入门指南

通常，无需下载 azure-core;它将作为客户端库的依赖项下载。 如果要显式下载它（例如实现自己的客户端库），可以在此处找到源，或使用 vcpkg 安装包 azure-core-cpp。

添加包

获取C++ SDK 的最简单方法是利用 vcpkg 包管理器。 请参阅相应的 Azure SDK for C++ 自述文件部分。

若要通过 vcpkg 安装 Azure Core 包，

> vcpkg install azure-core-cpp

然后，在 CMake 文件中使用：

find_package(azure-core-cpp CONFIG REQUIRED)
target_link_libraries(<your project name> PRIVATE Azure::azure-core)

重要概念

主要共享概念 Azure::Core 包括：

  • 处理 BodyStream 流数据和输入/输出（I/O）及其派生类型。
  • 通过 Response<T> 访问任何 SDK 客户端作返回的模型的 HTTP 响应详细信息。
  • 通过 Operation<T>.. 轮询长时间运行的作（LROs）。
  • 通过基本异常类型 RequestFailedException以一致的方式报告服务请求的错误的异常。
  • Azure SDK 凭据的抽象（TokenCredential）。
  • 可替换的 HTTP 传输层，用于通过网络发送请求和接收响应。
  • HTTP 管道和 HTTP 策略（例如重试和日志记录），可通过服务客户端特定的选项进行配置。

长期操作

某些作需要很长时间才能完成，需要轮询其状态。 启动长时间运行的作返回 Operation<T> 类型的方法。

可以间歇性地轮询作是否已完成，方法是使用 Poll() 返回 Operation<T> 的方法，并使用此方法跟踪作 Value()进度。 或者，如果只想等到作完成，则可以使用 PollUntilDone()。

SomeServiceClient client;

auto operation = *client.StartSomeLongRunningOperation();

while (!operation.IsDone())
{
  std::unique_ptr<Http::RawResponse> response = operation.Poll();

  auto partialResult = operation.Value();

  // Your per-polling custom logic goes here, such as logging progress.

  // You can also try to abort the operation if it doesn't complete in time.

  std::this_thread::sleep_for(std::chrono::milliseconds(1000));
}

auto finalResult = operation.Value();

HTTP 传输适配器

现成的 Azure SDK for C++支持 libcurl 和 WinHTTP 库作为 HTTP 堆栈，用于通过网络与 Azure 服务通信。 SDK 还提供 HTTP customer-implemented传输适配器的机制。 可以在此文档中了解有关传输适配器的详细信息。

Troubleshooting

故障排除失败的三种主要方法包括：

SDK 日志消息

启用日志的最简单方法是将环境变量设置为AZURE_LOG_LEVEL以下值之一： ||AZURE_LOG_LEVELAzure::Core::Diagnostics::Logger::Level|日志消息级别 |-|-|-| |4或error或Errorerr| |应用程序不太可能从中恢复的故障的日志记录级别。||3、或 warningwarn|Warning|函数无法执行其预期任务时的日志记录级别。||2、或informational、或 informationinfo|Informational|函数正常运行时的日志记录级别。||1、或 verbosedebug|Verbose|详细故障排除方案的日志记录级别。|

然后，日志消息将输出到控制台（stderr）。 请注意， stderr 可以将消息重定向到如下所示的日志文件中：

在 Windows 上：

myprogram.exe 2> log.txt

在 Linux 或 macOS 上：

./myprogram 2> log.txt

此外，可以通过提供回调函数以编程方式处理日志消息，该函数可以将其保存到文件中，或以所需的自定义方式显示它们。

#include <azure/core/diagnostics/logger.hpp>

int main()
{
    using namespace Azure::Core::Diagnostics;

    // See above for the level descriptions.
    Logger::SetLevel(Logger::Level::Verbose);

    // SetListener accepts std::function<>, which can be either lambda or a function pointer.
    Logger::SetListener([&](auto lvl, auto msg){ /* handle Logger::Level lvl and std::string msg */ });
}

请注意，侦听器回调在触发日志消息的作所在的同一线程上执行。 建议实现，因为回调线程上的日志消息处理量最少。 如果需要消息处理，请考虑以回调将消息字符串推送到线程安全队列的方式实现，以便另一个线程从该队列中选取消息并处理它们。

后续步骤

浏览并安装可用的 Azure SDK 库。

Contributing

有关参与此存储库的详细信息，请参阅 贡献指南。

此项目欢迎贡献和建议。 大多数贡献要求你同意参与者许可协议（CLA），声明你有权（实际这样做）授予我们使用你的贡献的权利。 有关详细信息，请访问 参与者许可协议。

提交拉取请求时，CLA 机器人会自动确定是否需要提供 CLA 并适当修饰 PR（例如标签、注释）。 只需按照机器人提供的说明进行操作。 只需使用 CLA 在所有存储库中执行此操作一次。

该项目已采用 Microsoft开源行为准则。 有关详细信息，请参阅 行为准则常见问题解答 或与 opencode@microsoft.com 联系，了解任何其他问题或意见。

世界各地的许多人都帮助使这个项目变得更好。 需要查看：

报告安全问题和安全 bug

应通过电子邮件向Microsoft安全响应中心（MSRC） secure@microsoft.com私下报告安全问题和 bug。 应在 24 小时内收到响应。 如果出于某种原因你没有这样做，请通过电子邮件跟进，以确保我们收到了你的原始邮件。 可以在 安全技术中心中找到其他信息，包括 MSRC PGP 密钥。

许可证

适用于C++的 Azure SDK 根据 MIT 许可证获得许可。

  • Last updated on