sql_request 插件
适用于:✅Azure 数据资源管理器
sql_request
插件将 SQL 查询发送到 Azure SQL Server 网络终结点并返回结果。
如果 SQL 返回多个行集,将仅使用第一个行集。
该插件通过 evaluate
运算符调用。
语法
evaluate
sql_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 权限。 |
托管的标识 | Authentication="Active Directory Managed Identity";User Id={object_id} |
添加到 ConnectionString 参数。 | 将代表托管标识执行请求。 托管标识必须具有 SQL 资源的适当权限,才能执行请求的操作。 若要启用托管标识身份验证,必须将托管标识添加到群集并更改托管标识策略。 有关详细信息,请参阅托管标识策略。 |
用户名和密码 | User ID=...; Password=...; |
添加到 ConnectionString 参数。 | 请尽可能避免使用此方法,因为它可能不太安全。 |
Microsoft Entra 访问令牌 | dynamic({'token': h"eyJ0..."}) |
在 Options 参数中添加。 | 访问令牌在插件的 Options 参数中作为 token 属性传递。 |
注意
应该对包含机密信息(或应当受保护的信息)的连接字符串和查询进行模糊处理,以在任何 Kusto 跟踪中忽略它们。 有关详细信息,请参阅经过模糊处理的字符串文本。
示例
使用 Microsoft Entra 集成身份验证发送 SQL 查询
下面的示例向 Azure SQL DB 数据库发送 SQL 查询。 它从 [dbo].[Table]
检索所有记录,然后在 Kusto 端处理结果。 身份验证会重复使用调用方用户的 Microsoft Entra 令牌。
注意
建议不要像此示例这样以此方式筛选或投影数据。 应当将 SQL 查询构造为返回尽可能小的数据集。
evaluate sql_request(
'Server=tcp:contoso.database.chinacloudapi.cn,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.chinacloudapi.cn,1433;'
'Initial Catalog=Fabrikam;'
h'User ID=USERNAME;'
h'Password=PASSWORD;',
'select * from [dbo].[Table]') : (Id:long, Name:string)
| where Id > 0
| project Name
使用 Microsoft Entra 访问令牌发送 SQL 查询
下面的示例向 Azure SQL 数据库发送一个 SQL 查询,从 [dbo].[Table]
检索所有记录,同时追加另一个 datetime
列,然后在 Kusto 端处理结果。
它指定要在 SQL 查询中使用的 SQL 参数 (@param0
)。
evaluate sql_request(
'Server=tcp:contoso.database.chinacloudapi.cn,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.chinacloudapi.cn,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:
FQDN [,
Port]
其中:
- FQDN 是终结点的完全限定域名。
- Port 是终结点的 TCP 端口。 默认为
1433
。
注意
不支持以其他形式指定网络终结点。
例如,不能省略前缀 tcp:
,即使在以编程方式使用 SQL 客户端库时可以省略它。