CosmosClientBuilder クラス

  • java.lang.Object
    • com.azure.cosmos.CosmosClientBuilder

実装

public class CosmosClientBuilder
implements TokenCredentialTrait<CosmosClientBuilder>, AzureKeyCredentialTrait<CosmosClientBuilder>, EndpointTrait<CosmosClientBuilder>

Azure Cosmos データベース サービスの論理表現としてビルドおよびCosmosClientインスタンスを作成CosmosAsyncClientするヘルパー クラス。

CosmosAsyncClient と CosmosClient はスレッド セーフです。 アプリケーションの有効期間ごとに CosmosClient または CosmosAsyncClient の 1 つのインスタンスを維持することをお勧めします。これにより、効率的な接続管理とパフォーマンスが可能になります。 CosmosAsyncClient と CosmosClient の初期化は、大量の操作です。資格情報やネットワーク接続の検証として、CosmosAsyncClient インスタンスまたは CosmosClient インスタンスの初期化を使用しないでください。

クライアントをビルドする場合、endpoint() と key() は必須の API であり、これらの初期化は失敗します。

consistencyLevel は必須ではありませんが、クライアントを構築するときは、この API に注意を払うことを強くお勧めします。 既定では、何も指定されていない場合は、アカウントの整合性レベルが使用されます。

既定では、直接接続モードは指定されていない場合に使用されます。

Building Cosmos Async Client minimal APIs (without any customized configurations)
 
 CosmosAsyncClient client = new CosmosClientBuilder()
         .endpoint(serviceEndpoint)
         .key(key)
         .buildAsyncClient();
Building Cosmos Async Client with customizations
 
 CosmosAsyncClient client = new CosmosClientBuilder()
         .endpoint(serviceEndpoint)
         .key(key)
         .directMode(directConnectionConfig, gatewayConnectionConfig)
         .consistencyLevel(ConsistencyLevel.SESSION)
         .connectionSharingAcrossClientsEnabled(true)
         .contentResponseOnWriteEnabled(true)
         .userAgentSuffix("my-application1-client")
         .preferredRegions(Collections.singletonList("West US", "East US"))
         .buildAsyncClient();
Building Cosmos Sync Client minimal APIs (without any customized configurations)
 
 CosmosClient client = new CosmosClientBuilder()
         .endpoint(serviceEndpoint)
         .key(key)
         .buildClient();
Building Cosmos Sync Client with customizations
 
 CosmosClient client = new CosmosClientBuilder()
         .endpoint(serviceEndpoint)
         .key(key)
         .directMode(directConnectionConfig, gatewayConnectionConfig)
         .consistencyLevel(ConsistencyLevel.SESSION)
         .connectionSharingAcrossClientsEnabled(true)
         .contentResponseOnWriteEnabled(true)
         .userAgentSuffix("my-application1-client")
         .preferredRegions(Collections.singletonList("West US", "East US"))
         .buildClient();

コンストラクターの概要

コンストラクター 説明
CosmosClientBuilder()

新しい Cosmos クライアント ビルダーをインスタンス化します。

メソッドの概要

修飾子と型 メソッドと説明
CosmosClientBuilder authorizationTokenResolver(CosmosAuthorizationTokenResolver cosmosAuthorizationTokenResolver)

トークン リゾルバーを設定します

CosmosAsyncClient buildAsyncClient()

指定されたプロパティを使用して Cosmos 非同期クライアントを構築します

CosmosClient buildClient()

指定されたプロパティを使用して Cosmos 同期クライアントを構築します

CosmosClientBuilder clientTelemetryConfig(CosmosClientTelemetryConfig telemetryConfig)

このビルダーのクライアント テレメトリ構成インスタンスを返します

CosmosClientBuilder clientTelemetryEnabled(boolean clientTelemetryEnabled)

フラグを設定して、データベース操作の集計統計、cpu/memory などのシステム情報を定期的に収集し、Cosmos 監視サービスに送信するクライアント テレメトリを有効にします。これは、デバッグ中に役立ちます。

CosmosClientBuilder connectionSharingAcrossClientsEnabled(boolean connectionSharingAcrossClientsEnabled)

複数の Cosmos クライアント間での接続の共有を有効にします。

CosmosClientBuilder consistencyLevel(ConsistencyLevel desiredConsistencyLevel)

