Azure SDK Core Library for C++

Azure：：Core （azure-core） 提供以 C++ 撰寫的現代 Azure SDK 用戶端函式庫的共享原語、抽象與輔助工具。 這些函式庫遵循 Azure SDK C++ 設計指引。

此函式庫允許用戶端函式庫以一致的方式揭露共同功能。 一旦你學會在一個客戶端函式庫中使用這些 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 的共享概念包括：

  • 透過串流資料及輸入/輸出（I/O） BodyStream 及其衍生型別來處理。
  • 透過 存取任何 SDK 用戶端操作回傳模型的 HTTP 回應細節。Response<T>
  • 長期運作（LRO）投票，來源為 Operation<T>。
  • 透過基礎例外類型 RequestFailedException以一致方式報告服務請求錯誤的例外。
  • Abstractions for Azure SDK credentials （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 函式庫，作為透過網路與 Azure 服務通訊的 HTTP 堆疊。 SDK 也提供 customer-implemented的機制。 你可以在這份文件中了解更多關於傳輸轉接器的資訊。

故障排除

故障排除的三種主要方法為：

SDK 日誌訊息

啟用日誌最簡單的方法是將 AZURE_LOG_LEVEL 環境變數設為以下值之一：|AZURE_LOG_LEVEL|Azure::Core::Diagnostics::Logger::Level|日誌訊息層級| |-|-|-| |4，或 error，或 err|Error|應用程式不太可能恢復的失敗日誌層級。|3，或 warning，或 warn|Warning|當函式未能執行預期任務時的日誌層級。|2，或 informational，或 information，或 info|Informational|函數正常運作時的日誌層級。|1，或 verbose，或 debug|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-Bot 會自動判斷您是否需要提供 CLA 並適當裝飾 PR（例如標籤、批註）。 只要遵循 Bot 所提供的指示即可。 您只需要使用我們的 CLA 在所有存放庫上執行此動作一次。

此專案採用了 Microsoft 開放原始碼管理辦法。 如需詳細資訊，請參閱 《行為規範》常見問題 或連絡 opencode@microsoft.com，以取得任何其他問題或意見。

世界各地的許多人都幫助讓這個計畫變得更好。 你會想看看：

報告安全問題與安全漏洞

安全問題與錯誤應私下透過電子郵件向 Microsoft 安全回應中心（MSRC） secure@microsoft.com回報。 您應該會在24小時內收到回覆。 如果由於某種原因您沒有收到，請透過電子郵件跟進，以確保我們收到您的原始訊息。 更多資訊，包括MSRC PGP金鑰，可於 Security TechCenter找到。

許可證

Azure SDK for C++ 採用 MIT 授權。

  • 上次更新時間：