バージョン: 3.16

ScalarDB Cluster .NET Client SDK リファレンス

注記

このページは英語版のページが機械翻訳されたものです。英語版との間に矛盾または不一致がある場合は、英語版を正としてください。

このリファレンスでは、ScalarDB Cluster .NET Client SDK の動作について詳しく説明します。

クライアント設定

クライアントは、次のものを使用して設定できます。

設定ファイル (appsettings.json など) またはカスタム JSON ファイル
環境変数
ScalarDbOptions オブジェクト

ASP.NET Core で SDK を使用する場合は、アプリをさまざまな方法で設定できます。詳細については、ASP.NET Core の構成を参照してください。

設定できるオプションの一覧については、使用可能なオプションを参照してください。

設定ファイルの使用

SDK は、標準の appsettings.json とカスタム JSON 設定ファイルの両方をサポートしています。 JSON ファイルでクライアントを設定するには、ScalarDbOptions セクションを追加し、必要なオプションを設定します。例:

{
  "ScalarDbOptions": {
    "Address": "http://localhost:60053",
    "HopLimit": 10
  }
}

次に、次のように設定された TransactionFactory オブジェクトを作成します。

// If appsettings.json is used, call the Create() method without parameters.
var factory = TransactionFactory.Create();

// Or, if a custom file is used, call the Create() method that is passed in the path to the custom file as a parameter.
factory = TransactionFactory.Create("scalardb-options.json");

ASP.NET Core で SDK を使用する場合、登録されたトランザクションマネージャーや ScalarDbContext が作成されると、appsettings.json の設定が自動的に適用されます。カスタム JSON ファイルを使用する場合は、次のように設定フレームワークに追加します。

var builder = WebApplication.CreateBuilder(args);

// ...

builder.Configuration.AddJsonFile("scalardb-options.json");

警告

カスタム JSON ファイルはすべての標準設定プロバイダーの後に適用されるため、カスタムファイルの値が他のソースの値を上書きします。

環境変数の使用

クライアントが環境変数を使用するように設定するには、プレフィックス ScalarDbOptions__ を使用します。例:

export ScalarDbOptions__Address="http://localhost:60053"
export ScalarDbOptions__HopLimit=10

警告

環境変数の値は設定ファイルの値を上書きします。

`ScalarDbOptions` オブジェクトの使用

次のように ScalarDbOptions オブジェクトを使用して、実行時にクライアントを設定できます。

var options = new ScalarDbOptions()
{
    Address = "http://localhost:60053",
    HopLimit = 10
};

var factory = TransactionFactory.Create(options);

また、次のように、JSON ファイルや環境変数の値を使用して ScalarDbOptions オブジェクトを初期化し、残りの値を実行時に設定することもできます。

// If appsettings.json is used, call the Load() method without parameters.
var options = ScalarDbOptions.Load();

// Or, if a custom file is used, call the Load() method that is passed in the path to the custom file as a parameter.
options = ScalarDbOptions.Load("scalardb-options.json");

options.HopLimit = 10;

var factory = TransactionFactory.Create(options);

ASP.NET Core で SDK を使用する場合は、次のように AddScalarDb および AddScalarDbContext のラムダ式を使用できます。

var builder = WebApplication.CreateBuilder(args);

//...

builder.Services.AddScalarDb(options =>
{
    options.Address = "http://localhost:60053";
    options.HopLimit = 10;
});

builder.Services.AddScalarDbContext<MyDbContext>(options =>
{
    options.Address = "http://localhost:60053";
    options.HopLimit = 10;
});

この設定を使用すると、ラムダ式に渡される ScalarDbOptions オブジェクト (上記の例では options という名前) が、JSON ファイル、環境変数、およびその他のソースからの値で初期化されます。

使用可能なオプション

利用可能なオプションは次のとおりです。

