Kusto bağlantı dizeleriKusto connection strings

Kusto bağlantı dizeleri, bir kusto istemci uygulaması için gereken bilgileri bir kusto hizmet uç noktasıyla bağlantı kuracak şekilde sağlayabilir.Kusto connection strings can provide the information necessary for a Kusto client application to establish a connection to a Kusto service endpoint. Kusto bağlantı dizeleri, ADO.NET bağlantı dizelerinden sonra modellenir.Kusto connection strings are modeled after the ADO.NET connection strings. Diğer bir deyişle, bağlantı dizesi, isteğe bağlı olarak tek bir URI tarafından ön ekli olan, noktalı virgülle ayrılmış bir ad/değer parametre çiftleri listesidir.That is, the connection string is a semicolon-delimited list of name/value parameter pairs, optionally prefixed by a single URI.

ÖrneğindeExample:

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

URI, ile iletişim kurmak için hizmet uç noktasını sağlar:The URI provides the service endpoint to communicate with:

  • ( https://help.kusto.windows.net )- Data Source özelliğin değeri.(https://help.kusto.windows.net) - value of the Data Source property.
  • Samples(varsayılan veritabanı)- Initial Catalog özelliğin değeri.Samples(default database) - value of theInitial Catalog property.

Ad/değer sözdizimi kullanılarak iki ek özellik sağlanır:Two additional properties are provided using the name/value syntax:

  • Fedözelliği olarak ayarlanan Özellik (da denir AAD Federated Security ) true .Fed property (also called AAD Federated Security) set to true.
  • Acceptözelliği olarak ayarlandı true .Accept property set to true.

Not

  • Özellik adları büyük/küçük harfe duyarlı değildir ve ad/değer çiftleri arasındaki boşluklar yok sayılır.Property names are not case sensitive, and spaces between name/value pairs are ignored.
  • Özellik değerleri büyük /küçük harfe duyarlıdır.Property values are case sensitive. Noktalı virgül ( ; ), tek tırnak işareti ( ' ) veya çift tırnak işareti () içeren bir özellik değeri " çift tırnak işaretleri arasında olmalıdır.A property value that contains a semicolon (;), a single quotation mark ('), or a double quotation mark (") must be enclosed between double quotation marks.

Çeşitli kusto istemci araçları, bağlantı dizesinin URI ön eki üzerinden bir uzantıyı destekler, bu, kısayol biçiminde @ clustername / InitialCatalog kullanılmasına izin verir.Several 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. Örneğin, bağlantı dizesi @help/Samples Bu araçların tarafından çevrilerek https://help.kusto.windows.net/Samples; Fed=true üç özelliği ( Data Source , Initial Catalog , ve AAD Federated Security ) gösterir.For example, the connection string @help/Samples is translated by these tools to https://help.kusto.windows.net/Samples; Fed=true, which indicates three properties (Data Source, Initial Catalog, and AAD Federated Security).

Programlı olarak, kusto bağlantı dizeleri C# sınıfı tarafından ayrıştırılabilir ve değiştirilebilir Kusto.Data.KustoConnectionStringBuilder .Programmatically, Kusto connection strings can be parsed and manipulated by the C# Kusto.Data.KustoConnectionStringBuilder class. Bu sınıf tüm bağlantı dizelerini doğrular ve doğrulama başarısız olursa bir çalışma zamanı özel durumu oluşturur.This class validates all connection strings and generates a runtime exception if validation fails. Bu işlevsellik, kusto SDK 'sının tüm türleri içinde mevcuttur.This functionality is present in all flavors of Kusto SDK.

Bağlantı dizesi özellikleriConnection string properties

Aşağıdaki tabloda, bir kusto bağlantı dizesinde belirtebileceğiniz tüm özellikler listelenmiştir.The following table lists all the properties you can specify in a Kusto connection string. Programlı adları (nesne içindeki özelliğin adı Kusto.Data.KustoConnectionStringBuilder ) ve diğer adlar olan ek özellik adlarını listeler.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.

Genel ÖzelliklerGeneral properties

Özellik adıProperty name Alternatif adlarAlternative names Programlı adProgrammatic name AçıklamaDescription
Izleme için istemci sürümüClient Version for Tracing TraceClientVersionTraceClientVersion İstemci sürümünü izlerken, bu değeri kullanınWhen tracing the client version, use this value
veri kaynağıData Source ADR, adres, ağ adresi, sunucuAddr, Address, Network Address, Server DataSourceDataSource Kusto hizmeti uç noktasını belirten URI.The URI specifying the Kusto service endpoint. Örneğin https://mycluster.kusto.windows.net veya net.tcp://localhost olabilir.For example, https://mycluster.kusto.windows.net or net.tcp://localhost
İlk KatalogInitial Catalog VeritabanıDatabase InitialCatalogInitialCatalog Varsayılan olarak kullanılacak veritabanının adı.The name of the database to be used by default. Örneğin, MyDatabaseFor example, MyDatabase
Sorgu tutarlılığıQuery Consistency QuerytutarlılığıQueryConsistency QuerytutarlılığıQueryConsistency strongconsistency weakconsistency Sorgunun çalıştırılmadan önce meta verilerle eşitlenmesi gerekip gerekmediğini öğrenmek için veya olarak ayarlayınSet to either strongconsistency or weakconsistency to determine if the query should synchronize with the metadata before running

Kullanıcı kimlik doğrulama özellikleriUser authentication properties

Özellik adıProperty name Alternatif adlarAlternative names Programlı adProgrammatic name AçıklamaDescription
AAD Federasyon güvenliğiAAD Federated Security Federal güvenlik, federal, beslenir, AadbesdeFederated Security, Federated, Fed, AADFed FederatedgüvenliğiFederatedSecurity İstemcinin Azure etkin gerçekleştirmesini sağlayan bir Boole değeriA Boolean value that instructs the client to perform Azure Active
MFA zorlaEnforce MFA MFA, EnforceMFAMFA,EnforceMFA EnforceMfaEnforceMfa İstemciye bir çok faktörlü-Authentication belirteci edinmesini sağlayan bir Boole değeriA Boolean value that instructs the client to acquire a multifactor-authentication token
Kullanıcı KimliğiUser ID UID, KullanıcıUID, User UserIDUserID İstemciye, belirtilen Kullanıcı adı ile Kullanıcı kimlik doğrulaması gerçekleştirmesini bildiren bir dize değeriA String value that instructs the client to perform user authentication with the indicated user name
Izleme için Kullanıcı adıUser Name for Tracing TraceUserNameTraceUserName İstek dahili olarak izlenirken kullanılacak kullanıcı adına hizmet veren bir dize değeriA String value that reports to the service which user name to use when tracing the request internally
Kullanıcı belirteciUser Token UsrToken, UserTokenUsrToken, UserToken UserTokenUserToken İstemciye, belirtilen taşıyıcı belirteciyle Kullanıcı kimlik doğrulaması gerçekleştirmesini yönlendiren bir dize değeri.A String value that instructs the client to perform user authentication with the specified bearer token.
Applicationclientıd, ApplicationKey ve ApplicationToken geçersiz kılar.Overrides ApplicationClientId, ApplicationKey, and ApplicationToken. (Belirtilmişse, belirtilen belirtecin yerine gerçek istemci kimlik doğrulama akışını atlar.)(If specified, skips the actual client authentication flow in favor of the provided token.)
Ad AlanıNamespace NSNS Ad AlanıNamespace (Gelecekte kullanılmak üzere)(For future use)

Uygulama kimlik doğrulaması özellikleriApplication authentication properties

Özellik adıProperty name Alternatif adlarAlternative names Programlı adProgrammatic name AçıklamaDescription
AAD Federasyon güvenliğiAAD Federated Security Federal güvenlik, federal, beslenir, AadbesdeFederated Security, Federated, Fed, AADFed FederatedgüvenliğiFederatedSecurity İstemcinin Azure Active Directory (AAD) federal kimlik doğrulaması gerçekleştirmesini sağlayan bir Boole değeriA Boolean value that instructs the client to perform Azure Active Directory (AAD) federated authentication
Uygulama sertifikası Parmak IziApplication Certificate Thumbprint AppCertAppCert ApplicationCertificateThumbprintApplicationCertificateThumbprint Bir uygulama istemci sertifikası kimlik doğrulaması akışı kullanılırken kullanılacak istemci sertifikasının parmak izini sağlayan bir dize değeriA String value that provides the thumbprint of the client certificate to use when using an application client certificate authenticating flow
Uygulama Istemci kimliğiApplication Client Id AppclientıdAppClientId ApplicationclientıdApplicationClientId Kimlik doğrulanırken kullanılacak uygulama istemci KIMLIĞINI sağlayan bir dize değeriA String value that provides the application client ID to use when authenticating
Uygulama anahtarıApplication Key AppKeyAppKey ApplicationKeyApplicationKey Uygulama gizli dizisi kullanılarak kimlik doğrulanırken kullanılacak uygulama anahtarını sağlayan bir dize değeriA String value that provides the application key to use when authenticating using an application secret flow
Izleme için uygulama adıApplication Name for Tracing TraceAppNameTraceAppName ApplicationNameForTracingApplicationNameForTracing İsteği dahili olarak izlerken kullanılacak uygulama adının hizmete rapor veren bir dize değeriA String value that reports to the service which application name to use when tracing the request internally
Uygulama belirteciApplication Token AppTokenAppToken ApplicationTokenApplicationToken İstemciye belirtilen taşıyıcı belirteciyle uygulama kimlik doğrulamasını gerçekleştirmesini bildiren bir dize değeriA String value that instructs the client to perform application authenticating with the specified bearer token
Yetkili kimliğiAuthority Id TenantIdTenantId YetkiliAuthority Uygulamanın kaydedildiği kiracının adını veya KIMLIĞINI sağlayan bir dize değeriA String value that provides the name or ID of the tenant in which the application is registered
EmbeddedmanagedıdentityEmbeddedManagedIdentity İstemciye, yönetilen kimlik doğrulama ile hangi uygulama kimliğini kullanacağınızı bildiren bir dize değeri; systemsistem tarafından atanan kimliği belirtmek için kullanın.A String value that instructs the client which application identity to use with managed identity authentication; use system to indicate the system-assigned identity. Bu özellik yalnızca program aracılığıyla bir bağlantı dizesiyle ayarlanamaz.This property cannot be set with a connection string, only programmatically. ManagedserviceıdentityManagedServiceIdentity TODOTODO
Uygulama sertifikası konusu ayırt edici adıApplication Certificate Subject Distinguished Name Uygulama sertifikası konusuApplication Certificate Subject ApplicationCertificateSubjectDistinguishedNameApplicationCertificateSubjectDistinguishedName
Uygulama sertifikası verenin ayırt edici adıApplication Certificate Issuer Distinguished Name Uygulama sertifikasını verenApplication Certificate Issuer ApplicationCertificateIssuerDistinguishedNameApplicationCertificateIssuerDistinguishedName
Uygulama sertifikası ortak sertifika gönderApplication Certificate Send Public Certificate Uygulama sertifikası SendX5c, SendX5cApplication Certificate SendX5c, SendX5c ApplicationCertificateSendPublicCertificateApplicationCertificateSendPublicCertificate

İstemci iletişim özellikleriClient communication properties

Özellik adıProperty name Alternatif adlarAlternative names Programlı adProgrammatic name AçıklamaDescription
Kabul EtAccept Kabul EtAccept Hata durumunda döndürülecek ayrıntılı hata nesnelerini isteyen bir Boole değeri.A Boolean value that requests detailed error objects to be returned on failure.
AkışStreaming AkışStreaming İstemci isteyen bir Boole değeri, çağrıyı yapana girmeden önce verileri birikmez.A Boolean value that requests the client will not accumulate data before providing it to the caller.
SıkıştırılmamışUncompressed SıkıştırılmamışUncompressed İstemci isteyen bir Boole değeri, Aktarım düzeyinde sıkıştırmayı istemez.A Boolean value that requests the client will not ask for transport-level compression.

Kimlik doğrulama özellikleri (Ayrıntılar)Authentication properties (details)

Bağlantı dizesinin önemli görevlerden biri, istemciye hizmetin kimliğini nasıl doğrulayacağınızı söyleyecektir.One of the important tasks of the connection string is to tell the client how to authenticate to the service. Aşağıdaki algoritma genellikle istemciler tarafından HTTP/HTTPS uç noktalarında kimlik doğrulaması için kullanılır:The following algorithm is generally used by clients for authentication against HTTP/HTTPS endpoints:

  1. AadFederatedSecurity true ise:If AadFederatedSecurity is true:

    1. UserToken belirtilmişse, belirtilen belirteçle AAD federal kimlik doğrulaması kullanIf UserToken is specified, use AAD federated authentication with the specified token
    2. Aksi takdirde, ApplicationToken belirtilmişse, belirtilen belirteçle federal kimlik doğrulaması gerçekleştirinOtherwise, if ApplicationToken is specified, perform federated authentication with the specified token
    3. Aksi takdirde, Applicationclientıd ve ApplicationKey belirtilmişse, belirtilen uygulama istemci KIMLIĞI ve anahtarıyla Federasyon kimlik doğrulaması gerçekleştirinOtherwise, if ApplicationClientId and ApplicationKey are specified, perform federated authentication with the specified application client ID and key
    4. Aksi takdirde, Applicationclientıd ve ApplicationCertificateThumbprint belirtilmişse, belirtilen uygulama istemci KIMLIĞI ve sertifikasıyla federal kimlik doğrulaması gerçekleştirinOtherwise, if ApplicationClientId and ApplicationCertificateThumbprint are specified, perform federated authentication with the specified application client ID and certificate
    5. Aksi takdirde, geçerli oturum açan kullanıcının kimliğiyle federal kimlik doğrulaması gerçekleştirin (Bu, oturumdaki ilk kimlik doğrulaması ise kullanıcıya sorulur)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. Aksi takdirde kimlik doğrulaması yapın.Otherwise do not authenticate.

Uygulama sertifikasıyla AAD Federasyon uygulaması kimlik doğrulamasıAAD federated application authentication with application certificate

  1. Uygulamanın sertifikasını temel alan kimlik doğrulaması yalnızca Web uygulamaları için desteklenir (yerel istemci uygulamaları için değildir).Authentication based on an application's certificate is supported only for web applications (and not for native client applications).
  2. Web uygulaması, verilen sertifikayı kabul edecek şekilde yapılandırılmalıdır.The web application should be configured to accept the given certificate. AAD uygulamasının sertifikası temelinde kimlik doğrulamaHow to authentication based-on AAD application's certificate
  3. Web uygulaması, ilgili kusto kümesinde yetkili sorumlu olarak yapılandırılmalıdır.The web application should be configured as an authorized principal in the relevant Kusto cluster.
  4. Belirtilen parmak izine sahip sertifika yüklenmelidir (yerel makine deposunda veya geçerli kullanıcı deposunda).The certificate with the given thumbprint should be installed (in Local Machine store or in Current User store).
  5. Sertifikanın ortak anahtarı en az 2048 bit içermelidir.The certificate's public key should contain at least 2048 bits.

AAD tabanlı kimlik doğrulama örnekleriAAD-based authentication examples

Şu anda oturum açmış olan kullanıcı kimliğini kullanan AAD federal kimlik doğrulaması (gerekli olduğunda Kullanıcı sorulur)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.windows.net";
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}"

Kullanıcı kimliği ipucuyla birlikte AAD federal kimlik doğrulaması (gerekli olduğunda Kullanıcı sorulur)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.windows.net";
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}"

Applicationclientıd ve ApplicationKey kullanılarak AAD federal uygulama kimlik doğrulamasıAAD Federated application authentication using ApplicationClientId and ApplicationKey

var serviceUri = "Service URI, typically of the form https://cluster.region.kusto.windows.net";
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}"

Kullanıcı/uygulama belirtecini kullanarak AAD federal kimlik doğrulamasıAAD Federated authentication using user / application token

var serviceUri = "Service URI, typically of the form https://cluster.region.kusto.windows.net";
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}"

Belirteç sağlayıcısı geri çağırma kullanma (bir belirteç gerektiğinde çağrılır)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.windows.net";
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()),
};

Yönetilen kimliği kullanmaUsing Managed Identity

var serviceUri = "Service URI, typically of the form https://cluster.region.kusto.windows.net";
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.440 sertifikası kullanmaUsing X.509 certificate

var serviceUri = "Service URI, typically of the form https://cluster.region.kusto.windows.net";
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,
};

Parmak izine göre X. 509.440 sertifikasını kullanma (istemci, sertifikayı yerel depodan yüklemeye çalışır)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.windows.net";
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}"