Microsoft Azure Cosmos DB .NET SDK Version 3 のクライアントオプション
既定値
- Gatewayモードの最大コネクション数：50
- リクエストタイムアウト：60秒
- コネクションモード：Direct
- 接続プロトコル：TCP
オプション
クラス
「CosmosClientOptions」を使用して、「CosmosClient」に渡すことで設定できます。
var option = new CosmosClientOptions();
try
{
using (var client = new CosmosClient(endpoint, key, option))
{
var container = client.GetContainer(“test”,”test”);
await container.CreateItemAsync(new { id=”example”,test = “hoge”,pk=”hoge” });
Console.WriteLine(“test”);
}
}
ApplicationName
Cosmos DB の診断ログに出力されるログに出力される。出力先は、「userAgent」の一部にサフィックスとしての扱い。
リクエストを送った後に、プロパティを設定しても何の影響も及ぼさないので、設定する場合には、リクエストを送信する前に。
option.ApplicationName = “TestApp”;
ログには以下のように出力される。
（フォーマット）{OS}/{Process Architecture} {SDK Version}/{Direct pkg Version}-{Framework} {ClientId} {UserSuffix}
（例）Windows/10.0.17763 cosmos-netstandard-sdk/3.1.4 3.1.1-.NET Core 4.6.27817.01 X64 637028475632621596 TestApp
SQL Serverみたいに、ApplicationName列があるわけではなく、UserAgentに埋め込んで出力するという実装になっている。
ApplicationRegion
通信先のリージョンとして任意のリージョンを選択して設定することができる。
このプロパティを指定すると、各種操作をする先のリージョンにできる。
高可用性のためにジオレプリケーション先を自動選択させることもできる。
設定しない場合は、デフォルトでは、すべての操作は書き込みリージョンに行われる。
option.ApplicationRegion = Regions.JapanEast;
GatewayModeMaxConnectionLimit
対象のエンドポイントへの接続に許可する最大コネクション数を設定します。
デフォルトでは50が設定されています。
この設定は、Gatewayモードの時のみに適用されます。
option.GatewayModeMaxConnectionLimit = 2000;
RequestTimeout
Cosmos DBに接続するときに、リクエストタイムアウトするまでの時間を秒で取得、設定できます。
ネットワークからレスポンスが戻るまでに待機する時間を指定します。
デフォルトでは1分待ちます。
設定値は、TimeSpanです。
option.RequestTimeout = TimeSpan.FromSeconds(120);
ConnectionMode
接続するときのクライアントが使用する接続モードを取得したり、設定できます。
デフォルトでは、Directモードです。
option.ConnectionMode = ConnectionMode.Direct;
option.ConnectionMode = ConnectionMode.Gateway;
ConsistencyLevel
読み取り処理時に、データベースアカウントの一貫性レベルを弱めることができます。
設定しない場合は、データベースアカウントの一貫性レベルが使用されます。
option.ConsistencyLevel = ConsistencyLevel.BoundedStaleness;
option.ConsistencyLevel = ConsistencyLevel.ConsistentPrefix;
option.ConsistencyLevel = ConsistencyLevel.Eventual;
option.ConsistencyLevel = ConsistencyLevel.Session;
option.ConsistencyLevel = ConsistencyLevel.Strong;
MaxRetryAttemptsOnRateLimitedRequests
参考：「スループットを使い切った場合はどうなりますか?」
操作に上限を設定してパフォーマンスと待機時間を保証。保証されたスループットと待機時間が確保。
この容量を超えると、容量を使い切ったことを示すオーバーロードのエラー。
制限リクエスト時のリトライ回数を取得や設定ができます。
option.MaxRetryAttemptsOnRateLimitedRequests = 5;
MaxRetryWaitTimeOnRateLimitedRequests
制限リクエストレート時のリトライする最大時間を取得したり、設定できます。
最小インターバルは秒で、インターバルが短すぎると拒否されます。
option.MaxRetryWaitTimeOnRateLimitedRequests = TimeSpan.FromSeconds(100);
IdleTcpConnectionTimeout（version. 3.1.2以降）
（Direct/TCP）未使用のコネクションをクローズするまでのアイドルタイム時間を設定できます。
デフォルトでは、アイドルコネクションは、無期限に維持されます。この値は10分以上にしてください。推奨は20分から24時間です。
主に大規模なデータベースアカウントへのたまのアクセスの際に役立ちます。
option.IdleTcpConnectionTimeout = TimeSpan.FromMinutes(100);
OpenTcpConnectionTimeout（version. 3.1.2以降）
（Direct/TCP）接続を確立するまでの許容時間を設定できます。
デフォルトでは⑤秒です。推奨値は、5秒以上にすることです。
時間が経過すると、キャンセルしエラーを返します。長いタイムアウト時間は、リトライと失敗まで遅延します。
option.OpenTcpConnectionTimeout = TimeSpan.FromSeconds(10);
MaxRequestsPerTcpConnection（version. 3.1.2以降）
（Direct/TCP）単一のTCP接続で同時に許可するリクエスト数を制御します。同時にさらに多くのリクエストがあった場合は、direct/TCPクライアントは追加の接続を開きます。
デフォルトの設定では、1つの接続で同時に30リクエストを許可します。
この値は4より小さい値、100より大きい値にしないでください。
小さすぎると大量の接続が作成され、大きすぎるとブロッキング、高レイテンシー、タイムアウトになります。
非常に並列度の大きかったり、多いリクエストやレスポンス、とても小さいレイテンシーが必要なアプリケーションの場合、１つの接続当たりつの8-16リクエストにすると性能が良くなることがあります。
option.MaxRequestsPerTcpConnection = 100;
MaxTcpConnectionsPerEndpoint（version. 3.1.2以降）
(Direct/TCP) 一つのCosmos DBのエンドポイントに対して開くことができるTCP接続の最大数を制御します。MaxRequestsPerTcpConnectionと一緒に設定すると、同時に一つのCosmos DBエンドポイントに同時送信する最大リクエスト数を制限できます。（MaxRequestsPerTcpConnection*MaxTcpConnectionsPerEndpoint）
デフォルト値は、65,535で、この値は16以上にしなければなりません。
option.MaxTcpConnectionsPerEndpoint = 65535;
SerializerOptions
シリアライザのオプションを取得したり、設定することができます。
option.SerializerOptions = new CosmosSerializationOptions()
{
IgnoreNullValues = true,
Indented = false,
PropertyNamingPolicy = CosmosPropertyNamingPolicy.CamelCase
};
Version 3.1.2以降では、「PropertyNamingPolicy 」に「CamelCase」を指定できるようになった（このPRで）。これを設定しておくことで、idを認識してくれるようになります。
Serializer
JSONシリアライザを取得したり、設定できます。クライアントは、リクエスト/レスポンスのシリアライズ、デシリアライズにそれを使用します。
DatabasePropertiesやContainerPropertiesのようなSDKのプロパティは常にSDKのデフォルトのシリアライザを使用します。
CosmosSerializer ignoreNullSerializer = new MyCustomIgnoreNullSerializer();
option.Serializer = ignoreNullSerializer;
internal class MyCustomIgnoreNullSerializer : CosmosSerializer
{
private static readonly Encoding DefaultEncoding = new UTF8Encoding(false, true);
private readonly JsonSerializer Serializer;
internal MyCustomIgnoreNullSerializer()
{
this.Serializer = JsonSerializer.Create();
}
public override T FromStream<T>(Stream stream)
{
using (stream)
{
if (typeof(Stream).IsAssignableFrom(typeof(T)))
{
return (T)(object)stream;
}using (StreamReader sr = new StreamReader(stream))
{
using (JsonTextReader jsonTextReader = new JsonTextReader(sr))
{
return this.Serializer.Deserialize<T>(jsonTextReader);
}
}
}
}
public override Stream ToStream<T>(T input)
{
MemoryStream streamPayload = new MemoryStream();
using (StreamWriter streamWriter = new StreamWriter(streamPayload, encoding: MyCustomIgnoreNullSerializer.DefaultEncoding, bufferSize: 1024, leaveOpen: true)
{
using (JsonWriter writer = new JsonTextWriter(streamWriter))
{
writer.Formatting = Newtonsoft.Json.Formatting.None;
this.Serializer.Serialize(writer, input);
writer.Flush();
streamWriter.Flush();
}
}
streamPayload.Position = 0;
return streamPayload;
}
}