Kusto の接続文字列
Kusto 接続文字列は、Kusto クライアント アプリケーションが Kusto サービス エンドポイントへの接続を確立するために必要な情報を提供します。 Kusto の接続文字列は、ADO.NET 接続文字列の後にモデル化されます。 つまり、接続文字列は名前と値のパラメーターペアのセミコロン区切りのリストであり、必要に応じて 1 つの URI でプレフィックスが付けられます。
たとえば、次の Kusto 接続文字列は、通信用のサービス エンドポイントを指定する URI で始まります。 https://help.kusto.windows.net この URI は、 プロパティに Data Source 割り当てられます。 次に、/Samples接続文字列内で既定のデータベースを表し、 プロパティにInitial Catalog割り当てられます。 最後に、他の 2 つのプロパティ と Acceptは、Fed接続の追加の構成またはカスタマイズ オプションを提供します。
https://help.kusto.windows.net/Samples; Fed=true; Accept=true
注意
- プロパティ名では大文字と小文字は区別されません。
- プロパティ値は大文字と小文字を区別します。
- 名前と値のパラメーターのペア間のスペースは無視されます。
- セミコロン (
;)、一重引用符 (')、二重引用符 (") を含むプロパティ値の場合、二重引用符で囲む必要があります。
いくつかの Kusto クライアント ツールでは、ClusterName/InitialCatalog の短縮形式を使用できる接続文字列の @ URI プレフィックスに対する拡張機能がサポートされています。 たとえば、これらのツールは、接続文字列 @help/Samples を に変換しますhttps://help.kusto.windows.net/Samples; Fed=true。
C# Kusto.Data.KustoConnectionStringBuilder クラスは、プログラムによって Kusto 接続文字列を解析および操作できます。 このクラスでは、すべての接続文字列が検証され、検証に失敗した場合はランタイム例外が生成されます。 この機能は、Kusto SDK のすべての種類に存在します。
信頼されたエンドポイント
Kusto エンドポイントとの接続は、そのエンドポイントが信頼されている場合にのみ確立できます。
Kusto クライアントは、ホスト名部分がサービスによって発行されたすべてのエンドポイントを信頼します。
たとえば、DNS ホスト名が で kusto.windows.net終わるエンドポイントなどです。
既定では、クライアントは他のエンドポイントへの接続を確立しません。 他のエンドポイントへの接続を許可するには、 クラスを Kusto.Data.Common.KustoTrustedEndpoints 使用して、信頼されたエンドポイントの一覧にエンドポイントを追加します。 既定のポリシーをオーバーライドしAddTrustedHosts、既存のポリシーに新しいエントリを追加するには、 を使用SetOverridePolicyします。
KustoTrustedEndpoints.AddTrustedHosts(
new[]
{
// Allow an explicit service address
new FastSuffixMatcher.MatchRule("my-kusto.contoso.com", exact: true),
// Allow services whose DNS name end with ".contoso.com"
new FastSuffixMatcher.MatchRule(".contoso.com", exact: false),
}
);
接続文字列のプロパティ
次の表に、Kusto 接続文字列に含めることができるすべての可能なプロパティを示します。 テーブルには、各プロパティのエイリアス名も用意されています。 さらに、各プロパティに関連付けられているプログラム名を表します。これは、 オブジェクト内のプロパティの名前を Kusto.Data.KustoConnectionStringBuilder 表します。
全般プロパティ
| プロパティ名 | プログラム名 | 説明 |
|---|---|---|
| トレースのクライアント バージョン | TraceClientVersion | クライアント バージョンをトレースする場合は、このプロパティを使用します。 |
| データ ソースエイリアス: Addr、Address、Network Address、Server | DataSource | Kusto サービス エンドポイントを指定する URI。 たとえば、「 https://mycluster.kusto.windows.net 」のように入力します。 |
| 初期カタログエイリアス: データベース | InitialCatalog | 既定で使用されるデータベースの名前。 たとえば、「 MyDatabase 」のように入力します。 |
| クエリ整合性エイリアス: QueryConsistency | QueryConsistency | を または strongconsistencyweakconsistency に設定して、クエリを実行する前にメタデータと同期する必要があるかどうかを判断します。 |
ユーザー認証のプロパティ
| プロパティ名 | プログラム名 | 説明 |
|---|---|---|
| Microsoft Entra ID フェデレーション セキュリティエイリアス：フェデレーション セキュリティ、フェデレーション、Fed、AADFed | FederatedSecurity | Microsoft Entra認証を実行するようにクライアントに指示するブール値。 |
| 機関 ID エイリアス: TenantId | Authority | ユーザーのテナントの名前または ID を提供する文字列値。 既定値は microsoft.com です。 詳細については、「Microsoft Entra機関」を参照してください。 |
| MFA エイリアスの適用: MFA、EnforceMFA | EnforceMfa | クライアントに多要素認証トークンを取得するように指示するオプションのブール値。 |
| ユーザー ID エイリアス: UID、ユーザー | UserID | 指定されたユーザー名を使用してユーザー認証を実行するようにクライアントに指示する文字列値。 |
| トレースのユーザー名 | TraceUserName | 要求を内部的にトレースするときに使用するユーザー名をサービスに報告する省略可能な文字列値。 |
| ユーザー トークン エイリアス: UsrToken、UserToken | UserToken | 指定したベアラー トークンを使用してユーザー認証を実行するようにクライアントに指示する文字列値。 、ApplicationKey、ApplicationClientIdおよび をオーバーライドしますApplicationToken。 を指定した場合は、指定されたトークンを優先して、実際のクライアント認証フローをスキップします。 |
ユーザー認証でサポートされているプロパティの組み合わせ
ユーザー認証の場合は、 として trueを指定しますAAD Federated Security。 次に、次のいずれかの認証モードを選択し、そのモードに関連するプロパティを指定します。
| 認証モード | プロパティ名 |
|---|---|
| ユーザープロンプト認証のMicrosoft Entra | - ユーザー ID (省略可能)- 機関 ID (省略可能)- MFA を適用する (省略可能)- トレースのユーザー名 (省略可能) |
| Microsoft Entra ユーザー トークン認証 | - ユーザー トークン - MFA を適用する (省略可能)- トレースのユーザー名 (省略可能) |
アプリケーション認証のプロパティ
| プロパティ名 | プログラム名 | 説明 |
|---|---|---|
| Microsoft Entra ID フェデレーション セキュリティエイリアス：フェデレーション セキュリティ、フェデレーション、Fed、AADFed | FederatedSecurity | Microsoft Entra ID フェデレーション認証を実行するようにクライアントに指示するブール値。 |
| アプリケーション証明書 SendX5c エイリアス: アプリケーション証明書送信パブリック証明書、SendX5c | ApplicationCertificateSendX5c | サブジェクト名と発行者ベースの認証を実行するようにクライアントに指示するブール値。 |
| アプリケーション証明書の拇印 エイリアス: AppCert | ApplicationCertificateThumbprint | アプリケーション クライアント証明書認証フローを使用するときに使用するクライアント証明書の拇印を提供する文字列値。 |
| アプリケーション クライアント ID エイリアス: AppClientId | ApplicationClientId | 認証時に使用するアプリケーション クライアント ID を提供する文字列値。 |
| アプリケーション キー のエイリアス: AppKey | ApplicationKey | アプリケーション シークレット フローを使用して認証するときに使用するアプリケーション キーを提供する文字列値。 |
| トレース エイリアスのアプリケーション名: TraceAppName | ApplicationNameForTracing | 要求を内部的にトレースするときに使用するアプリケーション名をサービスに報告する省略可能な文字列値。 |
| アプリケーション トークン エイリアス: AppToken | ApplicationToken | 指定したベアラー トークンを使用してアプリケーションの認証を実行するようにクライアントに指示する文字列値。 |
| Authority ID Alias: TenantId | Authority | アプリケーションが登録されているテナントの名前または ID を提供する文字列値。 既定値は microsoft.com です。 詳細については、「Microsoft Entra機関」を参照してください。 |
| Azure リージョン エイリアス: AzureRegion、Region | AzureRegion | 認証する Azure リージョンの名前を提供する文字列値。 |
| ManagedServiceIdentity | EmbeddedManagedIdentity | マネージド ID 認証で使用するアプリケーション ID をクライアントに指示する文字列値。 を使用して system 、システム割り当て ID を示します。 このプロパティは、プログラムでのみ、接続文字列で設定することはできません。 |
| アプリケーション証明書のサブジェクト識別名 の別名: アプリケーション証明書のサブジェクト | ApplicationCertificateSubjectDistinguishedName | アプリケーション証明書のサブジェクト識別名を指定する文字列値。 |
| アプリケーション証明書発行者識別名 の別名: アプリケーション証明書の発行者 | ApplicationCertificateIssuerDistinguishedName | アプリケーション証明書の発行者の識別名を指定する文字列値。 |
アプリケーション認証でサポートされているプロパティの組み合わせ
アプリケーション認証の場合は、 として trueを指定しますAAD Federated Security。 次に、次のいずれかの認証モードを選択し、そのモードに関連するプロパティを指定します。
| 認証モード | プロパティ名 |
|---|---|
| Microsoft Entra アプリケーション キー認証 | - アプリケーション クライアント ID- アプリケーション キー - 機関 ID - トレースのアプリケーション名 (省略可能) |
| Microsoft Entra アプリケーション拇印認証 | - アプリケーション クライアント ID- アプリケーション証明書の拇印 - 機関 ID - トレースのアプリケーション名 (省略可能) |
| Microsoft Entra アプリケーションのサブジェクトと発行者の認証 | - アプリケーション クライアント ID- アプリケーション証明書サブジェクト識別名- アプリケーション証明書発行者識別名- 機関 ID - Azure リージョン (省略可能)- アプリケーション証明書 SendX5c (省略可能) - トレースのアプリケーション名 (省略可能) |
| アプリケーションサブジェクト名認証のMicrosoft Entra | - アプリケーション クライアント ID- アプリケーション証明書のサブジェクト識別名- 機関 ID と Azure リージョン (省略可能) - トレースのアプリケーション名 (省略可能) |
| Microsoft Entra アプリケーション トークン認証 | - アプリケーション トークン - トレースのアプリケーション名 (省略可能) |
アプリケーション証明書を使用した認証
- アプリケーションは、指定された証明書を受け入れるように構成する必要があります。 アプリケーションの証明書に基づいて認証Microsoft Entra方法。
- アプリケーションは、関連する Kusto クラスターで承認されたプリンシパルとして構成する必要があります。
- 証明書は、ローカル コンピューター ストアまたは現在のユーザー ストアにインストールする必要があります。
- 証明書の公開キーには、少なくとも 2048 ビットを含める必要があります。
クライアント通信のプロパティ
| プロパティ名 | プログラム名 | 説明 |
|---|---|---|
| Accept | 承諾 | エラー発生時に詳細なエラー オブジェクトを返すように要求するブール値。 |
| ストリーミング | ストリーミング | クライアントが呼び出し元にデータを提供する前にデータを蓄積しないように要求するブール値。 これは既定の動作です。 |
| 非圧縮 | 非圧縮 | クライアントがトランスポート レベルの圧縮を要求しないように要求するブール値。 |
注意
フラグが Streaming 有効になっている場合 (既定値の場合)、SDK はすべての応答データをメモリにバッファー処理するわけではありません。代わりに、呼び出し元が要求したときにサービスからデータを "プル" します。 そのため、この場合、サービスへのネットワーク接続が不必要に開かれているため、データの読み取りが完了したら、呼び出し元がデータ (IDataReader など) を適切に破棄することが重要です。
例
現在ログオンしているユーザー ID を使用したMicrosoft Entra ID フェデレーション認証 (必要に応じてユーザーにメッセージが表示されます)
var kustoUri = "https://<clusterName>.<region>.kusto.windows.net";
var authority = "contoso.com"; // Or the AAD tenant GUID
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
.WithAadUserPromptAuthentication(authority);
// Equivalent Kusto connection string: $"Data Source={kustoUri};Database=NetDefaultDB;Fed=True;Authority Id={authority}"
ユーザー ID ヒントを使用して ID フェデレーション認証をMicrosoft Entraします (必要に応じて、ユーザーにメッセージが表示されます)
var kustoUri = "https://<clusterName>.<region>.kusto.windows.net";
var authority = "contoso.com"; // Or the AAD tenant GUID
var userId = "johndoe@contoso.com";
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
.WithAadUserPromptAuthentication(authority, userId);
// Equivalent Kusto connection string: $"Data Source={kustoUri};Database=NetDefaultDB;Fed=True;Authority Id={authority};User ID={userId}"
ApplicationClientId と ApplicationKey を使用したMicrosoft Entra ID フェデレーション アプリケーション認証
var kustoUri = "https://<clusterName>.<region>.kusto.windows.net";
var appId = "<appId>";
var appKey = "<appKey>";
var authority = "contoso.com"; // Or the AAD tenant GUID
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
.WithAadApplicationKeyAuthentication(appId, appKey, authority);
// Equivalent Kusto connection string: $"Data Source={kustoUri};Database=NetDefaultDB;Fed=True;AppClientId={appId};AppKey={appKey};Authority Id={authority}"
システム割り当てマネージド ID の使用
var kustoUri = "https://<clusterName>.<region>.kusto.windows.net";
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
.WithAadSystemManagedIdentity();
ユーザー割り当てマネージド ID の使用
var kustoUri = "https://<clusterName>.<region>.kusto.windows.net";
var managedIdentityClientId = "<managedIdentityClientId>";
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
.WithAadUserManagedIdentity(managedIdentityClientId);
ユーザー/アプリケーション トークンを使用したMicrosoft Entra ID フェデレーション認証
var kustoUri = "https://<clusterName>.<region>.kusto.windows.net";
var userAccessToken = "<userAccessToken>";
var appAccessToken = "<appAccessToken>";
// AAD User token
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
.WithAadUserTokenAuthentication(userAccessToken);
// Equivalent Kusto connection string: "Data Source={kustoUri};Database=NetDefaultDB;Fed=True;UserToken={userAccessToken}"
// AAD Application token
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
.WithAadApplicationTokenAuthentication(appAccessToken);
// Equivalent Kusto connection string: "Data Source={kustoUri};Database=NetDefaultDB;Fed=True;ApplicationToken={appAccessToken}"
トークン プロバイダー コールバックの使用 (トークンが必要になるごとに呼び出されます)
var kustoUri = "https://<clusterName>.<region>.kusto.windows.net";
Func<string> tokenProviderCallback; // User-defined method to retrieve the access token
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
.WithAadTokenProviderAuthentication(tokenProviderCallback);
X.509 証明書の使用
var kustoUri = "https://<clusterName>.<region>.kusto.windows.net";
var appId = "<appId>";
X509Certificate2 appCert;
var authority = "contoso.com"; // Or the AAD tenant GUID
bool sendX5c; // Set to 'True' to use Trusted Issuer feature of AAD
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
.WithAadApplicationCertificateAuthentication(appId, appCert, authority, sendX5c);
拇印による X.509 証明書の使用 (クライアントはローカル ストアから証明書の読み込みを試みます)
var kustoUri = "https://<clusterName>.<region>.kusto.windows.net";
var appId = "<appId>";
var appCert = "<appCert>";
var authority = "contoso.com"; // Or the AAD tenant GUID
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
.WithAadApplicationThumbprintAuthentication(appId, appCert, authority);
// Equivalent Kusto connection string: $"Data Source={kustoUri};Database=NetDefaultDB;Fed=True;AppClientId={appId};AppCert={appCert};Authority Id={authority}"
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示