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

Переключайте службы с помощью раскрывающегося списка Версия. Дополнительные сведения о навигации.
Область применения: ✅ Microsoft Fabric ✅ Azure Data Explorer

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

Синтаксис

evaluate sql_request ( ConnectionString SqlQuery,

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

Параметры

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

Примечание.

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

Примеры

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

В следующем примере sql-запрос отправляется в базу данных БАЗЫ данных SQL Azure. Он извлекает все записи из [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-запрос отправляется в базу данных SQL Azure, из нее извлекаются все записи [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-запрос отправляется в базу данных SQL Azure без выходной схемы. Это не рекомендуется, если схема не неизвестна, так как это может повлиять на производительность запроса.

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 программным способом.