名前	説明	デフォルト
`Address`	必須: クラスターのアドレス。形式は `<PROTOCOL>://<HOSTNAME_OR_IP_ADDRESS>:<PORT>` です。`<PROTOCOL>`: ワイヤ暗号化 (TLS) が有効な場合は `https`、それ以外の場合は `http` です。`<HOSTNAME_OR_IP_ADDRESS>`: クラスターの FQDN または IP アドレスです。`<PORT>`: クラスターのポート番号 (デフォルトでは `60053`)。	-
`HopLimit`	クラスターへのリクエストのホップ数。`HopLimit` の目的は、クラスター内での無限ループを防ぐことです。リクエストが別のクラスターノードに転送されるたびに、`HopLimit` は1ずつ減少します。`HopLimit` が0に達すると、リクエストは拒否されます。	`3`
`RetryCount`	クラスターが利用できない場合にクライアントがクラスターへの接続を試行できる回数。	`10`
`AuthEnabled`	認証と認可が有効かどうか。	`false`
`Username`	認証/認可のためのユーザー名。
`Password`	認証用のパスワード。設定されていない場合は、パスワードなしで認証が行われます。
`AuthTokenExpirationTime`	認証トークンを更新するまでの時間。`AuthTokenExpirationTime` に設定された時間がクラスターの有効期限よりも長い場合、認証エラーを受信すると認証トークンが更新されます。認証トークンが正常に更新されると、認証エラーはクライアントコードに伝播されません。代わりに、認証エラーで失敗した操作が自動的に再試行されます。複数の操作が並行して実行されている場合、認証トークンが更新される前に、これらすべての操作が認証エラーで一度失敗します。	`00:00:00` (クラスターから受信した認証トークンの有効期限が使用されます。)
`TlsRootCertPem`	TLS 通信用のカスタム CA ルート証明書 (PEM データ)。
`TlsRootCertPath`	TLS 通信用のカスタム CA ルート証明書へのファイルパス。
`TlsOverrideAuthority`	TLS 通信のカスタム認証局。これは、実際に接続しているホストを変更するものではありません。これは主にテストを目的としています。たとえば、クラスターの証明書 (クラスターの `scalar.db.cluster.node.tls.cert_chain_path` パラメータ) に記載されているホスト名を指定できます。クラスターの証明書に複数のホスト名がある場合は、最初のホスト名のみがチェックされます。
`LogSensitiveData`	`true` に設定すると、gRPC リクエストとレスポンスをログに記録するときに、ユーザー名、パスワード、認証トークンなどの情報がマスクされずにそのままログに記録されます。	`false`
`GrpcRequestTimeout`	gRPC リクエストのタイムアウト。内部的には、タイムアウトの値はクラスターへの各 gRPC リクエストのデッドラインを計算して設定するために使用されます。設定されたデッドラインを超えると、リクエストはキャンセルされ、`DeadlineExceededException` がスローされます。タイムアウトが `0` に設定されている場合、デッドラインは設定されません。	`00:01:00`
`GrpcMaxReceiveMessageSize`	クライアントが受信できる最大メッセージサイズ (バイト単位)。`0` に設定すると、メッセージサイズは無制限になります。	`4 MB`
`GrpcMaxSendMessageSize`	クライアントから送信できる最大メッセージサイズ (バイト単位)。`0` に設定すると、メッセージサイズは無制限になります。	`0` (無制限)

ScalarDB 列型と .NET 型間の変換方法

LINQ または Transactional API、SQL API、または Administrative API の拡張メソッドを使用すると、クラスターから受信した列の値は、対応する .NET 型に自動的に変換されます。同様に、オブジェクトがクラスターに保存されるときに、.NET プロパティの値は対応するクラスターの型に自動的に変換されます。

次の表に、型がどのように変換されるかを示します。

ScalarDB 型	.NET 型	C# エイリアス
TEXT	System.String	string
INT	System.Int32	int
BIGINT	System.Int64	long
FLOAT	System.Single	float
DOUBLE	System.Double	double
BOOLEAN	System.Boolean	bool
BLOB	Google.Protobuf.ByteString
DATE	NodaTime.LocalDate
TIME	NodaTime.LocalTime
TIMESTAMP	NodaTime.LocalDateTime
TIMESTAMPTZ	NodaTime.Instant

注記

ScalarDB Cluster .NET Client SDK は、BLOB 型には Google.Protobuf を使用し、時間関連の型には NodaTime を使用します。

警告

.NET の時間関連型の精度は、ScalarDB でサポートされている精度よりも高くなります。そのため、外部ソースから受信した時間関連の値を保存するときは注意が必要です。ScalarDB Cluster .NET Client SDK には、次の方法で時間関連の値の精度を下げるために使用できる WithScalarDbPrecision 拡張メソッドが含まれています:

using ScalarDB.Client.Extensions;

// ...

var updatedAt = Instant.FromDateTimeUtc(DateTime.UtcNow)
                       .WithScalarDbPrecision();

// using NodaTime to get current instant
updatedAt = clockInstance.GetCurrentInstant()
                         .WithScalarDbPrecision();

ScalarDB の値の範囲と精度の詳細については、ScalarDB と他のデータベース間のデータ型マッピングを参照してください。

クライアント設定​

設定ファイルの使用​

環境変数の使用​

ScalarDbOptions オブジェクトの使用​

使用可能なオプション​

ScalarDB 列型と .NET 型間の変換方法​