Подключаемый модуль sql_request

Подключаемый sql_request модуль отправляет SQL-запрос в конечную точку сети SQL Server и возвращает результаты. Если SQL возвращает несколько наборов строк, используется только первый. Подключаемый модуль вызывается с evaluate помощью оператора .

Синтаксис

evaluatesql_request(Connectionstring,SqlQuery [,SqlParameters [,Options]] ) [:OutputSchema]

Дополнительные сведения о соглашениях о синтаксисе.

Параметры

Имя	Тип	Обязательно	Описание
Connectionstring	string	✔️	Строка подключения, указывающий на конечную точку сети SQL Server. См. сведения о допустимых методах проверки подлинности и о том, как указать конечную точку сети.
SqlQuery	string	✔️	Запрос, выполняемый к конечной точке SQL. Запрос должен возвращать один или несколько наборов строк, но только первый из них будет доступен для остальной части запроса Kusto.
SqlParameters	dynamic		Контейнер свойств пар "ключ-значение", передаваемых в качестве параметров вместе с запросом.
Параметры	dynamic		Контейнер свойств пар "ключ-значение" для передачи более сложных параметров вместе с запросом. В настоящее время можно задать только token для передачи предоставленного вызывающим Microsoft Entra маркера доступа, который перенаправлен в конечную точку SQL для проверки подлинности.
OutputSchema	string		Имена и типы ожидаемых столбцов выходных данных подключаемого sql_request модуля. Используйте следующий синтаксис: (ColumnName:ColumnType [, ...] ).

Примечание

• Настоятельно рекомендуется указать OutputSchema , так как это позволяет использовать подключаемый модуль в сценариях, которые в противном случае могут не работать без него, например в межкластичном запросе. OutputSchema также может включить несколько оптимизаций запросов.
• Если схема времени выполнения первого набора строк, возвращенного сетевой конечной точкой SQL, не соответствует схеме OutputSchema .

Аутентификация и авторизация

Подключаемый модуль sql_request поддерживает следующие три метода проверки подлинности в конечной точке SQL Server.

Метод проверки подлинности	Синтаксис	Как	Описание
интеграция Microsoft Entra	Authentication="Active Directory Integrated"	Добавьте в параметр ConnectionString .	Предпочтителен этот метод проверки подлинности. Пользователь или приложение проходит проверку подлинности через Microsoft Entra ID в кластер, и тот же маркер используется для доступа к SQL Server конечной точке сети. Субъект должен иметь соответствующие разрешения на ресурс SQL для выполнения запрошенного действия. Например, для чтения из базы данных субъекту требуются разрешения SELECT таблицы, а для записи в существующую таблицу субъекту требуются разрешения UPDATE и INSERT. Для записи в новую таблицу также требуются разрешения CREATE.
Имя пользователя и пароль	User ID=...; Password=...;	Добавьте в параметр ConnectionString .	По возможности избегайте этого метода, так как он может быть менее безопасным.
маркер доступа Microsoft Entra	dynamic({'token': h"eyJ0..."})	Добавьте в параметр Options .	Маркер доступа передается как token свойство в аргументе Options подключаемого модуля.

Примечание

Строки подключения и запросы, включающие конфиденциальную информацию или сведения, которые должны быть защищены, должны быть замаскированы, чтобы исключить их из любой трассировки Kusto. Дополнительные сведения см. в статье Скрытые строковые литералы.

Примеры

Отправка SQL-запроса с помощью встроенной проверки подлинности Microsoft Entra

В следующем примере sql-запрос отправляется в базу данных Azure SQL DB. Он извлекает все записи из [dbo].[Table], а затем обрабатывает результаты на стороне Kusto. При проверке подлинности повторно используется маркер Microsoft Entra вызывающего пользователя.

Примечание

Этот пример не следует рассматривать как рекомендацию для фильтрации или проецировать данные таким образом. Sql-запросы должны быть созданы для возврата наименьшего возможного набора данных.

evaluate sql_request(
  'Server=tcp:contoso.database.windows.net,1433;'
    'Authentication="Active Directory Integrated";'
    'Initial Catalog=Fabrikam;',
  'select * from [dbo].[Table]') : (Id:long, Name:string)
| where Id > 0
| project Name

Отправка SQL-запроса с использованием проверки подлинности имени пользователя и пароля

Следующий пример идентичен предыдущему, за исключением того, что проверка подлинности SQL выполняется с помощью имени пользователя или пароля. Для конфиденциальности здесь используются скрытые строки.

evaluate sql_request(
  'Server=tcp:contoso.database.windows.net,1433;'
    'Initial Catalog=Fabrikam;'
    h'User ID=USERNAME;'
    h'Password=PASSWORD;',
  'select * from [dbo].[Table]') : (Id:long, Name:string)
| where Id > 0
| project Name

Отправка SQL-запроса с помощью маркера доступа Microsoft Entra

В следующем примере SQL-запрос отправляется в базу данных Azure SQL, извлекающую все записи из [dbo].[Table], добавляя другой datetime столбец, а затем обрабатывает результаты на стороне Kusto. Он задает параметр SQL (@param0), который будет использоваться в SQL-запросе.

evaluate sql_request(
  'Server=tcp:contoso.database.windows.net,1433;'
    'Authentication="Active Directory Integrated";'
    'Initial Catalog=Fabrikam;',
  'select *, @param0 as dt from [dbo].[Table]',
  dynamic({'param0': datetime(2020-01-01 16:47:26.7423305)})) : (Id:long, Name:string, dt: datetime)
| where Id > 0
| project Name

Отправка SQL-запроса без определяемой запросом выходной схемы

В следующем примере sql-запрос отправляется в базу данных Azure SQL без выходной схемы. Это не рекомендуется, если схема неизвестна, так как это может повлиять на производительность запроса.

evaluate sql_request(
  'Server=tcp:contoso.database.windows.net,1433;'
    'Initial Catalog=Fabrikam;'
    h'User ID=USERNAME;'
    h'Password=PASSWORD;',
  'select * from [dbo].[Table]')
| where Id > 0
| project Name

Шифрование и проверка сервера

Следующие свойства подключения принудительно применяются при подключении к SQL Server конечной точке сети по соображениям безопасности.

• Encrypt параметру задано значение true безусловно.
• TrustServerCertificate параметру задано значение false безусловно.

В результате SQL Server необходимо настроить с использованием допустимого сертификата сервера SSL/TLS.

Укажите конечную точку сети

Указание сетевой конечной точки SQL в составе строка подключения является обязательным. Правильный синтаксис:

Server=tcp:Полное доменное имя [,порт]

Где:

• Полное доменное имя — это полное доменное имя конечной точки.
• Порт — это TCP-порт конечной точки. По умолчанию предполагается значение 1433.

Примечание

Другие формы указания конечной точки сети не поддерживаются. Нельзя опустить, например, префикс tcp: , хотя это возможно при использовании клиентских библиотек SQL программным способом.

Эта возможность не поддерживается в Azure Monitor