Java 用 Azure Core 共有ライブラリ - バージョン 1.45.0

[アーティクル]
11/03/2023

Azure Core には、最新の Java Azure SDK クライアントライブラリ用の共有プリミティブ、抽象化、ヘルパーが用意されています。これらのライブラリは、Azure SDK Design Guidelines for Java に従っており、で始まるパッケージ名とで始まるcom.azureazure-モジュール名で簡単に/sdk/storage/azure-storage-blob識別できます。たとえばcom.azure.storage.blobs、ディレクトリ内にあります。 Azure Core を使用したクライアントライブラリの詳細な一覧については、こちらを参照してください。

Azure Core を使用すると、クライアントライブラリで一般的な機能を一貫して公開できるため、これらの API を 1 つのクライアントライブラリで使用する方法を学習すると、他のクライアントライブラリでそれらを使用する方法がわかります。

作業の開始

前提条件

Java Development Kit (JDK) バージョン 8 以降。

パッケージを組み込む

BOM ファイルを含める

ライブラリの一般提供 (GA) バージョンに依存するには、azure-sdk-bom をプロジェクトに含めてください。次のスニペットでは、{bom_version_to_target} プレースホルダーをバージョン番号に置き換えます。 BOM の詳細については、 AZURE SDK BOM README に関するページを参照してください。

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

次に、バージョンタグのない依存関係セクションに直接依存関係を含めます。通常、Azure Core をインストールしたり、Azure Core に依存したりする必要はありません。代わりに、それを使用するクライアントライブラリに依存するときに、ビルドツールによって推移的にダウンロードされます。

<dependencies>
    <dependency>
        <groupId>com.azure</groupId>
        <artifactId>azure-core</artifactId>
    </dependency>
</dependencies>

直接依存関係を含める

BOM に存在しない特定のバージョンのライブラリに依存する場合は、次のように直接依存関係をプロジェクトに追加します。

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-core</artifactId>
    <version>1.45.0</version>
</dependency>

主要な概念

Azure Core (したがって、Azure Core を使用するすべての Azure クライアントライブラリ) の主な概念は次のとおりです。

サービスクライアントの構成 (再試行、ログ記録など) の構成 (HttpTrait<T>など ConfigurationTrait<T>)
HTTP 応答の詳細へのアクセス (Response<T>)。
実行時間の長い操作の呼び出し (PollerFlux<T>)。
ページングと非同期ストリーム (ContinuablePagedFlux<T>)。
サービス要求からのエラーを一貫して報告するための例外。
Azure SDK 資格情報を表す抽象化。
操作のタイムアウト

これらは、以下に示す例を使用して紹介します。

例

を使用した HTTP 応答の詳細へのアクセス `Response<T>`

サービスクライアント には、Azure サービスを呼び出すメソッドがあります。これらのメソッドの サービスメソッドの呼び出しを参照してください。

サービスメソッドは、 共有 Azure Core 型 Response<T>を返すことができます。この型は、サービス呼び出しの逆シリアル化された結果と、サーバーから返される HTTP 応答の詳細の両方にアクセスできるようにします。

を使用した HTTP パイプライン `HttpPipeline`

HttpPipeline は、によって送信される要求を準備するために順番に要求に適用されるの一覧 HttpPipelinePolicy を含むコンストラクトです HttpClient。

例外階層 `AzureException`

AzureException は、Azure Core で使用される階層内のルート例外です。やなどのHttpRequestExceptionHttpResponseException追加の例外は、例外の理由の範囲を減らすために使用されます。

の改ページ位置 `ContinuablePagedFlux<T>`

ContinuablePageFlux は、最初のページ要求をサービスに送信し、コンシューマーが処理を完了するか、すべてのページが使用されるまで、コンシューマーがより多くのデータを要求する際に追加のページを取得することを管理します。

実行時間の長い操作 `PollerFlux<T>`

PollerFlux は、ポーリングが取り消されるか、終了状態に達するまで、最初のサービス要求の送信と修正間隔での更新処理の要求を管理します。

ビルダーの構成

ビルダーは、サービスクライアントと一部 TokenCredential の実装を作成するために使用されます。 HTTP ベースのクライアントや、などのendpointConfigurationより一般的なオプションなどHttpPipelineHttpClient、さまざまなオプションを使用して構成できます。 Spring などのフレームワークへのより簡単な統合を可能にし、すべてのビルダー azure-core でジェネリックメソッドを使用できるようにするために、必要な機能を提供するために実装できる一連のインターフェイスが用意されています。

HttpTrait

HttpTrait<T> には、HTTP ベースのクライアントのキー構成を設定するためのメソッドが含まれています。このインターフェイスを使用すると、、HttpPipeline、s、、RetryOptions、HttpLogOptions、および ClientOptions を構成HttpClientできます (HTTP ベースのサービスクライアントに対してより具体的であるため、お勧めしますHttpClientOptionsHttpPipelinePolicy)。

