Строки подключения 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/Samples в https://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.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 | При трассировке версии клиента используйте это свойство. |
| Псевдонимы источников данных: Addr, Address, Network Address, Server |
DataSource | Код URI для указания конечной точки службы Data Explorer. Например, https://mycluster.kusto.windows.net. |
| Начальный псевдоним каталога : база данных |
InitialCatalog | Имя базы данных, используемой по умолчанию, Например, MyDatabase. |
| Псевдоним согласованности запросов: QueryConsistency |
QueryConsistency | Задайте значение strongconsistency или weakconsistency , чтобы определить, должен ли запрос синхронизироваться с метаданными перед выполнением. |
Свойства проверки подлинности пользователя
| Имя свойства | Имя в программном коде | Описание |
|---|---|---|
| Федеративная безопасность Microsoft Entra IDПсевдонимы: Federated Security, Federated, Fed, AADFed |
FederatedSecurity | Логическое значение, указывающее клиенту выполнить проверку подлинности Microsoft Entra. |
| Псевдоним идентификатора центра: TenantId |
Authority | Строковое значение, указывающее имя или идентификатор клиента пользователя. Значение по умолчанию — microsoft.com. Дополнительные сведения см. в разделе центр Microsoft Entra. |
| Применение псевдонима MFA : MFA, EnforceMFA |
EnforceMfa | Необязательное логическое значение, указывающее клиенту на получение маркера многофакторной проверки подлинности. |
| Псевдонимы идентификаторов пользователей: UID, User |
UserID | Строковое значение, указывающее клиенту выполнить проверку подлинности пользователя с указанным именем пользователя. |
| Имя пользователя для трассировки | TraceUserName | Необязательное строковое значение, которое сообщает службе, какое имя пользователя следует использовать при внутренней трассировке запроса. |
| Псевдонимы маркера пользователя: UsrToken, UserToken |
UserToken | Строковое значение, указывающее клиенту выполнить проверку подлинности пользователя с помощью указанного токена носителя. Переопределяет ApplicationClientId, ApplicationKeyи ApplicationToken. Если этот параметр указан, пропускает фактический поток проверки подлинности клиента в пользу предоставленного маркера. |
Поддерживаемые сочетания свойств для проверки подлинности пользователей
Для проверки подлинности пользователя укажите AAD Federated Security как true. Затем выберите один из следующих режимов проверки подлинности и укажите соответствующие свойства для этого режима.
| Режим проверки подлинности | Имена свойств |
|---|---|
| Microsoft Entra запрос проверки подлинности пользователя | - Идентификатор пользователя (необязательно) - Идентификатор центра (необязательно) - Принудительное применение MFA (необязательно) - Имя пользователя для трассировки (необязательно) |
| Microsoft Entra проверка подлинности на основе маркера пользователя | — Маркер пользователя — принудительное применение MFA (необязательно) — имя пользователя для трассировки (необязательно) |
Свойства проверки подлинности приложения
| Имя свойства | Имя в программном коде | Описание |
|---|---|---|
| Федеративная безопасность Microsoft Entra IDПсевдонимы: Federated Security, Federated, Fed, AADFed |
FederatedSecurity | Логическое значение, указывающее клиенту выполнять федеративную проверку подлинности с Microsoft Entra идентификатором. |
| Псевдонимы SendX5c сертификата приложения: отправка открытого сертификата приложения, SendX5c |
ApplicationCertificateSendX5c | Логическое значение, указывающее клиенту выполнять проверку подлинности на основе имени субъекта и издателя. |
| Псевдоним отпечатка сертификата приложения: AppCert |
ApplicationCertificateThumbprint | Строковое значение, которое предоставляет отпечаток сертификата клиента для использования при использовании потока проверки подлинности сертификата клиента приложения. |
| Псевдоним идентификатора клиента приложения: AppClientId |
ApplicationClientId | Строковое значение, которое предоставляет идентификатор клиента приложения для использования при проверке подлинности. |
| Псевдоним ключа приложения: AppKey |
ApplicationKey | Строковое значение, предоставляющее ключ приложения для использования при проверке подлинности с помощью потока секрета приложения. |
| Имя приложения для псевдонима трассировки : TraceAppName |
ApplicationNameForTracing | Необязательное строковое значение, которое сообщает службе, какое имя приложения следует использовать при внутренней трассировке запроса. |
| Псевдоним маркера приложения: AppToken |
ApplicationToken | Строковое значение, указывающее клиенту выполнить проверку подлинности приложения с помощью указанного токена носителя. |
| Псевдоним идентификатора центра: TenantId |
Authority | Строковое значение, указывающее имя или идентификатор клиента, в котором зарегистрировано приложение. Значение по умолчанию — microsoft.com. Дополнительные сведения см. в разделе центр Microsoft Entra. |
| Псевдонимы регионов Azure: AzureRegion, Region |
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 бит.
Свойства взаимодействия с клиентом
| Имя свойства | Имя в программном коде | Описание |
|---|---|---|
| Принятие | Accept | Логическое значение, которое запрашивает возврат подробных объектов ошибок при сбое. |
| Потоковая передача | Streaming | Логическое значение, которое запрашивает, чтобы клиент не накапливал данные перед их предоставлением вызывающему объекту. Это поведение по умолчанию. |
| Без сжатия | Без сжатия | Логическое значение, которое запрашивает у клиента сжатие на уровне транспорта. |
Примечание
Streaming Если флаг включен (как по умолчанию), пакет SDK не буферизует все данные ответа в памяти. Вместо этого он "извлекает" данные из службы, когда вызывающий запрашивает их. Поэтому очень важно, чтобы в этом случае вызывающий объект надлежащим образом утилизировал данные (например IDataReader, ) после завершения чтения данных, так как сетевое подключение к службе не требуется.
Примеры
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 идентификатор федеративной проверки подлинности с указанием идентификатора пользователя (при необходимости пользователю будет предложено)
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}"
Microsoft Entra идентификатор федеративной проверки подлинности приложения с помощью ApplicationClientId и ApplicationKey
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 идентификатор федеративной проверки подлинности с помощью маркера пользователя или приложения
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}"
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по