你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Kusto 连接字符串

适用于：✅Microsoft Fabric✅Azure 数据资源管理器

Kusto 连接字符串为 Kusto 客户端应用程序提供与 Kusto 服务终结点建立连接所需的信息。 Kusto 连接字符串借鉴了 ADO.NET 连接字符串。 也就是说，连接字符串是一个以分号分隔的名称-值参数对列表，可以用单个 URI 作为前缀。

例如，以下 Kusto 连接字符串以 URI 开头，该 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	跟踪客户端版本时使用的属性。
数据源 别名：地址、网络地址、服务器	数据源	指定 Kusto 服务终结点的 URI。 例如，https://mycluster.kusto.windows.net。
初始目录 别名：数据库	InitialCatalog	默认数据库名称。 例如，MyDatabase。
查询一致性 别名：QueryConsistency	QueryConsistency	设置为 strongconsistency 或 weakconsistency，用于决定查询在运行之前是否应与元数据同步。

用户身份验证属性

属性名称	编程名称	说明
Microsoft Entra ID 联合安全 别名：联合安全、联合、AADFed	FederatedSecurity	一个布尔值，指示客户端执行 Microsoft Entra 身份验证。
颁发机构 ID 别名：TenantId	颁发机构	一个字符串值，该值提供用户的租户的名称或 ID。 默认值为 microsoft.com。 有关详细信息，请参阅 Microsoft Entra 颁发机构。
强制执行 MFA 别名：MFA、EnforceMFA	EnforceMfa	一个可选的布尔值，指示客户端获取多重身份验证令牌。
用户 ID 别名：UID、用户	UserID	一个字符串值，指示客户端使用指定的用户名执行用户身份验证。
跟踪的用户名	TraceUserName	一个可选字符串值，用于向服务报告在内部跟踪请求时使用的用户名。
用户令牌 别名：UsrToken、UserToken	UserToken	一个字符串值，指示客户端使用指定的持有者令牌执行用户身份验证。 可覆盖 ApplicationClientId、ApplicationKey 和 ApplicationToken。 如果指定了此项，则会跳过实际的客户端身份验证流，转而使用提供的令牌。

用户身份验证支持的属性组合

对于用户身份验证，请将 AAD Federated Security 指定为 true。 然后，选择以下身份验证模式之一，并指定该模式的相关属性。

身份验证模式	属性名称
Microsoft Entra 用户提示身份验证	- 用户 ID（可选） - 颁发机构 ID（可选） - 强制执行 MFA（可选） - 跟踪的用户名（可选）
Microsoft Entra 用户令牌身份验证	- 用户令牌 - 强制执行 MFA（可选） - 跟踪的用户名（可选）

应用程序身份验证属性

属性名称	编程名称	说明
Microsoft Entra ID 联合安全 别名：联合安全、联合、AADFed	FederatedSecurity	一个布尔值，指示客户端执行 Microsoft Entra ID 联合身份验证。
应用程序证书 SendX5c 别名：应用程序证书发送公共证书、SendX5c	ApplicationCertificateSendX5c	一个布尔值，指示客户端执行基于使用者名称和证书颁发者的身份验证。
应用程序证书指纹 别名：AppCert	ApplicationCertificateThumbprint	一个字符串值，该值提供使用应用程序客户端证书身份验证流时要使用的客户端证书的指纹。
应用程序客户端 ID 别名：AppClientId	ApplicationClientId	一个字符串值，该值提供进行身份验证时要使用的应用程序客户端 ID。
应用程序密钥 别名：AppKey	ApplicationKey	一个字符串值，该值提供使用应用程序机密流进行身份验证时要使用的应用程序密钥。
跟踪的应用程序名称 别名：TraceAppName	ApplicationNameForTracing	一个可选字符串值，用于向服务报告在内部跟踪请求时使用的应用程序名称。
应用程序令牌 别名：AppToken	ApplicationToken	一个字符串值，指示客户端使用指定的持有者令牌执行应用程序身份验证。
颁发机构 ID 别名：TenantId	颁发机构	一个字符串值，该值提供在其中注册应用程序的租户的名称或 ID。 默认值为 microsoft.com。 有关详细信息，请参阅 Microsoft Entra 颁发机构。
Azure 区域 别名：AzureRegion、区域	AzureRegion	一个字符串值，该值提供可在其中进行身份验证的 Azure 区域的名称。
ManagedServiceIdentity	EmbeddedManagedIdentity	一个字符串值，指示客户端使用哪个应用程序标识进行托管标识身份验证。 使用 system 指示系统分配的标识。 此属性不能通过连接字符串进行设置，只能以编程方式设置。
应用程序证书使用者可分辨名称 别名：应用程序证书使用者	ApplicationCertificateSubjectDistinguishedName	一个字符串值，指定应用程序证书使用者可分辨名称。
应用程序证书颁发者可分辨名称 别名：应用程序证书颁发者	ApplicationCertificateIssuerDistinguishedName	一个字符串值，指定应用程序证书颁发者可分辨名称。

应用程序身份验证支持的属性组合

对于应用程序身份验证，请将 AAD Federated Security 指定为 true。 然后，选择以下身份验证模式之一，并指定该模式的相关属性。

身份验证模式	属性名称
Microsoft Entra 应用程序密钥身份验证	- 应用程序客户端 ID - 应用程序密钥 - 颁发机构 ID - 跟踪的应用程序名称（可选）
Microsoft Entra 应用程序指纹身份验证	- 应用程序客户端 ID - 应用程序证书指纹 - 颁发机构 ID - 跟踪的应用程序名称（可选）
Microsoft Entra 应用程序主体和颁发者身份验证	- 应用程序客户端 ID - 应用程序证书使用者可分辨名称 - 应用程序证书颁发者可分辨名称 - 颁发机构 ID - Azure 区域（可选） - 应用程序证书 SendX5c（可选） - 跟踪的应用程序名称（可选）
Microsoft Entra 应用程序主体名称身份验证	- 应用程序客户端 ID - 应用程序证书使用者可分辨名称 - 颁发机构 ID - Azure 区域（可选） - 跟踪的应用程序名称（可选）
Microsoft Entra 应用程序令牌身份验证	- 应用程序令牌 - 跟踪的应用程序名称（可选）

使用应用程序证书进行身份验证

1. 应将应用程序配置为接受给定的证书。 如何基于 Microsoft Entra 应用程序证书进行身份验证。
2. 应将应用程序配置为相关 Kusto 环境中的授权主体。
3. 需要安装证书，安装位置为本地计算机存储或当前用户存储。
4. 证书的公钥应至少包含 2,048 位。

客户端通信属性

属性名称	编程名称	说明
Accept	Accept	一个布尔值，它请求失败时返回的详细错误对象。
流式处理	流式处理	一个布尔值，它请求客户端立即向调用方提供数据，而无需先累积数据。 流式处理是默认行为。
未压缩	未压缩	指示客户端避免请求传输级压缩的布尔值。

注意

Streaming启用标志（默认值）时，SDK 不会缓冲内存中的所有响应数据;而是在调用方请求时从服务“拉取”数据。 因此，在这种情况下，调用方必须正确处理数据，例如 IDataReader。 读取数据后，将不必要地打开与服务的网络连接。

示例

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

使用用户 ID 提示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 服务进行身份验证，以便通过应用程序客户端 ID 和密钥进行联合身份验证。

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