postgresql_request 插件

项目
10/01/2024

适用于：✅Azure 数据资源管理器

postgresql_request 插件将 SQL 查询发送到 Azure PostgreSQL 服务器网络终结点，并返回结果中的第一个行集。此查询可能返回多个行集，但只有第一个行集可用于 Kusto 查询的其余部分。

该插件通过 evaluate 运算符调用。

重要

postgresql_request 插件默认已禁用。若要启用此插件，请运行 .enable plugin postgresql_request 命令。若要查看启用了哪些插件，请使用 .show plugin 管理命令。

语法

evaluate postgresql_request ( ConnectionString , SqlQuery [, SqlParameters] ) [: OutputSchema]

详细了解语法约定。

参数

客户	类型	必需	描述
ConnectionString	`string`	✔️	指向 PostgreSQL 服务器网络终结点的连接字符串。请了解身份验证以及指定网络终结点的方法。
SqlQuery	`string`	✔️	要对 SQL 终结点执行的查询。必须返回一个或多个行集。只有第一个集可用于查询的其余部分。
SqlParameters	`dynamic`		一个属性包对象，用于保存作为参数随查询一起传递的键值对。
OutputSchema			`postgresql_request` 插件输出的所需列的名称和类型。语法：`(` ColumnName `:` ColumnType [`,` ...] `)`

注意

强烈建议指定 OutputSchema，因为这样可以在方案中使用插件，否则该方案不能正常工作，例如在跨群集查询中。 OutputSchema 还可以启用多种查询优化。
如果 SQL 网络终结点返回的第一个行集的运行时架构与 OutputSchema 架构不匹配，则会引发错误。

身份验证和授权

若要对 PostgreSQL 服务器网络终结点进行授权，必须在连接字符串中指定授权信息。支持的授权方法是借助用户名和密码。

设置标注策略

该插件会对 PostgreSQL 数据库进行标注。请确保群集的标注策略允许对目标 PostgreSqlDbUri 进行 postgresql 类型的调用。

以下示例演示如何为 PostgreSQL 数据库定义标注策略。建议将标注策略限制为特定的终结点（my_endpoint1、my_endpoint2）。

[
  {
    "CalloutType": "postgresql",
    "CalloutUriRegex": "my_endpoint1\\.postgres\\.database\\.chinacloudapi\\.cn",
    "CanCall": true
  },
  {
    "CalloutType": "postgresql",
    "CalloutUriRegex": "my_endpoint2\\.postgres\\.database\\.chinacloudapi\\.cn",
    "CanCall": true
  }
]

以下示例演示了针对 postgresql CalloutType 的 .alter callout policy 命令：

.alter cluster policy callout @'[{"CalloutType": "postgresql", "CalloutUriRegex": "\\.postgresql\\.database\\.chinacloudapi\\.cn", "CanCall": true}]'

用户名和密码身份验证

postgresql_request 插件仅支持向 PostgreSQL 服务器终结点进行用户名和密码身份验证，未与 Microsoft Entra 身份验证集成。

用户名和密码是通过以下参数作为连接字符串的一部分提供的：

User ID=...; Password=...;

警告

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

加密和服务器验证

出于安全考虑，连接到 PostgreSQL 服务器网络终结点时，SslMode 会无条件地设置为 Required。因此，必须为服务器配置有效的 SSL/TLS 服务器证书。

指定网络终结点

将 PostgreSQL 网络终结点指定为连接字符串的一部分。

语法：

Host = FQDN [Port = Port]

其中：

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

示例

向 Azure PostgreSQL 数据库发送 SQL 查询

以下示例向 Azure PostgreSQL 数据库发送 SQL 查询。它从 public."Table" 检索所有记录，然后处理结果。

注意

不应将此示例作为以这种方式筛选或投影数据的建议。应将 SQL 查询构造为返回尽可能小的数据集。

evaluate postgresql_request(
    'Host=contoso.postgres.database.chinacloudapi.cn; Port = 5432;'
    'Database=Fabrikam;'
    h'User Id=USERNAME;'
    h'Password=PASSWORD;',
    'select * from public."Table"') : (Id: int, Name: string)
| where Id > 0
| project Name

经过修改的对 Azure PostgreSQL 数据库执行的 SQL 查询

以下示例会将 SQL 查询发送到 Azure PostgreSQL Database，以从 public."Table" 中检索所有记录，同时追加另一 datetime 列，然后处理结果。它指定要在 SQL 查询中使用的 SQL 参数 (@param0)。

evaluate postgresql_request(
    'Server=contoso.postgres.database.chinacloudapi.cn; Port = 5432;'
    'Database=Fabrikam;'
    h'User Id=USERNAME;'
    h'Password=PASSWORD;',
    'select *, @param0 as dt from public."Table"',
    dynamic({'param0': datetime(2020-01-01 16:47:26.7423305)})) : (Id: int, Name: string, dt: datetime)
| where Id > 0
| project Name

在没有查询定义的输出架构的情况下对 Azure PostgreSQL 数据库进行 SQL 查询

以下示例将 SQL 查询发送到没有输出架构的 Azure PostgreSQL 数据库。除非架构未知，否则不建议这样做，因为这可能会影响查询的性能

evaluate postgresql_request(
    'Host=contoso.postgres.database.chinacloudapi.cn; Port = 5432;'
    'Database=Fabrikam;'
    h'User Id=USERNAME;'
    h'Password=PASSWORD;',
    'select * from public."Table"')
| where Id > 0
| project Name

通过