你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

sql_request 插件

项目
01/10/2024

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 参数中添加。	访问令牌在插件的 Options 参数中作为 `token` 属性传递。

注意

应该对包含机密信息（或应当受保护的信息）的连接字符串和查询进行模糊处理，以在任何 Kusto 跟踪中忽略它们。有关详细信息，请参阅经过模糊处理的字符串文本。

示例

使用Microsoft Entra集成身份验证发送 SQL 查询

下面的示例向 Azure SQL DB 数据库发送 SQL 查询。它从 [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

使用Microsoft Entra访问令牌发送 SQL 查询

下面的示例向 Azure SQL 数据库发送一个 SQL 查询，从 [dbo].[Table] 检索所有记录，同时追加另一个 datetime 列，然后在 Kusto 端处理结果。它指定要在 SQL 查询中使用的 SQL 参数 (@param0)。

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:FQDN [,Port]

其中：

FQDN 是终结点的完全限定域名。
Port 是终结点的 TCP 端口。默认为 1433。

注意

不支持以其他形式指定网络终结点。例如，不能省略前缀 tcp:，即使在以编程方式使用 SQL 客户端库时可以省略它。

Azure Monitor 不支持此功能