使用する を ConsistencyLevel 設定します。既定では、 SESSION 整合性が使用されます。

CosmosClientBuilder contentResponseOnWriteEnabled(boolean contentResponseOnWriteEnabled)

CosmosItem に対する作成、更新、および削除操作の場合にのみ、Cosmos DB 応答でヘッダーと状態コードを返すようにブール値を設定します。

CosmosClientBuilder credential(AzureKeyCredential credential)

使用する を設定します。AzureKeyCredential

CosmosClientBuilder credential(TokenCredential credential)

サービスに TokenCredential 送信される要求を承認するために使用する を設定します。

CosmosClientBuilder directMode()

使用する既定の DIRECT 接続構成を設定します。

CosmosClientBuilder directMode(DirectConnectionConfig directConnectionConfig)

使用する DIRECT 接続構成を設定します。

CosmosClientBuilder directMode(DirectConnectionConfig directConnectionConfig, GatewayConnectionConfig gatewayConnectionConfig)

使用する DIRECT 接続構成を設定します。

CosmosClientBuilder endToEndOperationLatencyPolicyConfig(CosmosEndToEndOperationLatencyPolicyConfig cosmosEndToEndOperationLatencyPolicyConfig)

クライアントで を設定します。CosmosEndToEndOperationLatencyPolicyConfig

CosmosClientBuilder endpoint(String endpoint)

SDK が接続する Azure Cosmos DB エンドポイントを設定します

CosmosClientBuilder endpointDiscoveryEnabled(boolean endpointDiscoveryEnabled)

geo レプリケートされたデータベース アカウントのエンドポイント検出を有効にするフラグを設定します。

CosmosClientBuilder excludedRegionsSupplier(Supplier<CosmosExcludedRegions> excludedRegionsSupplier)

Supplierが呼び出されたときにSupplier#get()インスタンスを返す をCosmosExcludedRegions設定します。

CosmosClientBuilder gatewayMode()

使用する既定のゲートウェイ接続構成を設定します。

CosmosClientBuilder gatewayMode(GatewayConnectionConfig gatewayConnectionConfig)

使用するゲートウェイ接続構成を設定します。

CosmosClientBuilder key(String key)

リソースにアクセスするための認証を実行するために使用されるマスター キーまたは読み取り専用キーを設定します。

CosmosClientBuilder multipleWriteRegionsEnabled(boolean multipleWriteRegionsEnabled)

フラグを設定して、Azure Cosmos DB サービス内の geo レプリケートされたデータベース アカウントの任意のリージョンでの書き込みを有効にします。

CosmosClientBuilder openConnectionsAndInitCaches(CosmosContainerProactiveInitConfig proactiveContainerInitConfig)

CosmosContainerProactiveInitConfigから取得getCosmosContainerIdentities()したコンテナーに関連付けられているキャッシュと接続のウォームアップを有効にする を、k が に評価される最初の k 優先リージョンから取得したレプリカにgetProactiveConnectionRegionsCount()設定します。

CosmosClientBuilder permissions(List<CosmosPermissionProperties> permissions)

アクセス許可リストを設定します。このリストには、リソースへのアクセスに必要なリソース トークンが含まれます。

CosmosClientBuilder preferredRegions(List<String> preferredRegions)

geo レプリケートされたデータベース アカウントの優先リージョンを設定します。

CosmosClientBuilder readRequestsFallbackEnabled(boolean readRequestsFallbackEnabled)

Azure Cosmos DB サービスのアカウントで構成された複数のリージョンへの読み取りを許可するかどうかを設定します。

CosmosClientBuilder resourceToken(String resourceToken)

リソースにアクセスするための認証を実行するために使用するリソース トークンを設定します。

CosmosClientBuilder sessionCapturingOverrideEnabled(boolean sessionCapturingOverrideEnabled)

セッション キャプチャは、 に対 SESSIONして既定で有効になっています。

CosmosClientBuilder sessionRetryOptions(SessionRetryOptions sessionRetryOptions)

クライアント上の SessionRetryOptions インスタンスを設定します。

CosmosClientBuilder throttlingRetryOptions(ThrottlingRetryOptions throttlingRetryOptions)

ドキュメントクライアント インスタンスに関連付けられている再試行ポリシー オプションを設定します。

