Kusto 连接字符串Kusto connection strings

Kusto 连接字符串可以为 Kusto 客户端应用程序提供与 Kusto 服务终结点建立连接所需的信息。Kusto connection strings can provide the information necessary for a Kusto client application to establish a connection to a Kusto service endpoint. Kusto 连接字符串借鉴了 ADO.NET 连接字符串。Kusto connection strings are modeled after the ADO.NET connection strings. 也就是说,连接字符串是一个以分号分隔的名称/值参数对列表,可以用单个 URI 作为前缀。That is, the connection string is a semicolon-delimited list of name/value parameter pairs, optionally prefixed by a single URI.

示例:Example:

https://help.kusto.chinacloudapi.cn/Samples; Fed=true; Accept=true

URI 提供要与之通信的服务终结点:The URI provides the service endpoint to communicate with:

  • (https://help.kusto.chinacloudapi.cn) - Data Source 属性的值。(https://help.kusto.chinacloudapi.cn) - value of the Data Source property.
  • Samples(默认数据库)- Initial Catalog 属性的值。Samples(default database) - value of theInitial Catalog property.

使用名称/值语法提供两个附加属性:Two additional properties are provided using the name/value syntax:

  • Fed 属性(也称为 AAD Federated Security)设置为 trueFed property (also called AAD Federated Security) set to true.
  • Accept 属性设置为 trueAccept property set to true.

备注

  • 属性名称不区分大小写,并且忽略名称/值对之间的空格。Property names are not case sensitive, and spaces between name/value pairs are ignored.
  • 属性值区分大小写。Property values are case sensitive. 包含分号 (;)、单引号 (') 或双引号 (") 的属性值必须用双引号引起来。A property value that contains a semicolon (;), a single quotation mark ('), or a double quotation mark (") must be enclosed between double quotation marks.

多个 Kusto 客户端工具支持基于连接字符串的 URI 前缀进行扩展,因为它们允许使用简写格式 @ ClusterName / InitialCatalogSeveral Kusto client tools support an extension over the URI prefix of the connection string, in that they allow the shorthand format @ ClusterName / InitialCatalog to be used. 例如,这些工具将连接字符串 @help/Samples 转换为 https://help.kusto.chinacloudapi.cn/Samples; Fed=true,后者指示三个属性(Data SourceInitial CatalogAAD Federated Security)。For example, the connection string @help/Samples is translated by these tools to https://help.kusto.chinacloudapi.cn/Samples; Fed=true, which indicates three properties (Data Source, Initial Catalog, and AAD Federated Security).

可以采用编程方式通过 C# Kusto.Data.KustoConnectionStringBuilder 类分析和操作 Kusto 连接字符串。Programmatically, Kusto connection strings can be parsed and manipulated by the C# Kusto.Data.KustoConnectionStringBuilder class. 此类验证所有连接字符串,并在验证失败时生成运行时异常。This class validates all connection strings and generates a runtime exception if validation fails. 此功能存在于所有形式的 Kusto SDK 中。This functionality is present in all flavors of Kusto SDK.

连接字符串属性Connection string properties

下表列出了可以在 Kusto 连接字符串中指定的所有属性。The following table lists all the properties you can specify in a Kusto connection string. 它列出了编程名称(属性在 Kusto.Data.KustoConnectionStringBuilder 对象中的名称)以及作为别名的其他属性名称。It lists programmatic names (which is the name of the property in the Kusto.Data.KustoConnectionStringBuilder object) as well as additional property names that are aliases.

常规属性General properties

属性名称Property name 别名Alternative names 编程名称Programmatic name 说明Description
跟踪的客户端版本Client Version for Tracing TraceClientVersionTraceClientVersion 跟踪客户端版本时,请使用此值When tracing the client version, use this value
数据源Data Source 地址、网络地址、服务器Addr, Address, Network Address, Server 数据源DataSource 指定 Kusto 服务终结点的 URI。The URI specifying the Kusto service endpoint. 例如,https://mycluster.kusto.chinacloudapi.cnnet.tcp://localhostFor example, https://mycluster.kusto.chinacloudapi.cn or net.tcp://localhost
初始目录Initial Catalog 数据库Database InitialCatalogInitialCatalog 将在默认情况下使用的数据库的名称。The name of the database to be used by default. 例如 MyDatabaseFor example, MyDatabase
查询一致性Query Consistency QueryConsistencyQueryConsistency QueryConsistencyQueryConsistency 设置为 strongconsistencyweakconsistency,用于决定查询在运行之前是否应与元数据同步Set to either strongconsistency or weakconsistency to determine if the query should synchronize with the metadata before running

用户身份验证属性User authentication properties

属性名称Property name 别名Alternative names 编程名称Programmatic name 说明Description
AAD 联合安全性AAD Federated Security 联合安全性、联合、AADFedFederated Security, Federated, Fed, AADFed FederatedSecurityFederatedSecurity 一个布尔值,指示客户端执行 Azure Active Directory (AAD) 联合身份验证A Boolean value that instructs the client to perform Azure Active
强制执行 MFAEnforce MFA MFA、EnforceMFAMFA,EnforceMFA EnforceMfaEnforceMfa 一个布尔值,指示客户端获取多重身份验证令牌A Boolean value that instructs the client to acquire a multifactor-authentication token
用户 IDUser ID UID、用户UID, User UserIDUserID 一个字符串值,指示客户端使用指定的用户名执行用户身份验证A String value that instructs the client to perform user authentication with the indicated user name
跟踪的用户名User Name for Tracing TraceUserNameTraceUserName 一个字符串值,用于向服务报告在内部跟踪请求时使用的用户名A String value that reports to the service which user name to use when tracing the request internally
用户令牌User Token UsrToken、UserTokenUsrToken, UserToken UserTokenUserToken 一个字符串值,指示客户端使用指定的持有者令牌执行用户身份验证。A String value that instructs the client to perform user authentication with the specified bearer token.
替代 ApplicationClientId、ApplicationKey 和 ApplicationToken。Overrides ApplicationClientId, ApplicationKey, and ApplicationToken. (如果指定了此项,则会跳过实际的客户端身份验证流,转而使用提供的令牌。)(If specified, skips the actual client authentication flow in favor of the provided token.)
命名空间Namespace NSNS 命名空间Namespace (供将来使用)(For future use)

应用程序身份验证属性Application authentication properties

属性名称Property name 别名Alternative names 编程名称Programmatic name 说明Description
AAD 联合安全性AAD Federated Security 联合安全性、联合、AADFedFederated Security, Federated, Fed, AADFed FederatedSecurityFederatedSecurity 一个布尔值,指示客户端执行 Azure Active Directory (AAD) 联合身份验证A Boolean value that instructs the client to perform Azure Active Directory (AAD) federated authentication
应用程序证书指纹Application Certificate Thumbprint AppCertAppCert ApplicationCertificateThumbprintApplicationCertificateThumbprint 一个字符串值,该值提供使用应用程序客户端证书身份验证流时要使用的客户端证书的指纹A String value that provides the thumbprint of the client certificate to use when using an application client certificate authenticating flow
应用程序客户端 IDApplication Client Id AppClientIdAppClientId ApplicationClientIdApplicationClientId 一个字符串值,该值提供进行身份验证时要使用的应用程序客户端 IDA String value that provides the application client ID to use when authenticating
应用程序密钥Application Key AppKeyAppKey ApplicationKeyApplicationKey 一个字符串值,该值提供使用应用程序机密流进行身份验证时要使用的应用程序密钥A String value that provides the application key to use when authenticating using an application secret flow
跟踪的应用程序名称Application Name for Tracing TraceAppNameTraceAppName ApplicationNameForTracingApplicationNameForTracing 一个字符串值,用于向服务报告在内部跟踪请求时使用的应用程序名称A String value that reports to the service which application name to use when tracing the request internally
应用程序令牌Application Token AppTokenAppToken ApplicationTokenApplicationToken 一个字符串值,指示客户端使用指定的持有者令牌执行应用程序身份验证A String value that instructs the client to perform application authenticating with the specified bearer token
颁发机构 IDAuthority Id TenantIdTenantId 颁发机构Authority 一个字符串值,该值提供在其中注册应用程序的租户的名称或 IDA String value that provides the name or ID of the tenant in which the application is registered
EmbeddedManagedIdentityEmbeddedManagedIdentity 一个字符串值,指示客户端使用哪个应用程序标识进行托管标识身份验证;使用 system 来指示系统分配的标识。A String value that instructs the client which application identity to use with managed identity authentication; use system to indicate the system-assigned identity. 此属性不能通过连接字符串进行设置,只能以编程方式设置。This property cannot be set with a connection string, only programmatically. ManagedServiceIdentityManagedServiceIdentity TODOTODO
应用程序证书使用者可分辨名称Application Certificate Subject Distinguished Name 应用程序证书使用者Application Certificate Subject ApplicationCertificateSubjectDistinguishedNameApplicationCertificateSubjectDistinguishedName
应用程序证书颁发者可分辨名称Application Certificate Issuer Distinguished Name 应用程序证书颁发者Application Certificate Issuer ApplicationCertificateIssuerDistinguishedNameApplicationCertificateIssuerDistinguishedName
应用程序证书发送公共证书Application Certificate Send Public Certificate 应用程序证书 SendX5c、SendX5cApplication Certificate SendX5c, SendX5c ApplicationCertificateSendPublicCertificateApplicationCertificateSendPublicCertificate

客户端通信属性Client communication properties

属性名称Property name 别名Alternative names 编程名称Programmatic name 说明Description
AcceptAccept AcceptAccept 一个布尔值,它请求失败时返回的详细错误对象。A Boolean value that requests detailed error objects to be returned on failure.
流式处理Streaming 流式处理Streaming 一个布尔值,它请求客户端在将数据提供给调用方之前不累积数据。A Boolean value that requests the client will not accumulate data before providing it to the caller.
未压缩Uncompressed 未压缩Uncompressed 一个布尔值,它请求客户端不要求进行传输级压缩。A Boolean value that requests the client will not ask for transport-level compression.

身份验证属性(详细信息)Authentication properties (details)

连接字符串的重要任务之一是告诉客户端如何向服务进行身份验证。One of the important tasks of the connection string is to tell the client how to authenticate to the service. 客户端针对 HTTP/HTTPS 终结点进行身份验证时通常使用以下算法:The following algorithm is generally used by clients for authentication against HTTP/HTTPS endpoints:

  1. 如果 AadFederatedSecurity 为 true:If AadFederatedSecurity is true:

    1. 如果指定了 UserToken,则使用指定的令牌进行 AAD 联合身份验证If UserToken is specified, use AAD federated authentication with the specified token
    2. 否则,如果指定了 ApplicationToken,则使用指定的令牌执行联合身份验证Otherwise, if ApplicationToken is specified, perform federated authentication with the specified token
    3. 否则,如果指定了 ApplicationClientId 和 ApplicationKey,则使用指定的应用程序客户端 ID 和密钥执行联合身份验证Otherwise, if ApplicationClientId and ApplicationKey are specified, perform federated authentication with the specified application client ID and key
    4. 否则,如果指定了 ApplicationClientId 和 ApplicationCertificateThumbprint,则使用指定的应用程序客户端 ID 和证书执行联合身份验证Otherwise, if ApplicationClientId and ApplicationCertificateThumbprint are specified, perform federated authentication with the specified application client ID and certificate
    5. 否则,将使用当前登录用户的标识执行联合身份验证(如果这是会话中的第一次身份验证,系统会提示用户)Otherwise, perform federated authentication with the current logged-on user's identity (user will be prompted if this is the first authentication in the session)
  2. 否则,不进行身份验证。Otherwise do not authenticate.

使用应用程序证书的 AAD 联合应用程序身份验证AAD federated application authentication with application certificate

  1. 基于应用程序证书的身份验证仅支持 Web 应用程序(不支持原生客户端应用程序)。Authentication based on an application's certificate is supported only for web applications (and not for native client applications).
  2. 应将 Web 应用程序配置为接受给定的证书。The web application should be configured to accept the given certificate. 如何基于 AAD 应用程序的证书进行身份验证How to authentication based-on AAD application's certificate
  3. 应将 Web 应用程序配置为相关 Kusto 群集中的经授权主体。The web application should be configured as an authorized principal in the relevant Kusto cluster.
  4. 应安装具有给定指纹的证书(安装位置为本地计算机存储或当前用户存储)。The certificate with the given thumbprint should be installed (in Local Machine store or in Current User store).
  5. 证书的公钥应至少包含 2048 位。The certificate's public key should contain at least 2048 bits.

基于 AAD 的身份验证示例AAD-based authentication examples

使用当前登录用户标识的 AAD 联合身份验证(系统会根据需要提示用户)AAD Federated authentication using the currently logged-on user identity (user will be prompted if required)

var serviceUri = "Service URI, typically of the form https://cluster.region.kusto.chinacloudapi.cn";
var authority = "contoso.com"; // Or the AAD tenant GUID: "..."

// Recommended syntax
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(serviceUri)
  .WithAadUserPromptAuthentication(authority);

// Legacy syntax
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(serviceUri)
{
    FederatedSecurity = true,
    InitialCatalog = "NetDefaultDB",
    Authority = authority,
};

// Equivalent Kusto connection string: $"Data Source={serviceUri};Database=NetDefaultDB;Fed=True;Authority Id={authority}"

使用用户 ID 提示的 AAD 联合身份验证(系统会根据需要提示用户)AAD Federated authentication with user id hint (user will be prompted if required)

var serviceUri = "Service URI, typically of the form https://cluster.region.kusto.chinacloudapi.cn";
var authority = "contoso.com"; // Or the AAD tenant GUID: "..."
var userUPN = "johndoe@contoso.com";

// Recommended syntax
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(serviceUri)
  .WithAadUserPromptAuthentication(authority);
kustoConnectionStringBuilder.UserID = userUPN;

// Legacy syntax
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(serviceUri)
{
    FederatedSecurity = true,
    InitialCatalog = "NetDefaultDB",
    UserID = userUPN,
    Authority = authority,
};

// Equivalent Kusto connection string: $"Data Source={serviceUri};Database=NetDefaultDB;Fed=True;User ID={userUPN};Authority Id={authority}"

使用 ApplicationClientId 和 ApplicationKey 的 AAD 联合应用程序身份验证AAD Federated application authentication using ApplicationClientId and ApplicationKey

var serviceUri = "Service URI, typically of the form https://cluster.region.kusto.chinacloudapi.cn";
var authority = "contoso.com"; // Or the AAD tenant GUID: "..."
var applicationClientId = <ApplicationClientId>;
var applicationKey = <ApplicationKey>;

// Recommended syntax
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(serviceUri)
    .WithAadApplicationKeyAuthentication(applicationClientId, applicationKey, authority);

// Legacy syntax
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(serviceUri)
{
    FederatedSecurity = true,
    InitialCatalog = "NetDefaultDB",
    ApplicationClientId = applicationClientId,
    ApplicationKey = applicationKey,
    Authority = authority,
};

// Equivalent Kusto connection string: $"Data Source={serviceUri};Database=NetDefaultDB;Fed=True;AppClientId={applicationClientId};AppKey={applicationKey};Authority Id={authority}"

使用用户/应用程序令牌的 AAD 联合身份验证AAD Federated authentication using user / application token

var serviceUri = "Service URI, typically of the form https://cluster.region.kusto.chinacloudapi.cn";
var authority = "contoso.com"; // Or the AAD tenant GUID: "..."
var access_token = "<access token obtained from AAD>"

// Recommended syntax - AAD User token
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(serviceUri)
    .WithAadUserTokenAuthentication(access_token, authority);

// Legacy syntax - AAD User token
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(serviceUri)
{
    FederatedSecurity = true,
    UserToken = access_token,
    Authority = authority,
};

// Equivalent Kusto connection string: "Data Source={serviceUri};Database=NetDefaultDB;Fed=True;UserToken={access_token};Authority Id={authority}"

// Recommended syntax - AAD Application token
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(serviceUri)
    .WithAadApplicationTokenAuthentication(access_token, authority);

// Legacy syntax - AAD Application token
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(serviceUri)
{
    FederatedSecurity = true,
    ApplicationToken = access_token,
    Authority = authority,
};

// Equivalent Kusto connection string: $"Data Source={serviceUri};Database=NetDefaultDB;Fed=True;AppToken={applicationToken};Authority Id={authority}"

使用令牌提供程序回调(将在每次需要令牌时调用)Using token provider callback (will be invoked each time a token is required)

var serviceUri = "Service URI, typically of the form https://cluster.region.kusto.chinacloudapi.cn";
Func<string> tokenProviderCallback; // User-defined method to retrieve the access token

// Recommended syntax
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(serviceUri)
    .WithAadTokenProviderAuthentication(tokenProviderCallback);

// Legacy syntax
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(serviceUri)
{
    FederatedSecurity = true,
    TokenProviderCallback = () => Task.FromResult(tokenProviderCallback()),
};

使用托管标识Using Managed Identity

var serviceUri = "Service URI, typically of the form https://cluster.region.kusto.chinacloudapi.cn";
var managedIdentity = "<managed identity>"; // For system-assigned identity use "system"

// Recommended syntax
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(serviceUri)
    .WithAadManagedIdentity(managedIdentity);

// Legacy syntax
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(serviceUri)
{
    FederatedSecurity = true,
    EmbeddedManagedIdentity = managedIdentity,
};

使用 X.509 证书Using X.509 certificate

var serviceUri = "Service URI, typically of the form https://cluster.region.kusto.chinacloudapi.cn";
var authority = "contoso.com"; // Or the AAD tenant GUID: "..."
string applicationClientId = "<applicationClientId>";
X509Certificate2 applicationCertificate = "<certificate blob>";
bool sendX5c = <desired value>; // Set too 'True' to use Trusted Issuer feature of AAD

// Recommended syntax
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(serviceUri)
    .WithAadApplicationCertificateAuthentication(applicationClientId, applicationCertificate, authority, sendX5c);

// Legacy syntax
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(serviceUri)
{
    FederatedSecurity = true,
    ApplicationClientId = applicationClientId,
    ApplicationCertificateBlob = applicationCertificate,
    ApplicationCertificateSendX5c = sendX5c,
    Authority = authority,
};

使用 X.509 证书的指纹(客户端会尝试从本地存储加载证书)Using X.509 certificate by thumbprint (client will attempt to load the certificate from local store)

var serviceUri = "Service URI, typically of the form https://cluster.region.kusto.chinacloudapi.cn";
var authority = "contoso.com"; // Or the AAD tenant GUID: "..."
string applicationClientId = "<applicationClientId>";
string applicationCertificateThumbprint = "<ApplicationCertificateThumbprint>";

// Recommended syntax
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(serviceUri)
    .WithAadApplicationThumbprintAuthentication(applicationClientId, applicationCertificateThumbprint, authority);

// Legacy syntax
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(serviceUri)
{
    FederatedSecurity = true,
    ApplicationClientId = applicationClientId,
    ApplicationCertificateThumbprint = applicationCertificateThumbprint,
    Authority = authority,
};

// Equivalent Kusto connection string: $"Data Source={serviceUri};Database=NetDefaultDB;Fed=True;AppClientId={applicationClientId};AppCert={applicationCertificateThumbprint};Authority Id={authority}"