C++ 用 Azure SDK Core ライブラリ

Azure::Core (azure-core) は、C++ で記述された最新の Azure SDK クライアント ライブラリ用の共有プリミティブ、抽象化、ヘルパーを提供します。 これらのライブラリは、 C++ の Azure SDK 設計ガイドラインに従います。

このライブラリを使用すると、クライアント ライブラリは一貫した方法で共通の機能を公開できます。 これらの API を 1 つのクライアント ライブラリで使用する方法を学習したら、それらを他のクライアント ライブラリで使用する方法を学習します。

作業の開始

通常、 azure-coreダウンロードする必要はありません。クライアント ライブラリの依存関係としてダウンロードされます。 (たとえば、独自のクライアント ライブラリを実装するために) 明示的にダウンロードする場合は、ここでソースを見つけたり、vcpkg を使用してパッケージ azure-core-cppをインストールしたりできます。

パッケージを含めてください

C++ SDK を取得する最も簡単な方法は、vcpkg パッケージ マネージャーを利用することです。 対応する C++ 用 Azure SDK の readme セクションを参照してください。

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>を使用して実行時間の長い操作 (LLO) をポーリングする。
  • 基本の例外の種類 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++ では、ネットワーク経由で Azure サービスと通信するための HTTP スタックとして libcurl ライブラリと WinHTTP ライブラリがサポートされています。 SDK には、HTTP トランスポート アダプターのメカニズムも用意されています。 トランスポート アダプターの詳細については、このドキュメントを参照してください。

トラブルシューティング

エラーのトラブルシューティングの主な方法は次の 3 つです。

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 ボットは、CLA を提供し、PR を適切に装飾する必要があるかどうかを自動的に判断します (ラベル、コメントなど)。 ボットによって提供される手順にそのまま従ってください。 これは、CLA を使用するすべてのリポジトリで 1 回だけ行う必要があります。

このプロジェクトは、「Microsoft のオープン ソースの倫理規定」を採用しています。 詳細については、行動規範に関する FAQ を参照するか、その他の質問やコメントを opencode@microsoft.com にお問い合わせください。

世界中の多くの人々がこのプロジェクトをより良くするのに役立っています。 チェックアウトする必要があります。

セキュリティの問題とセキュリティのバグの報告

セキュリティの問題とバグは、Microsoft Security Response Center (MSRC) secure@microsoft.comに電子メールで非公開で報告する必要があります。 24 時間以内に応答を受け取る必要があります。 何らかの理由でそうでない場合は、メールでフォローアップして、元のメッセージを確実に受信したことを確認してください。 MSRC PGP キーを含む詳細については、 Security TechCenter を参照してください。

ライセンス

Azure SDK for C++ は MIT ライセンスで ライセンスされています。

  • 最終更新: