Kusto 連接字串

  • 發行項

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

注意

  • 屬性名稱不區分大小寫。
  • 屬性值會區分大小寫。
  • 忽略名稱/值參數組之間的空格。
  • 包含分號 (;)、單引號 (') 或雙引號 (") 的屬性值，必須以雙引號括住。

數個 Kusto 用戶端工具支援透過連接字串 URI 前置詞的擴充功能，允許使用 ClusterName/InitialCatalog的 @ 速記格式。 例如，這些工具會將連接字串 @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 類別將端點新增至受信任的端點清單。 使用 SetOverridePolicy 覆寫預設原則，以及 AddTrustedHosts 將新專案新增至現有原則。

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 設定為 strongconsistency 或 weakconsistency ，以判斷查詢是否應該與元資料同步處理，再執行。

使用者驗證屬性

屬性名稱 程式設計名稱 Description
Microsoft Entra識別碼同盟安全性

別名：同盟安全性、同盟、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 (選擇性)
- 追蹤的使用者名稱 (選擇性)

應用程式驗證屬性

屬性名稱 程式設計名稱 Description
Microsoft Entra識別碼同盟安全性

別名：同盟安全性、同盟、Fed、AADFed		 FederatedSecurity 布林值，指示用戶端執行識別碼同盟驗證Microsoft Entra。
應用程式憑證 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 Entra應用程式主體名稱驗證 - 應用程式用戶端識別碼
- 應用程式憑證主體辨別名稱
- 授權單位識別碼
和 Azure 區域 (選擇性)
- 追蹤應用程式名稱 (選擇性)
Microsoft Entra應用程式權杖驗證 - 應用程式權杖
- 追蹤 (選擇性) 的應用程式名稱

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

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

用戶端通訊屬性

屬性名稱 程式設計名稱 Description
接受 接受 布林值，要求在失敗時傳回詳細的錯誤物件。
串流 串流 布林值，要求用戶端在提供給呼叫端之前不會累積資料。 此為預設行為。
未壓縮 未壓縮 布林值，要求用戶端不會要求傳輸層級壓縮。

注意

Streaming當旗標啟用 (為預設) 時，SDK 不會緩衝記憶體中的所有回應資料;而是會在呼叫端要求時，從服務「提取」資料。 因此，在此情況下，呼叫端必須正確地處置資料 (，例如 IDataReader 在讀取資料之後) ，因為服務的網路連線會不必要地保持開啟狀態。

範例

Microsoft Entra使用目前登入的使用者身分識別 (使用者身分識別同盟驗證，如有需要，系統會提示使用者) 

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}"

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識別碼同盟應用程式驗證

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}"

使用系統指派的受控識別

var kustoUri = "https://<clusterName>.<region>.kusto.windows.net";
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
    .WithAadSystemManagedIdentity();

使用使用者指派的受控識別

var kustoUri = "https://<clusterName>.<region>.kusto.windows.net";
var managedIdentityClientId = "<managedIdentityClientId>";
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
    .WithAadUserManagedIdentity(managedIdentityClientId);

使用使用者/應用程式權杖Microsoft Entra識別碼同盟驗證

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}"