Kusto 連接字串

適用於： ✅Microsoft網狀架構✅Azure 數據總管

Kusto 連接字串 提供 Kusto 用戶端應用程式建立 Kusto 服務端點連線所需的資訊。 Kusto 連接字串 會在 ADO.NET 連接字串 之後建立模型。 也就是說，連接字串 是以分號分隔的名稱/值參數位清單，選擇性地加上單一 URI 的前置詞。

例如，下列 Kusto 連接字串 開頭是指定通訊服務端點的 URI：https://help.kusto.windows.net。 此 URI 會指派給 Data Source 屬性。 接下來，/Samples在 連接字串 中代表預設資料庫，並指派給 Initial Catalog 屬性。 最後，另外兩個屬性 Fed 和 Accept提供連線的進一步組態或自定義選項。

https://help.kusto.windows.net/Samples; Fed=true; Accept=true

注意

• 屬性名稱不區分大小寫。
• 屬性值會區分大小寫。
• 會忽略名稱/值參陣列之間的空格。
• 包含分號 （）、單引號 （;'） 或雙引號 （"） 的屬性值必須以雙引弧括住。

以程序設計方式，C# Kusto.Data.KustoConnectionStringBuilder 類別可以剖析及操作 Kusto 連接字串。 此類別會驗證所有 連接字串，並在驗證失敗時產生運行時間例外狀況。 此功能存在於 Kusto SDK 的所有類別中。

信任的端點

只有信任該端點時，才能建立與 Kusto 端點的連線。 Kusto 用戶端會信任服務發出其主機網域的所有端點。 例如，DNS 主機名結尾 kusto.windows.net為 的端點。

根據預設，用戶端不會建立與其他端點的連線。 若要允許連線到其他端點，請使用 Kusto.Data.Common.KustoTrustedEndpoints 類別將端點新增至受信任的端點清單。 使用 SetOverridePolicy 來覆寫默認原則，以及 AddTrustedHosts 將新專案新增至現有的原則。

KustoTrustedEndpoints.AddTrustedHosts(
    new[]
    {
        // Allow an explicit service address
        new FastSuffixMatcher<EndpointContext>.MatchRule("my-kusto.contoso.com", exact: true, new EndpointContext(EndpointType.Kusto)),
        // Allow services whose DNS name end with ".contoso.com"
        new FastSuffixMatcher<EndpointContext>.MatchRule(".contoso.com", exact: false, new EndpointContext(EndpointType.Kusto)),
    }
);

連接字串屬性

下表列出所有可能的屬性，這些屬性可以包含在 Kusto 連接字串，並提供每個屬性的別名名稱。 此外，數據表會記下與每個屬性相關聯的程式設計名稱，這代表 物件中的 Kusto.Data.KustoConnectionStringBuilder 屬性名稱。

一般屬性

屬性名稱	程式設計名稱	描述
追蹤的用戶端版本	TraceClientVersion	追蹤用戶端版本時所使用的屬性。
數據源 別名： Addr、Address、Network Address、Server	DataSource	指定 Kusto 服務端點的 URI。 例如： https://mycluster.kusto.windows.net 。
初始目錄 別名： 資料庫	InitialCatalog	預設資料庫名稱。 例如： MyDatabase 。
查詢一致性 別名： QueryConsistency	QueryConsistency	將 設定為 strongconsistency 或 weakconsistency ，以判斷查詢是否應該與元數據同步，再執行。

使用者驗證屬性

屬性名稱	程式設計名稱	描述
Microsoft Entra ID 同盟安全性別名：同盟安全性 、同盟、Fed、AADFed	FederatedSecurity	布爾值，指示客戶端執行Microsoft Entra 驗證。
授權單位標識碼 別名： TenantId	授權單位	提供使用者租用戶名稱或標識碼的字串值。 預設值是 microsoft.com。 如需詳細資訊，請參閱 Microsoft Entra 授權單位。
強制執行 MFA 別名：MFA 、EnforceMFA	EnforceMfa	選擇性布爾值，指示用戶端取得多重要素驗證令牌。
用戶標識碼 別名： UID、使用者	UserID	字串值，指示用戶端使用指定的用戶名稱執行用戶驗證。
追蹤的用戶名稱	TraceUserName	選擇性字串值，會向服務報告在內部追蹤要求時要使用的用戶名稱。
使用者令牌 別名： UsrToken、UserToken	UserToken	字串值，指示用戶端使用指定的持有人令牌執行用戶驗證。 覆寫 ApplicationClientId、 ApplicationKey和 ApplicationToken。 如果指定，則會略過實際的客戶端驗證流程，以利於提供的令牌。

使用者驗證的支持屬性組合

針對使用者驗證，請指定 AAD Federated Security 為 true。 然後，選擇下列其中一種驗證模式，並指定該模式的相關屬性。

驗證模式	屬性名稱
Microsoft Entra 使用者提示驗證	- 使用者識別碼 （選擇性） - 授權單位識別碼 （選擇性） - 強制執行 MFA （選擇性） - 追蹤的使用者名稱 （選擇性）
Microsoft Entra 使用者令牌驗證	- 使用者權杖 - 強制執行 MFA （選擇性） - 追蹤的使用者名稱（選擇性）

應用程式驗證屬性

屬性名稱	程式設計名稱	描述
Microsoft Entra ID 同盟安全性別名：同盟安全性 、同盟、Fed、AADFed	FederatedSecurity	布爾值，指示客戶端執行Microsoft Entra ID 同盟驗證。
應用程式憑證 SendX5c 別名： 應用程式憑證傳送公用憑證、SendX5c	ApplicationCertificateSendX5c	布爾值，指示用戶端執行主體名稱和簽發者型驗證。
應用程式憑證指紋 別名： AppCert	ApplicationCertificateThumbprint	字串值，提供使用應用程式用戶端憑證驗證流程時要使用的用戶端憑證指紋。
應用程式用戶端識別碼 別名： AppClientId	ApplicationClientId	字串值，提供驗證時要使用的應用程式用戶端識別碼。
應用程式金鑰 別名： AppKey	ApplicationKey	字串值，提供使用應用程式秘密流程進行驗證時要使用的應用程式密鑰。
追蹤 別名的應用程式名稱： TraceAppName	ApplicationNameForTracing	選擇性字串值，會向服務報告在內部追蹤要求時要使用的應用程式名稱。
應用程式令牌 別名： AppToken	ApplicationToken	字串值，指示用戶端使用指定的持有人令牌執行應用程序驗證。
授權單位標識碼 別名： TenantId	授權單位	字串值，提供註冊應用程式之租用戶的名稱或標識符。 預設值是 microsoft.com。 如需詳細資訊，請參閱 Microsoft Entra 授權單位。
Azure 區域 別名： AzureRegion、Region	AzureRegion	字串值，提供要在其中進行驗證的 Azure 區域名稱。
ManagedServiceIdentity	EmbeddedManagedIdentity	字串值，指示用戶端要與受控識別驗證搭配使用的應用程式身分識別。 使用 system 來指出系統指派的身分識別。 此屬性無法以程式設計方式設定 連接字串。
應用程式憑證主體辨別名稱 別名： 應用程式憑證主體	ApplicationCertificateSubjectDistinguishedName	指定應用程式憑證主體辨別名稱的字串值。
應用程式憑證簽發者辨別名稱 別名： 應用程式憑證簽發者	ApplicationCertificateIssuerDistinguishedName	指定應用程式憑證簽發者辨別名稱的字串值。

應用程式驗證的支持屬性組合

針對應用程式驗證，請指定 AAD Federated Security 為 true。 然後，選擇下列其中一種驗證模式，並指定該模式的相關屬性。