CosmosClientBuilder userAgentSuffix(String userAgentSuffix)

は、ユーザー エージェント サフィックスの値を設定します。

メソッドの継承元: java.lang.Object

コンストラクターの詳細

CosmosClientBuilder

public CosmosClientBuilder()

新しい Cosmos クライアント ビルダーをインスタンス化します。

メソッドの詳細

authorizationTokenResolver

public CosmosClientBuilder authorizationTokenResolver(CosmosAuthorizationTokenResolver cosmosAuthorizationTokenResolver)

トークン リゾルバーを設定します

Parameters:

cosmosAuthorizationTokenResolver - トークン リゾルバー

Returns:

現在の cosmosClientBuilder

buildAsyncClient

public CosmosAsyncClient buildAsyncClient()

指定されたプロパティを使用して Cosmos 非同期クライアントを構築します

Returns:

CosmosAsyncClient

buildClient

public CosmosClient buildClient()

指定されたプロパティを使用して Cosmos 同期クライアントを構築します

Returns:

CosmosClient

clientTelemetryConfig

public CosmosClientBuilder clientTelemetryConfig(CosmosClientTelemetryConfig telemetryConfig)

このビルダーのクライアント テレメトリ構成インスタンスを返します

Parameters:

telemetryConfig - 使用するクライアント テレメトリ構成

Returns:

現在の CosmosClientBuilder

clientTelemetryEnabled

public CosmosClientBuilder clientTelemetryEnabled(boolean clientTelemetryEnabled)

フラグを設定して、データベース操作の集計統計、cpu/memory などのシステム情報を定期的に収集し、Cosmos 監視サービスに送信するクライアント テレメトリを有効にします。これは、デバッグ中に役立ちます。

既定値は false で、これはオプトイン機能であり、既定ではテレメトリ収集がないことを示します。

Parameters:

clientTelemetryEnabled - フラグを設定して、クライアント テレメトリを有効にします。

Returns:

現在の CosmosClientBuilder

connectionSharingAcrossClientsEnabled

public CosmosClientBuilder connectionSharingAcrossClientsEnabled(boolean connectionSharingAcrossClientsEnabled)

複数の Cosmos クライアント間での接続の共有を有効にします。 既定値は false です。

CosmosAsyncClient client1 = new CosmosClientBuilder()
         .endpoint(serviceEndpoint1)
         .key(key1)
         .consistencyLevel(ConsistencyLevel.SESSION)
         .connectionSharingAcrossClientsEnabled(true)
         .buildAsyncClient();

 CosmosAsyncClient client2 = new CosmosClientBuilder()
         .endpoint(serviceEndpoint2)
         .key(key2)
         .consistencyLevel(ConsistencyLevel.SESSION)
         .connectionSharingAcrossClientsEnabled(true)
         .buildAsyncClient();

 // when configured this way client1 and client2 will share connections when possible.

同じ JVM に複数の Cosmos アカウントと対話する Cosmos Client のインスタンスが複数あるときは、これを有効にすると、Cosmos Client のインスタンス間で、実行できる場合に直接モードで接続の共有を実行できます。 このオプションを設定すると、最初にインスタンス化されたクライアントの接続構成 (ソケット タイムアウト構成、アイドル タイムアウト構成など) が、他のすべてのクライアント インスタンスに使用されることに注意してください。

Parameters:

connectionSharingAcrossClientsEnabled - 接続の共有

Returns:

current cosmosClientBuilder

consistencyLevel

public CosmosClientBuilder consistencyLevel(ConsistencyLevel desiredConsistencyLevel)

使用する を ConsistencyLevel 設定します。既定では、 SESSION 整合性が使用されます。

Parameters:

desiredConsistencyLevel - ConsistencyLevel

Returns:

現在のビルダー

contentResponseOnWriteEnabled

public CosmosClientBuilder contentResponseOnWriteEnabled(boolean contentResponseOnWriteEnabled)

CosmosItem に対する作成、更新、および削除の操作の場合にのみ、Cosmos DB 応答でヘッダーと状態コードを返すようにブール値を設定します。 false (既定) に設定した場合、サービスは応答でペイロードを返しません。 ネットワーク経由でペイロードを返送せず、クライアントでシリアル化することで、ネットワークと CPU の負荷を軽減します。 この機能は、読み取り操作または書き込み操作の RU 使用量には影響しません。 既定では、これは false です。

