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

Kusto 连接字符串

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

例如,以下 Kusto 连接字符串以 URI 开头,该 URI 指定用于通信的服务终结点:https://help.kusto.windows.net。 此 URI 分配给 Data Source 属性。 接下来,连接字符串中的 /Samples 代表默认数据库,分配给 Initial Catalog 属性。 最后,另外两个属性 FedAccept 为连接提供进一步的配置或自定义选项。

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 跟踪客户端版本时,请使用此属性。
数据源

别名:地址、网络地址、服务器
数据源 指定 Kusto 服务终结点的 URI。 例如 https://mycluster.kusto.windows.net
初始目录

别名:数据库
InitialCatalog 将在默认情况下使用的数据库的名称。 例如 MyDatabase
查询一致性

别名:QueryConsistency
QueryConsistency 设置为 strongconsistencyweakconsistency,用于决定查询在运行之前是否应与元数据同步。

用户身份验证属性

属性名称 编程名称 说明
Microsoft Entra ID 联合安全性

别名:Federated Security、Federated、Fed、AADFed
FederatedSecurity 一个布尔值,指示客户端执行Microsoft Entra身份验证。
颁发机构 ID

别名:TenantId
颁发机构 一个字符串值,该值提供用户的租户的名称或 ID。 默认值为 microsoft.com。 有关详细信息,请参阅Microsoft Entra机构
强制执行 MFA

别名:MFA、EnforceMFA
EnforceMfa 一个可选布尔值,指示客户端获取多重身份验证令牌。
用户 ID

别名:UID、用户
UserID 一个字符串值,指示客户端使用指定的用户名执行用户身份验证。
跟踪的用户名 TraceUserName 一个可选字符串值,用于向服务报告在内部跟踪请求时使用的用户名。
用户令牌

别名:UsrToken、UserToken
UserToken 一个字符串值,指示客户端使用指定的持有者令牌执行用户身份验证。

可覆盖 ApplicationClientIdApplicationKeyApplicationToken。 如果指定了此项,则会跳过实际的客户端身份验证流,转而使用提供的令牌。

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

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

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

应用程序身份验证属性

属性名称 编程名称 说明
Microsoft Entra ID 联合安全性

别名:Federated Security、Federated、Fed、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. 证书的公钥应至少包含 2048 位。

客户端通信属性

属性名称 编程名称 说明
Accept Accept 一个布尔值,它请求失败时返回的详细错误对象。
流式处理 流式处理 一个布尔值,它请求客户端在将数据提供给调用方之前不累积数据。 这是默认行为。
未压缩 未压缩 一个布尔值,它请求客户端不要求进行传输级压缩。

注意

启用 Streaming 标志(默认情况)后,SDK 不会将所有响应数据缓存在内存中;相反,它会在调用方请求时从服务中“拉取”数据。 因此,在这种情况下,调用方必须在完成数据读取后正确释放数据(例如 IDataReader),因为与服务的网络连接会不必要地保持打开状态。

示例

如果需要,系统将提示使用当前登录的用户标识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}"

如果需要,将提示Microsoft Entra ID 联合身份验证与用户 ID 提示 ()

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

使用系统分配的托管标识

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