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

  • Статья

Область применения: ✅Microsoft Fabric✅Azure Data Explorer

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

Синтаксис

evaluatesql_request ( ConnectionString SqlQuery [, SqlParameters [, Параметры]] ) [: OutputSchema] ,

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

Параметры

Имя (название) 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.

Authentication method Синтаксис Как Description
Интегрированная microsoft Entra Authentication="Active Directory Integrated" Добавьте в параметр ConnectionString . Пользователь или приложение проходит проверку подлинности с помощью идентификатора Microsoft Entra в кластере, а тот же маркер используется для доступа к конечной точке сети SQL Server.
Субъект должен иметь соответствующие разрешения на ресурс SQL для выполнения запрошенного действия. Например, для чтения из базы данных субъекту требуются разрешения SELECT таблицы, а для записи в существующую таблицу субъекту требуются разрешения UPDATE и INSERT. Для записи в новую таблицу также требуются разрешения CREATE.
Управляемое удостоверение Authentication="Active Directory Managed Identity";User Id={object_id} Добавьте в параметр ConnectionString . Запрос выполняется от имени управляемого удостоверения. Управляемое удостоверение должно иметь соответствующие разрешения для ресурса SQL для выполнения запрошенного действия.
Чтобы включить проверку подлинности управляемого удостоверения, необходимо добавить управляемое удостоверение в кластер и изменить политику управляемого удостоверения. Дополнительные сведения см. в разделе "Политика управляемого удостоверения".
Имя пользователя и пароль 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 программным способом.