Parameters:

contentResponseOnWriteEnabled - ペイロードが応答に含まれるかどうかを示すブール値

Returns:

current cosmosClientBuilder

credential

public CosmosClientBuilder credential(AzureKeyCredential credential)

使用する を設定します。AzureKeyCredential

Parameters:

credential - AzureKeyCredential

Returns:

current cosmosClientBuilder

credential

public CosmosClientBuilder credential(TokenCredential credential)

サービスに TokenCredential 送信される要求を承認するために使用する を設定します。 型の適切な使用方法の詳細については、Azure SDK for Java の ID と認証 に関するドキュメントを TokenCredential 参照してください。

Parameters:

credential - TokenCredential サービスに送信された要求を承認するために使用されます。

Returns:

更新された CosmosClientBuilder

directMode

public CosmosClientBuilder directMode()

使用する既定の DIRECT 接続構成を設定します。 既定では、ビルダーは directMode() で初期化されます

Returns:

現在の CosmosClientBuilder

directMode

public CosmosClientBuilder directMode(DirectConnectionConfig directConnectionConfig)

使用する DIRECT 接続構成を設定します。 既定では、ビルダーは directMode() で初期化されます

Parameters:

directConnectionConfig - 直接接続の構成

Returns:

現在の CosmosClientBuilder

directMode

public CosmosClientBuilder directMode(DirectConnectionConfig directConnectionConfig, GatewayConnectionConfig gatewayConnectionConfig)

使用する DIRECT 接続構成を設定します。 gatewayConnectionConfig - ゲートウェイ クライアントに使用する基本的な構成を表します。 直接接続モードでも、一部のメタデータ操作はゲートウェイ クライアントを経由します。この API でゲートウェイ接続構成を設定しても、接続モードには影響しません。この場合は Direct になります。

Parameters:

directConnectionConfig - 使用する直接接続構成
gatewayConnectionConfig - 使用するゲートウェイ接続構成

Returns:

現在の CosmosClientBuilder

endToEndOperationLatencyPolicyConfig

public CosmosClientBuilder endToEndOperationLatencyPolicyConfig(CosmosEndToEndOperationLatencyPolicyConfig cosmosEndToEndOperationLatencyPolicyConfig)

クライアントで を設定します。CosmosEndToEndOperationLatencyPolicyConfig

Parameters:

cosmosEndToEndOperationLatencyPolicyConfig - 次の値を使用 CosmosEndToEndOperationLatencyPolicyConfig

Returns:

現在の CosmosClientBuilder

endpoint

public CosmosClientBuilder endpoint(String endpoint)

SDK が接続する Azure Cosmos DB エンドポイントを設定します

Parameters:

endpoint - サービス エンドポイント

Returns:

現在のビルダー

endpointDiscoveryEnabled

public CosmosClientBuilder endpointDiscoveryEnabled(boolean endpointDiscoveryEnabled)

geo レプリケートされたデータベース アカウントのエンドポイント検出を有効にするフラグを設定します。

EnableEndpointDiscovery が true の場合、SDK は現在の書き込みリージョンと読み取りリージョンを自動的に検出し、リージョンの機能とユーザーの設定に基づいて要求が正しいリージョンに送信されるようにします。

このプロパティの既定値は、エンドポイント検出が有効になっていることを示す true です。

Parameters:

endpointDiscoveryEnabled - EndpointDiscovery が有効になっている場合は true。

Returns:

現在の CosmosClientBuilder

excludedRegionsSupplier

public CosmosClientBuilder excludedRegionsSupplier(Supplier excludedRegionsSupplier)

Supplierが呼び出されたときにSupplier#get()インスタンスを返す をCosmosExcludedRegions設定します。 要求は、 のこのインスタンスCosmosClient / CosmosAsyncClientを介して実行されるワークロードのヘッジ シナリオと再試行シナリオのために、 に存在getExcludedRegions()するリージョンにはルーティングされません。

Parameters:

excludedRegionsSupplier - インスタンスを返す CosmosExcludedRegions サプライヤー。

Returns:

現在の CosmosClientBuilder。

gatewayMode

public CosmosClientBuilder gatewayMode()

使用する既定のゲートウェイ接続構成を設定します。

