CosmosClientBuilder クラス
- java.
lang. Object - com.
azure. cosmos. CosmosClientBuilder
- com.
実装
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 クライアント ビルダーをインスタンス化します。 |
メソッドの概要
メソッドの継承元: java.lang.Object
コンストラクターの詳細
CosmosClientBuilder
public CosmosClientBuilder()
新しい Cosmos クライアント ビルダーをインスタンス化します。
メソッドの詳細
authorizationTokenResolver
public CosmosClientBuilder authorizationTokenResolver(CosmosAuthorizationTokenResolver cosmosAuthorizationTokenResolver)
トークン リゾルバーを設定します
Parameters:
Returns:
buildAsyncClient
public CosmosAsyncClient buildAsyncClient()
指定されたプロパティを使用して Cosmos 非同期クライアントを構築します
Returns:
buildClient
public CosmosClient buildClient()
指定されたプロパティを使用して Cosmos 同期クライアントを構築します
Returns:
clientTelemetryConfig
public CosmosClientBuilder clientTelemetryConfig(CosmosClientTelemetryConfig telemetryConfig)
このビルダーのクライアント テレメトリ構成インスタンスを返します
Parameters:
Returns:
clientTelemetryEnabled
public CosmosClientBuilder clientTelemetryEnabled(boolean clientTelemetryEnabled)
フラグを設定して、データベース操作の集計統計、cpu/memory などのシステム情報を定期的に収集し、Cosmos 監視サービスに送信するクライアント テレメトリを有効にします。これは、デバッグ中に役立ちます。
既定値は false で、これはオプトイン機能であり、既定ではテレメトリ収集がないことを示します。
Parameters:
Returns:
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:
Returns:
consistencyLevel
public CosmosClientBuilder consistencyLevel(ConsistencyLevel desiredConsistencyLevel)
使用する を ConsistencyLevel 設定します。既定では、 SESSION 整合性が使用されます。
Parameters:
Returns:
contentResponseOnWriteEnabled
public CosmosClientBuilder contentResponseOnWriteEnabled(boolean contentResponseOnWriteEnabled)
CosmosItem に対する作成、更新、および削除の操作の場合にのみ、Cosmos DB 応答でヘッダーと状態コードを返すようにブール値を設定します。 false (既定) に設定した場合、サービスは応答でペイロードを返しません。 ネットワーク経由でペイロードを返送せず、クライアントでシリアル化することで、ネットワークと CPU の負荷を軽減します。 この機能は、読み取り操作または書き込み操作の RU 使用量には影響しません。 既定では、これは false です。
Parameters:
Returns:
credential
public CosmosClientBuilder credential(AzureKeyCredential credential)
使用する を設定します。AzureKeyCredential
Parameters:
Returns:
credential
public CosmosClientBuilder credential(TokenCredential credential)
サービスに TokenCredential 送信される要求を承認するために使用する を設定します。 型の適切な使用方法の詳細については、Azure SDK for Java の ID と認証 に関するドキュメントを TokenCredential 参照してください。
Parameters:
Returns:
directMode
public CosmosClientBuilder directMode()
使用する既定の DIRECT 接続構成を設定します。 既定では、ビルダーは directMode() で初期化されます
Returns:
directMode
public CosmosClientBuilder directMode(DirectConnectionConfig directConnectionConfig)
使用する DIRECT 接続構成を設定します。 既定では、ビルダーは directMode() で初期化されます
Parameters:
Returns:
directMode
public CosmosClientBuilder directMode(DirectConnectionConfig directConnectionConfig, GatewayConnectionConfig gatewayConnectionConfig)
使用する DIRECT 接続構成を設定します。 gatewayConnectionConfig - ゲートウェイ クライアントに使用する基本的な構成を表します。 直接接続モードでも、一部のメタデータ操作はゲートウェイ クライアントを経由します。この API でゲートウェイ接続構成を設定しても、接続モードには影響しません。この場合は Direct になります。
Parameters:
Returns:
endToEndOperationLatencyPolicyConfig
public CosmosClientBuilder endToEndOperationLatencyPolicyConfig(CosmosEndToEndOperationLatencyPolicyConfig cosmosEndToEndOperationLatencyPolicyConfig)
クライアントで を設定します。CosmosEndToEndOperationLatencyPolicyConfig
Parameters:
Returns:
endpoint
public CosmosClientBuilder endpoint(String endpoint)
SDK が接続する Azure Cosmos DB エンドポイントを設定します
Parameters:
Returns:
endpointDiscoveryEnabled
public CosmosClientBuilder endpointDiscoveryEnabled(boolean endpointDiscoveryEnabled)
geo レプリケートされたデータベース アカウントのエンドポイント検出を有効にするフラグを設定します。
EnableEndpointDiscovery が true の場合、SDK は現在の書き込みリージョンと読み取りリージョンを自動的に検出し、リージョンの機能とユーザーの設定に基づいて要求が正しいリージョンに送信されるようにします。
このプロパティの既定値は、エンドポイント検出が有効になっていることを示す true です。
Parameters:
Returns:
excludedRegionsSupplier
public CosmosClientBuilder excludedRegionsSupplier(Supplier
Supplier
Parameters:
CosmosExcludedRegions
サプライヤー。
Returns:
gatewayMode
public CosmosClientBuilder gatewayMode()
使用する既定のゲートウェイ接続構成を設定します。
Returns:
gatewayMode
public CosmosClientBuilder gatewayMode(GatewayConnectionConfig gatewayConnectionConfig)
使用するゲートウェイ接続構成を設定します。
Parameters:
Returns:
key
public CosmosClientBuilder key(String key)
リソースにアクセスするための認証を実行するために使用されるマスター キーまたは読み取り専用キーを設定します。
Parameters:
Returns:
multipleWriteRegionsEnabled
public CosmosClientBuilder multipleWriteRegionsEnabled(boolean multipleWriteRegionsEnabled)
フラグを設定して、Azure Cosmos DB サービス内の geo レプリケートされたデータベース アカウントの任意のリージョンでの書き込みを有効にします。
このプロパティの値が true の場合、SDK は geo レプリケートされたデータベース アカウントの使用可能な書き込み可能なリージョンに書き込み操作を送信します。 書き込み可能なリージョンは、PreferredRegions プロパティによって順序付けられます。 DatabaseAccount の EnableMultipleWriteRegions も true に設定されるまで、プロパティ値を true に設定しても効果はありません。
既定値は true で、geo レプリケートされたデータベース アカウントの使用可能な書き込み可能なリージョンに書き込みが送信されることを示します。
Parameters:
Returns:
openConnectionsAndInitCaches
public CosmosClientBuilder openConnectionsAndInitCaches(CosmosContainerProactiveInitConfig proactiveContainerInitConfig)
CosmosContainerProactiveInitConfigから取得getCosmosContainerIdentities()したコンテナーに関連付けられているキャッシュと接続のウォームアップを有効にする を、k が に評価される最初の k 優先リージョンから取得したレプリカにgetProactiveConnectionRegionsCount()設定します。
クラスをCosmosContainerProactiveInitConfigBuilder使用してクラスをインスタンス化するCosmosContainerProactiveInitConfig
Parameters:
Returns:
permissions
public CosmosClientBuilder permissions(List
アクセス許可リストを設定します。このリストには、リソースへのアクセスに必要なリソース トークンが含まれます。
Parameters:
Returns:
preferredRegions
public CosmosClientBuilder preferredRegions(List
geo レプリケートされたデータベース アカウントの優先リージョンを設定します。 たとえば、"米国東部" を優先地域に設定します。
EnableEndpointDiscovery が true で PreferredRegions が空でない場合、SDK は操作を実行するために指定された順序でコンテナー内のリージョンを使用します。
EnableEndpointDiscovery が false に設定されている場合、このプロパティは無視されます。
Parameters:
Returns:
readRequestsFallbackEnabled
public CosmosClientBuilder readRequestsFallbackEnabled(boolean readRequestsFallbackEnabled)
Azure Cosmos DB サービスのアカウントで構成された複数のリージョンへの読み取りを許可するかどうかを設定します。
既定値は true です。
このプロパティが設定されていない場合、境界付き制約以外のすべての整合性レベルの既定値は true、境界付き制約の既定値は false です。 1. #endpointDiscoveryEnabled は true 2 です。 Azure Cosmos DB アカウントに複数のリージョンがある
Parameters:
Returns:
resourceToken
public CosmosClientBuilder resourceToken(String resourceToken)
リソースにアクセスするための認証を実行するために使用するリソース トークンを設定します。
Parameters:
Returns:
sessionCapturingOverrideEnabled
public CosmosClientBuilder sessionCapturingOverrideEnabled(boolean sessionCapturingOverrideEnabled)
セッション キャプチャは、 に対 SESSIONして既定で有効になっています。 その他の整合性レベルの場合は、クライアントがセッションで構成されていないときに、セッション整合性で要求を送信する必要がある場合を除き、必要ありません。
セッション モードのセッション キャプチャを有効にしても影響はありません。
Parameters:
Returns:
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:
Returns:
throttlingRetryOptions
public CosmosClientBuilder throttlingRetryOptions(ThrottlingRetryOptions throttlingRetryOptions)
DocumentClient インスタンスに関連付けられている再試行ポリシー オプションを設定します。
RetryOptions クラスのプロパティを使用すると、アプリケーションで組み込みの再試行ポリシーをカスタマイズできます。 このプロパティは省略可能です。 設定されていない場合、SDK は再試行ポリシーの構成に既定値を使用します。 詳細については、「RetryOptions クラス」を参照してください。
Parameters:
Returns:
userAgentSuffix
public CosmosClientBuilder userAgentSuffix(String userAgentSuffix)
は、ユーザー エージェント サフィックスの値を設定します。
Parameters:
Returns:
適用対象
Azure SDK for Java