を公開HttpTrait<T>するビルダーの場合、または HttpClient が設定されていない場合HttpPipelineは、クラスパスの構成に基づいて既定のインスタンスが作成され、ビルダーに基づいてがClientOptions作成されます。これは、環境から読み込まれていないプロキシの使用など、クライアントに固有の動作が必要な場合に混乱を招く可能性があります。これを回避するには、構成がアプリケーションを HttpPipeline 実行している環境に基づいていない場合は、または HttpClient をすべてのクライアントで常に設定することをお勧めします。

資格情報の特徴

Azure Core では、Azure サービスで認証するためのさまざまな資格情報が提供されます。各資格情報の種類には、クライアントビルダーに資格情報を提供するために実装できる対応する特性があります。次の表に、資格情報の特徴と、対応する資格情報の種類を示します。

資格情報の特徴	[資格証明の種類]
`AzureKeyCredentialTrait`	`AzureKeyCredential`
`AzureNamedKeyCredentialTrait`	`AzureNamedKeyCredential`
`AzureSasCredentialTrait`	`AzureSasCredential`
`ConnectionStringCredentialTrait`	`String` (接続文字列に正式な型はありません)
`KeyCredentialTrait`	`KeyCredential`
`TokenCredentialTrait`	`TokenCredential`

ConfigurationTrait

ConfigurationTrait<T> では、サービスクライアントでを設定 Configuration できます。 Configuration を使用すると、環境からの読み込み方法、それをサポートする一部のクライアントビルダーに暗黙的に資格情報を渡す方法 ProxyOptions など、一連のランタイム動作をクライアントビルダーに渡すことができます。

EndpointTrait

EndpointTrait<T> では、サービスクライアントでサービスエンドポイントを設定できます。

操作のタイムアウト

Azure SDK には、API 呼び出しでタイムアウトを構成するための一貫したいくつかの方法が用意されています。各タイムアウトは、Azure SDK と呼び出し元アプリケーションの異なるスコープに影響します。

HTTP タイムアウト

HTTP タイムアウトは、Azure SDK によって提供される最も低いレベルのタイムアウト処理です。これらのタイムアウトは、をビルド HttpClientするとき、または自分で構成せずにサービスクライアントを構築するときにを使用 HttpClientOptions して構成 HttpClient できます。次の表に、HTTP タイムアウト、それを設定するために使用できる対応する HttpClientOptions メソッド、既定値を制御する環境変数、環境値が設定されていない場合の既定値、タイムアウトの影響の簡単な説明を示します。

HTTP タイムアウト	`HttpClientOptions` メソッド	環境変数	既定値	説明
Connect Timeout	`setConnectTimeout(Duration)`	AZURE_REQUEST_CONNECT_TIMEOUT	10 秒	タイムアウトするまでに接続が確立されるまでの時間。
書き込みタイムアウト	`setWriteTimeout(Duration)`	AZURE_REQUEST_WRITE_TIMEOUT	60 秒	タイムアウトするまでの各要求データがネットワークに書き込まれるまでの時間。
応答タイムアウト	`setResponseTimeout(Duration)`	AZURE_REQUEST_RESPONSE_TIMEOUT	60 秒	タイムアウトするまでの最初の応答バイトの受信に対する要求の送信が完了するまでの時間。
読み取りタイムアウト	`setReadTimeout(Duration)`	AZURE_REQUEST_READ_TIMEOUT	60 秒	ネットワークから読み取られた各応答データがタイムアウトするまでの時間。

これらのタイムアウトはネットワークに最も近いため、トリガーされた場合はを介して HttpPipeline 反映され、通常はによって再試行する RetryPolicy必要があります。

HttpPipeline のタイムアウト

HttpPipeline タイムアウトは、Azure SDK によって提供される次のレベルのタイムアウト処理です。これらのタイムアウトは、を使用して HttpPipelinePolicy 構成され、非同期要求の場合 Mono.timeout はを使用してタイムアウトを構成し ExecutorService 、同期要求の場合は get(long, TimeUnit) を使用してタイムアウトを構成します。

内 HttpPipelineの場所によっては、これらのタイムアウトがによって RetryPolicy キャプチャされ、再試行される場合があります。タイムアウトポリシーが (HttpPipelinePolicy.getPipelinePosition()) の場合、タイムアウトは PER_RETRY の後RetryPolicyに配置されるため、によってRetryPolicyキャプチャされます。そのため、要求を再試行する場合はPER_CALL、アプリケーションロジックで処理する必要があります。

サービスクライアントのタイムアウト

サービスクライアントのタイムアウトは、Azure SDK によって提供される最高レベルのタイムアウト処理です。これらのタイムアウトは、タイムアウトをサポートする同期サービスメソッドに渡Duration timeoutすか、非同期サービスメソッドでまたは Flux.timeout を使用Mono.timeoutして構成されます。

これらのタイムアウトは API 呼び出し自体に存在するため、Azure SDK 内の再試行メカニズムではキャプチャできず、アプリケーションロジックで処理する必要があります。

次のステップ

Azure Core を使用して構築された Azure ライブラリの使用を開始します。

トラブルシューティング

バグが発生した場合は、 GitHub の問題を使用して問題を報告するか、 Azure Java SDK の StackOverflow をチェックアウトしてください。