Returns:

現在の CosmosClientBuilder

gatewayMode

public CosmosClientBuilder gatewayMode(GatewayConnectionConfig gatewayConnectionConfig)

使用するゲートウェイ接続構成を設定します。

Parameters:

gatewayConnectionConfig - ゲートウェイ接続の構成

Returns:

現在の CosmosClientBuilder

key

public CosmosClientBuilder key(String key)

リソースにアクセスするための認証を実行するために使用されるマスター キーまたは読み取り専用キーを設定します。

Parameters:

key - master キーまたは readonly キー

Returns:

現在のビルダー。

multipleWriteRegionsEnabled

public CosmosClientBuilder multipleWriteRegionsEnabled(boolean multipleWriteRegionsEnabled)

フラグを設定して、Azure Cosmos DB サービス内の geo レプリケートされたデータベース アカウントの任意のリージョンでの書き込みを有効にします。

このプロパティの値が true の場合、SDK は geo レプリケートされたデータベース アカウントの使用可能な書き込み可能なリージョンに書き込み操作を送信します。 書き込み可能なリージョンは、PreferredRegions プロパティによって順序付けられます。 DatabaseAccount の EnableMultipleWriteRegions も true に設定されるまで、プロパティ値を true に設定しても効果はありません。

既定値は true で、geo レプリケートされたデータベース アカウントの使用可能な書き込み可能なリージョンに書き込みが送信されることを示します。

Parameters:

multipleWriteRegionsEnabled - geo レプリケートされたデータベース アカウントの任意のリージョンでの書き込みを有効にするフラグ。

Returns:

現在の CosmosClientBuilder

openConnectionsAndInitCaches

public CosmosClientBuilder openConnectionsAndInitCaches(CosmosContainerProactiveInitConfig proactiveContainerInitConfig)

CosmosContainerProactiveInitConfigから取得getCosmosContainerIdentities()したコンテナーに関連付けられているキャッシュと接続のウォームアップを有効にする を、k が に評価される最初の k 優先リージョンから取得したレプリカにgetProactiveConnectionRegionsCount()設定します。

クラスをCosmosContainerProactiveInitConfigBuilder使用してクラスをインスタンス化するCosmosContainerProactiveInitConfig

Parameters:

proactiveContainerInitConfig - コンテナー ID の一覧をカプセル化し、プロアクティブ接続リージョンがない

Returns:

現在の CosmosClientBuilder

permissions

public CosmosClientBuilder permissions(List permissions)

アクセス許可リストを設定します。このリストには、リソースへのアクセスに必要なリソース トークンが含まれます。

Parameters:

permissions - 認証のアクセス許可の一覧。

Returns:

現在のビルダー。

preferredRegions

public CosmosClientBuilder preferredRegions(List preferredRegions)

geo レプリケートされたデータベース アカウントの優先リージョンを設定します。 たとえば、"米国東部" を優先地域に設定します。

EnableEndpointDiscovery が true で PreferredRegions が空でない場合、SDK は操作を実行するために指定された順序でコンテナー内のリージョンを使用します。

EnableEndpointDiscovery が false に設定されている場合、このプロパティは無視されます。

Parameters:

preferredRegions - 優先リージョンの一覧。

Returns:

現在の CosmosClientBuilder

readRequestsFallbackEnabled

public CosmosClientBuilder readRequestsFallbackEnabled(boolean readRequestsFallbackEnabled)

Azure Cosmos DB サービスのアカウントで構成された複数のリージョンへの読み取りを許可するかどうかを設定します。

既定値は true です。

このプロパティが設定されていない場合、境界付き制約以外のすべての整合性レベルの既定値は true、境界付き制約の既定値は false です。 1. #endpointDiscoveryEnabled は true 2 です。 Azure Cosmos DB アカウントに複数のリージョンがある

Parameters:

readRequestsFallbackEnabled - フラグを使用して、Azure Cosmos DB サービスのアカウントで構成された複数のリージョンに読み取りを行えるようにします。

Returns:

現在の CosmosClientBuilder

resourceToken

public CosmosClientBuilder resourceToken(String resourceToken)

リソースにアクセスするための認証を実行するために使用するリソース トークンを設定します。

Parameters:

resourceToken - 認証用の resourceToken

Returns:

現在のビルダー。

