Строки подключения Kusto
Область применения: ✅Microsoft Fabric✅Azure Data Explorer
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/Sampleshttps://help.kusto.windows.net/Samples; Fed=trueв .
Программным образом класс C# Kusto.Data.KustoConnectionStringBuilder может анализировать и управлять строка подключения Kusto. Этот класс проверяет все строки подключения, и при сбое проверки выдает исключение во время выполнения. Эта функция присутствует во всех вариантах пакета SDK Kusto.
Доверенные конечные точки
Подключение к конечной точке 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 .
Общие свойства
| Имя свойства | Имя в программном коде | Description |
|---|---|---|
| Версия клиента для трассировки | TraceClientVersion | Свойство, используемое при трассировке версии клиента. |
| Псевдонимы источника данных: Addr, Address, Network Address, Server |
DataSource | Код URI для указания конечной точки службы Data Explorer. Например, https://mycluster.kusto.windows.net. |
| Псевдоним начального каталога : база данных |
InitialCatalog | Имя базы данных по умолчанию. Например, MyDatabase. |
| Псевдоним согласованности запросов: QueryConsistency |
QueryConsistency | Установите значение strongconsistency или weakconsistency определите, должен ли запрос синхронизироваться с метаданными перед выполнением. |
Свойства проверки подлинности пользователя
| Имя свойства | Имя в программном коде | Description |
|---|---|---|
| Псевдонимы федеративной безопасности Microsoft Entra ID: , Федеративная, Федеративная, Fed, AADFed |
FederatedSecurity | Логическое значение, указывающее клиенту выполнять проверку подлинности Microsoft Entra. |
| Псевдоним идентификатора центра: TenantId |
Центр | Строковое значение, которое предоставляет имя или идентификатор клиента пользователя. Значение по умолчанию — microsoft.com. Дополнительные сведения см. в центре Microsoft Entra. |
| Принудительное применение псевдонима MFA: , EnforceMFA |
EnforceMfa | Необязательное логическое значение, указывающее клиенту получить многофакторный маркер проверки подлинности. |
| Псевдонимы идентификаторов пользователя: UID, User |
UserID | Строковое значение, указывающее клиенту выполнять проверку подлинности пользователя с указанным именем пользователя. |
| Имя пользователя для трассировки | TraceUserName | Необязательное строковое значение, которое сообщает службе, имя пользователя которой следует использовать при трассировке запроса внутри. |
| Псевдонимы маркера пользователя: UsrToken, UserToken |
UserToken | Строковое значение, указывающее клиенту выполнять проверку подлинности пользователя с указанным маркером носителя.
Переопределяет ApplicationClientId, ApplicationKeyи ApplicationToken. Если задано, пропускает фактический поток проверки подлинности клиента в пользу предоставленного маркера. |
Поддерживаемые сочетания свойств для проверки подлинности пользователя
Для проверки подлинности пользователя укажите AAD Federated Security как true. Затем выберите один из следующих режимов проверки подлинности и укажите соответствующие свойства для этого режима.
| Режим проверки подлинности | Имена свойств |
|---|---|
| Проверка подлинности пользовательского запроса Microsoft Entra | — идентификатор пользователя (необязательно)- Идентификатор центра (необязательно) - Принудительное применение MFA (необязательно) - Имя пользователя для трассировки (необязательно) |
| Проверка подлинности маркера пользователя Microsoft Entra | — маркер пользователя— принудительное применение MFA (необязательно) - имя пользователя для трассировки (необязательно) |
Свойства проверки подлинности приложения
| Имя свойства | Имя в программном коде | Description |
|---|---|---|
| Псевдонимы федеративной безопасности Microsoft Entra ID: , Федеративная, Федеративная, Fed, AADFed |
FederatedSecurity | Логическое значение, указывающее клиенту выполнять федеративную проверку подлинности идентификатора Microsoft Entra ID. |
| Псевдонимы сертификата приложения SendX5c : сертификат приложения отправляет общедоступный сертификат, SendX5c |
ApplicationCertificateSendX5c | Логическое значение, указывающее клиенту выполнять проверку подлинности на основе субъекта и издателя. |
| Псевдоним сертификата приложения: AppCert |
ApplicationCertificateThumbprint | Строковое значение, которое предоставляет отпечаток сертификата клиента, используемого при использовании потока проверки подлинности сертификата клиента приложения. |
| Псевдоним идентификатора клиента приложения: AppClientId |
ApplicationClientId | Строковое значение, которое предоставляет идентификатор клиента приложения для проверки подлинности. |
| Псевдоним ключа приложения: AppKey |
ApplicationKey | Строковое значение, которое предоставляет ключ приложения для использования при проверке подлинности с помощью потока секрета приложения. |
| Имя приложения для псевдонима трассировки : TraceAppName |
ApplicationNameForTracing | Необязательное строковое значение, которое сообщает службе, имя приложения которой следует использовать при внутренней трассировке запроса. |
| Псевдоним маркера приложения: AppToken |
ApplicationToken | Строковое значение, указывающее клиенту выполнять проверку подлинности приложения с помощью указанного маркера носителя. |
| Псевдоним идентификатора центра: TenantId |
Центр | Строковое значение, которое предоставляет имя или идентификатор клиента, в котором зарегистрировано приложение. Значение по умолчанию — microsoft.com. Дополнительные сведения см. в центре Microsoft Entra. |
| Псевдонимы региона Azure: AzureRegion, Регион |
AzureRegion | Строковое значение, указывающее имя региона Azure, в котором выполняется проверка подлинности. |
| Управляемое удостоверение службы | EmbeddedManagedIdentity | Строковое значение, указывающее клиенту, какой идентификатор приложения будет использоваться с проверкой подлинности управляемого удостоверения. Используется system для указания назначаемого системой удостоверения.
Это свойство нельзя задать с помощью строка подключения только программным способом. |
| Псевдоним различающегося имени субъекта сертификата приложения: субъект сертификата приложения |
ApplicationCertificateSubjectDistinguishedName | Строковое значение, указывающее различающееся имя субъекта сертификата приложения. |
| Псевдоним различающегося имени издателя сертификата приложения: издатель сертификата приложения |
ApplicationCertificateIssuerDistinguishedName | Строковое значение, указывающее различающееся имя издателя сертификата приложения. |
Поддерживаемые сочетания свойств для проверки подлинности приложения
Для проверки подлинности приложения укажите AAD Federated Security как true. Затем выберите один из следующих режимов проверки подлинности и укажите соответствующие свойства для этого режима.
| Режим проверки подлинности | Имена свойств |
|---|---|
| Проверка подлинности ключа приложения Microsoft Entra | — Идентификатор клиента приложения— ключ приложения— идентификатор центра — имя приложения для трассировки (необязательно) |
| Проверка подлинности приложения Microsoft Entra | — Идентификатор клиента приложения— отпечаток сертификата приложения— идентификатор центра — имя приложения для трассировки (необязательно) |
| Проверка подлинности субъекта приложения Microsoft Entra и издателя | — Идентификатор клиента приложения— разделяемое имя субъекта сертификата приложения— различающееся имя издателя сертификата приложения— идентификатор центра — регион Azure (необязательно) - Сертификат приложения SendX5c (необязательно) — имя приложения для трассировки (необязательно) |
| Проверка подлинности субъекта приложения Microsoft Entra | — Идентификатор клиента приложения— субъект сертификата приложения, различающееся имя — идентификатор центра и регион Azure (необязательно) — имя приложения для трассировки (необязательно) |
| Проверка подлинности маркера приложения Microsoft Entra | — Токен приложения — имя приложения для трассировки (необязательно) |
Проверка подлинности с помощью сертификата приложения
- Приложение должно быть настроено для принятия данного сертификата. Как выполнить проверку подлинности на основе сертификата приложения Microsoft Entra.
- Приложение должно быть настроено в качестве авторизованного субъекта в соответствующей среде Kusto.
- Сертификат необходимо установить в локальном хранилище компьютеров или в текущем хранилище пользователей.
- Открытый ключ сертификата должен содержать не менее 2048 бит.
Свойства взаимодействия с клиентом
| Имя свойства | Имя в программном коде | Description |
|---|---|---|
| Accept | Accept | Логическое значение, которое запрашивает возврат подробных объектов ошибок при сбое. |
| Потоковая передача | Потоковая передача | Логическое значение, запрашивающее, что клиент немедленно предоставляет данные вызывающему объекту, не накапливая его сначала. Потоковая передача — это поведение по умолчанию. |
| Без сжатия | Без сжатия | Логическое значение, указывающее клиенту, чтобы избежать запроса сжатия на уровне транспорта. |
Примечание.
Streaming Если флаг включен (по умолчанию), пакет SDK не буферизирует все данные ответа в памяти. Вместо этого он "извлекает" данные из службы, когда вызывающий запрос запрашивает его. В этом случае вызывающий объект должен правильно удалить данные, такие как IDataReader, после завершения чтения данных, так как сетевое подключение к службе проводится ненужно.
Примеры
В следующих примерах показано, как настроить подключения с помощью C#. Примеры на других языках см. в методах проверки подлинности приложений.
Федеративная проверка подлинности идентификатора Microsoft Entra с текущим удостоверением пользователя
В следующем примере показано, как настроить подключение к службе Kusto с помощью идентификатора 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 ID с указанием идентификатора пользователя
В следующем примере показано, как настроить подключение к службе Kusto с помощью идентификатора Microsoft Entra для федеративной проверки подлинности и предварительно заполнить удостоверение пользователя с помощью переменной userID . При необходимости пользователь запрашивает учетные данные.
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
В следующем примере показано, как пройти проверку подлинности в службе Kusto с помощью идентификатора 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}"
Проверка подлинности с помощью управляемого удостоверения, назначаемого системой
В следующем примере показано, как пройти проверку подлинности в службе Kusto с помощью назначаемого системой управляемого удостоверения для проверки подлинности.
var kustoUri = "https://<clusterName>.<region>.kusto.windows.net";
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
.WithAadSystemManagedIdentity();
Проверка подлинности с помощью управляемого удостоверения, назначаемого пользователем
В следующем примере показано, как пройти проверку подлинности в службе Kusto с помощью назначаемого пользователем управляемого удостоверения для проверки подлинности.
var kustoUri = "https://<clusterName>.<region>.kusto.windows.net";
var managedIdentityClientId = "<managedIdentityClientId>";
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
.WithAadUserManagedIdentity(managedIdentityClientId);
Федеративная проверка подлинности Идентификатора Microsoft Entra с маркерами пользователей и приложений
В следующем примере показано, как настроить подключение к службе Kusto с помощью идентификатора 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}"
Проверка подлинности с помощью обратного вызова поставщика маркеров
В следующем примере показано, как выполнить проверку подлинности в службе Kusto с помощью идентификатора Microsoft Entra с обратным вызовом поставщика пользовательских маркеров. Маркер вызывается каждый раз, когда требуется маркер.
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
В следующем примере показано, как пройти проверку подлинности в службе Kusto с помощью идентификатора Microsoft Entra для федеративной проверки подлинности с помощью сертификата приложения.
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
В следующем примере показано, как настроить подключение к службе Kusto с помощью идентификатора Microsoft Entra с отпечатком сертификата приложения. Клиент пытается загрузить сертификат из локального хранилища.
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}"
Федеративная проверка подлинности идентификатора Microsoft Entra с текущим удостоверением пользователя
В следующем примере показано, как настроить подключение к службе Kusto с помощью идентификатора Microsoft Entra для федеративной проверки подлинности. При необходимости пользователь запрашивает учетные данные.
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}"
Федеративная проверка подлинности Microsoft Entra ID с указанием идентификатора пользователя
В следующем примере показано, как настроить подключение к службе Kusto с помощью идентификатора Microsoft Entra для федеративной проверки подлинности и предварительно заполнить удостоверение пользователя с помощью переменной 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
В следующем примере показано, как пройти проверку подлинности в службе Kusto с помощью идентификатора Microsoft Entra для федеративной проверки подлинности с идентификатором клиента приложения и ключом.
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 с маркерами пользователей и приложений
В следующем примере показано, как настроить подключение к службе Kusto с помощью идентификатора Microsoft Entra с маркером доступа пользователя или маркером доступа к приложению.
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}"
Проверка подлинности с помощью обратного вызова поставщика маркеров
В следующем примере показано, как выполнить проверку подлинности в службе Kusto с помощью идентификатора Microsoft Entra с обратным вызовом поставщика пользовательских маркеров. Маркер вызывается каждый раз, когда требуется маркер.
var kustoUri = "serviceURI";
Func<string> tokenProviderCallback; // User-defined method to retrieve the access token
var kustoConnectionStringBuilder = new KustoConnectionStringBuilder(kustoUri)
.WithAadTokenProviderAuthentication(tokenProviderCallback);
Проверка подлинности с помощью сертификата X.509
В следующем примере показано, как пройти проверку подлинности в службе Kusto с помощью идентификатора Microsoft Entra для федеративной проверки подлинности с помощью сертификата приложения.
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
В следующем примере показано, как настроить подключение к службе Kusto с помощью идентификатора Microsoft Entra с отпечатком сертификата приложения. Клиент пытается загрузить сертификат из локального хранилища.
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}"