ログ記録の有効化

Azure SDK for Java には、アプリケーションエラーのトラブルシューティングと解決の迅速化に役立つ一貫したログ記録のストーリーが用意されています。生成されたログでは、最終状態に達する前のアプリケーションのフローがキャプチャされ、根本原因を特定するのに役立ちます。ログ記録の有効化に関するガイダンスについては、ログ記録に関するドキュメントを参照してください。

HTTP 要求と応答のログ記録

HTTP 要求と応答のログ記録を有効にするには HttpLogDetailLevel 、HTTP ベースのサービスクライアントの作成に使用するをに HttpLogOptions 設定するか、環境変数またはシステムプロパティ AZURE_HTTP_LOG_DETAIL_LEVELを設定します。次の表に、の有効なオプション AZURE_HTTP_LOG_DETAIL_LEVEL と、それが関連付けられるオプションを示します (有効なオプションでは大文字と HttpLogDetailLevel 小文字が区別されません)。

`AZURE_HTTP_LOG_DETAIL_LEVEL` 値	`HttpLogDetailLevel` 列挙型
`basic`	`HttpLogDetailLevel.BASIC`
`headers`	`HttpLogDetailLevel.HEADERS`
`body`	`HttpLogDetailLevel.BODY`
`body_and_headers`	`HttpLogDetailLevel.BODY_AND_HEADERS`
`bodyandheaders`	`HttpLogDetailLevel.BODY_AND_HEADERS`

その他のすべての値、またはサポートされていない値は、HTTP 要求と応答のログ記録を HttpLogDetailLevel.NONE無効にするか、になります。 HTTP 要求と応答をログに記録するには、ログ記録を有効にする必要があります。 HTTP ヘッダーのログ記録を有効にするには、ログ記録が必要 verbose です。次の表では、各 HttpLogDetailLevelに対して有効になっているログ記録について説明します。

`HttpLogDetailLevel` 値	有効になるログ
`HttpLogDetailLevel.NONE`	HTTP 要求または応答のログ記録なし
`HttpLogDetailLevel.BASIC`	HTTP 要求メソッド、応答状態コード、要求と応答 URL
`HttpLogDetailLevel.HEADERS`	ログレベルがである場合は `HttpLogDetailLevel.BASIC` 、すべてのヘッダーと要求ヘッダーと応答ヘッダー `verbose`
`HttpLogDetailLevel.BODY`	サイズが `HttpLogDetailLevel.BASIC` 10 KB 以下の場合は、すべてのと要求と応答本文
`HttpLogDetailLevel.BODY_AND_HEADERS`	との `HttpLogDetailLevel.HEADERS` すべて `HttpLogDetailLevel.BODY`

共同作成

このリポジトリへの投稿の詳細については、投稿ガイドを参照してください。

フォーク
機能ブランチを作成する (git checkout -b my-new-feature)
変更をコミットする (git commit -am 'Add some feature')
ブランチにプッシュする (git push origin my-new-feature)
新しい Pull Request を作成する

インプレッション数

次の方法で共有

Java 用 Azure Core 共有ライブラリ - バージョン 1.45.0

作業の開始

前提条件

パッケージを組み込む

BOM ファイルを含める

直接依存関係を含める

主要な概念

例

を使用した HTTP 応答の詳細へのアクセス `Response<T>`

を使用した HTTP パイプライン `HttpPipeline`

例外階層 `AzureException`

実行時間の長い操作 `PollerFlux<T>`

ビルダーの構成

HttpTrait

資格情報の特徴

ConfigurationTrait

EndpointTrait

操作のタイムアウト

HTTP タイムアウト

HttpPipeline のタイムアウト

サービスクライアントのタイムアウト

次のステップ

トラブルシューティング

ログ記録の有効化

HTTP 要求と応答のログ記録

共同作成

フィードバック

その他のリソース

次の方法で共有

Java 用 Azure Core 共有ライブラリ - バージョン 1.45.0

作業の開始

前提条件

パッケージを組み込む

BOM ファイルを含める

直接依存関係を含める

主要な概念

例

を使用した HTTP 応答の詳細へのアクセス Response<T>

を使用した HTTP パイプライン HttpPipeline

例外階層 AzureException

の改ページ位置 ContinuablePagedFlux<T>

実行時間の長い操作 PollerFlux<T>

ビルダーの構成

HttpTrait

資格情報の特徴

ConfigurationTrait

EndpointTrait

操作のタイムアウト

HTTP タイムアウト

HttpPipeline のタイムアウト

サービス クライアントのタイムアウト

次のステップ

トラブルシューティング

ログ記録の有効化

HTTP 要求と応答のログ記録

共同作成

フィードバック

その他のリソース

を使用した HTTP 応答の詳細へのアクセス `Response<T>`

を使用した HTTP パイプライン `HttpPipeline`

例外階層 `AzureException`

の改ページ位置 `ContinuablePagedFlux<T>`

実行時間の長い操作 `PollerFlux<T>`

サービスクライアントのタイムアウト