sessionCapturingOverrideEnabled

public CosmosClientBuilder sessionCapturingOverrideEnabled(boolean sessionCapturingOverrideEnabled)

セッション キャプチャは、 に対 SESSIONして既定で有効になっています。 その他の整合性レベルの場合は、クライアントがセッションで構成されていないときに、セッション整合性で要求を送信する必要がある場合を除き、必要ありません。

セッション モードのセッション キャプチャを有効にしても影響はありません。

Parameters:

sessionCapturingOverrideEnabled - セッション キャプチャのオーバーライド

Returns:

現在の cosmosClientBuilder

sessionRetryOptions

public CosmosClientBuilder sessionRetryOptions(SessionRetryOptions sessionRetryOptions)

クライアント上の SessionRetryOptions インスタンスを設定します。

この設定は、要求によって使用されるターゲット整合性がセッション整合性であり、要求が探しているデータが最新ではないリージョンに要求が送信された場合に発生する、または404 / 1002に関連付けられたNOT_FOUND / READ_SESSION_NOT_AVAILABLE再試行動作を最適化するのに役立ちます。

免責事項: を設定 SessionRetryOptions すると、クライアントのこのインスタンスを介して実行されるすべての操作またはワークロードの再試行動作が変更されます。

複数書き込みアカウントの場合:

  • ローカルの読み取りリージョンに送信される読み取り要求の場合、他の書き込みリージョンのデータが最新のデータになる可能性があるため、別の書き込みリージョンで要求を再試行することで可用性を最適化できます。
  • ローカル書き込みリージョンに対する読み取り要求の場合、ローカル書き込みリージョンに最新のデータがない場合は、すぐに別の書き込みリージョンに切り替えるのに役立ちます。
  • ローカル書き込みリージョンに対する書き込み要求の場合、ローカル書き込みリージョンに最新のデータがない場合は、すぐに別の書き込みリージョンに切り替えるのに役立ちます。

単一書き込みアカウントの場合:

  • 読み取り要求がローカル読み取りリージョンに送信されると、書き込みリージョンにすばやく切り替えることができます。
  • 読み取り要求が書き込みリージョンに送信される場合、 SessionRetryOptions 単一書き込みアカウントの書き込みリージョンには最新のデータがあるため、この設定は重要ではありません。
  • 単一書き込みアカウントの書き込みリージョンへの書き込みの場合、 READ_SESSION_NOT_AVAILABLE 書き込みリージョンには常に最新バージョンのデータがあり、すべての書き込みはこのリージョンのプライマリ レプリカに移動するため、エラーは適用されません。 そのため、エラーの原因となっているレプリケーションの遅延は、ここでは適用できません。

リージョン切り替えヒントについて:

  • 再試行のためにローカル リージョンに優先順位を付けるためには、 ヒントを使用します。 LOCAL_REGION_PREFERRED
  • 再試行を別の/リモート リージョンにすばやく移動するには、ヒントを使用します。 REMOTE_REGION_PREFERRED

サポートされている操作:

  • Read
  • クエリ
  • 作成
  • Replace
  • Upsert
  • 削除
  • 修正プログラム
  • Batch
  • 一括

Parameters:

sessionRetryOptions - SessionRetryOptions のインスタンスです。

Returns:

現在の CosmosClientBuilder

throttlingRetryOptions

public CosmosClientBuilder throttlingRetryOptions(ThrottlingRetryOptions throttlingRetryOptions)

DocumentClient インスタンスに関連付けられている再試行ポリシー オプションを設定します。

RetryOptions クラスのプロパティを使用すると、アプリケーションで組み込みの再試行ポリシーをカスタマイズできます。 このプロパティは省略可能です。 設定されていない場合、SDK は再試行ポリシーの構成に既定値を使用します。 詳細については、「RetryOptions クラス」を参照してください。

Parameters:

throttlingRetryOptions - RetryOptions インスタンス。

Returns:

現在の CosmosClientBuilder

userAgentSuffix

public CosmosClientBuilder userAgentSuffix(String userAgentSuffix)

は、ユーザー エージェント サフィックスの値を設定します。

Parameters:

userAgentSuffix - ユーザー エージェント ヘッダーに追加する値。これは監視目的で使用されます。

Returns:

現在の CosmosClientBuilder

適用対象