驗證模式	屬性名稱
Microsoft Entra 應用程式密鑰驗證	- 應用程式用戶端識別碼 - 應用程式金鑰 - 授權單位識別碼 - 追蹤的應用程式名稱 （選擇性）
Microsoft Entra 應用程式指紋驗證	- 應用程式用戶端識別碼 - 應用程式憑證指紋 - 授權單位識別碼 - 追蹤的應用程式名稱 （選擇性）
Microsoft Entra 應用程式主體和簽發者驗證	- 應用程式用戶端識別碼 - 應用程式憑證主體辨別名稱 - 應用程式憑證簽發者辨別名稱 - 授權識別碼 - Azure 區域 （選擇性） - 應用程式憑證 SendX5c （選擇性） - 追蹤的應用程式名稱 （選擇性）
Microsoft專案應用程式主體名稱驗證	- 應用程式用戶端識別碼 - 應用程式憑證主體辨別名稱 - 授權單位識別碼 - 和 Azure 區域 （選擇性） - 追蹤的應用程式名稱 （選擇性）
Microsoft專案應用程式令牌驗證	- 應用程式權杖 - 追蹤的應用程式名稱（選擇性）

使用應用程式憑證進行驗證

1. 應用程式應該設定為接受指定的憑證。 如何根據Microsoft Entra 應用程式的憑證進行驗證。
2. 應用程式應設定為相關 Kusto 環境中的授權主體。
3. 憑證必須安裝在本機計算機存放區或目前使用者存放區中。
4. 憑證的公鑰應該至少包含 2,048 位。

用戶端通訊屬性

屬性名稱	程式設計名稱	描述
Accept	Accept	布爾值，要求在失敗時傳回詳細的錯誤物件。
串流	串流	布爾值，要求用戶端立即將數據提供給呼叫端，而不先累積數據。 串流是預設行為。
未壓縮	未壓縮	布爾值，指示用戶端避免要求傳輸層級壓縮。

注意

Streaming啟用旗標時（預設值），SDK 不會緩衝記憶體中的所有回應數據;而是會在呼叫端要求時，從服務「提取」數據。 在此情況下，呼叫端必須正確地處置數據，例如 IDataReader，一旦完成讀取數據，因為與服務的網路聯機會不必要地保持開啟。

範例

下列範例示範如何使用 C# 設定連線。 如需其他語言的範例，請參閱應用程式驗證方法。

Microsoft Entra ID 同盟驗證與目前的使用者身分識別

下列範例示範如何使用 Microsoft Entra ID 來設定與 Kusto 服務的聯機以進行同盟驗證。 如有需要，系統會提示使用者輸入認證。

var kustoUri = "serviceURI";
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}"

Microsoft Entra ID 同盟驗證與使用者標識元提示

下列範例示範如何使用 Microsoft Entra ID 來設定 Kusto 服務的連線以進行同盟驗證，並使用 變數預先填入使用者的身分 userID 識別。 如有需要，系統會提示使用者輸入認證。

var kustoUri = "serviceURI";
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 同盟應用程式驗證

下列範例示範如何使用 Microsoft Entra ID 向 Kusto 服務進行驗證，以搭配應用程式用戶端標識碼和密鑰進行同盟驗證。

var kustoUri = "serviceURI";
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}"

Microsoft Entra ID 同盟驗證與使用者和應用程式令牌

下列範例示範如何使用 Microsoft Entra ID 搭配使用者存取令牌或應用程式存取令牌來設定 Kusto 服務的連線。

var kustoUri = "serviceURI";
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}"

使用令牌提供者回呼進行驗證

下列範例示範如何使用 Microsoft Entra ID 搭配自定義令牌提供者回呼，向 Kusto 服務進行驗證。 每次需要令牌時，都會叫用令牌。

var kustoUri = "serviceURI";
Func<string> tokenProviderCallback; // User-defined method to retrieve the access token
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
    .WithAadTokenProviderAuthentication(tokenProviderCallback);

使用 X.509 憑證進行驗證

下列範例示範如何使用 Microsoft Entra ID 向 Kusto 服務進行驗證，以搭配應用程式憑證進行同盟驗證。

var kustoUri = "serviceURI";
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 憑證指紋進行驗證

下列範例示範如何使用具有應用程式憑證指紋的 Microsoft Entra ID 來設定 Kusto 服務的聯機。 用戶端會嘗試從本地存儲載入憑證。

var kustoUri = "serviceURI";
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}"

相關內容

• 連接字串概觀
• Kusto API
• Kusto 查詢語言 （KQL）