在本教程中,你将为 Lakeflow Designer 创建一个 SQL UDF 运算符,用于将消息发布到 Slack 通道。 如需更全面的概述,请参见 Lakeflow Designer 中的自定义运算符。
Overview
此运算符使用以下方法将消息发送到 Slack:
- SQL UDF:用 SQL 而不是Python编写。
- Unity 目录 HTTP 连接:安全地管理 Slack API 凭据。
- 预览模式支持:在工作流预览期间防止实际的 Slack API 调用。
- 表达式参数:允许来自 DataFrame 列的动态消息内容。
为何使用 SQL UDF
SQL UDF可以通过该 http_request() 函数调用外部API(如Slack、REST端点和webhooks),该函数通过 Unity Catalog HTTP 连接进行身份验证。 连接存储凭证,所以它们不会嵌入函数代码中。 要改为用 Python 调用 API,可以使用 python-run-function 操作符。 参见教程:Gmail 电子邮件发送器运算符。
Requirements
- 在支持Unity Catalog的工作区中访问Lakeflow Designer。 请参阅 先决条件。
- 在
main目录上执行USE CATALOG,在main上执行CREATE SCHEMA,或者在现有main.example_output架构上执行USE SCHEMA和CREATE FUNCTION。 如果要使用不同的目录或模式,就将所有位置的main.example_output替换掉。 请参阅 Unity Catalog 权限参考。 - 在 Unity Catalog 元存储上执行
CREATE CONNECTION,以创建 HTTP 连接。 请参阅 “连接到外部 HTTP 服务”。 - 一个带有机器人令牌的Slack应用,可以向你的频道发送消息。
步骤 1:设置 Unity 目录 HTTP 连接
在创建 UDF 之前,需要设置 Unity 目录 HTTP 连接,以安全地存储 Slack API 凭据。 用您实际的 Slack 机器人令牌替换 <xoxb-your-slack-bot-token>。 可以从 Slack 应用设置中获取此信息。 可以在多个 UDF 之间使用此相同的连接。 若要了解详细信息,请参阅 “连接到外部 HTTP 服务”。
CREATE CONNECTION my_slack_connection TYPE HTTP OPTIONS (
host 'https://slack.com',
port '443',
base_path '/api/',
bearer_token '<xoxb-your-slack-bot-token>'
);
步骤 2:创建操作员 YAML
现在,为操作员创建 YAML。 有关架构的详细信息,请参阅自定义操作符 YAML 参考。
此运算符的 YAML 包括:
-
表达式参数 (
msg): 允许来自数据帧列的动态消息内容。 -
字符串参数 (
channel): 静态通道名称/ID。 -
预览模式 (
is_preview):一个配置属性,该属性format: is_preview允许预览模式在测试期间防止实际的 API 调用。
schema: custom-operator-v0.2.0
type: uc-udf
name: Send Slack Message
id: send_msg
version: '1.0.0'
description: Send Slack Message to a Channel
config:
type: object
properties:
msg:
type: string
format: expression
title: Message
examples:
- 'Select message column or expression'
x-ui:
widget: expression
port: input_data
channel:
type: string
title: Channel
x-ui:
widget: input
is_preview:
type: boolean
format: is_preview
default: false
required:
- msg
- channel
additionalProperties: false
ports:
input:
- name: input_data
title: Input Data
output:
- name: output
title: Send Response Data
这包括:
| 配置键 | Widget | Purpose |
|---|---|---|
msg |
expression |
来自输入数据的动态消息内容。 |
channel |
input |
要发送到的 Slack 频道(例如:#alerts)。 |
is_preview |
n/a | 一个带有 format: is_preview 的布尔配置属性,它允许算子在预览期间以不同方式运行(在这种情况下,避免实际创建 Slack 消息)。 |
步骤 3:创建 Unity 目录函数
创建 SQL UDF 时,与大多数 SQL 查询相比,有些事情并不常见:
- 请使用
RETURN语法,而不要使用AS $$。 - 在 SQL 注释块(
/* ... */)中嵌入 YAML 配置。 - 可以将函数
http_request用于 API 调用。
该示例在 main.example_output 中创建该函数。 如果没有模式,先创建它:
CREATE SCHEMA IF NOT EXISTS main.example_output
CREATE OR REPLACE FUNCTION main.example_output.send_slack_msg(
msg STRING,
channel STRING,
is_preview BOOLEAN
)
RETURNS STRING
RETURN (/*
schema: custom-operator-v0.2.0
type: uc-udf
name: Send Slack Message
id: send_msg
version: "1.0.0"
description: Send Slack Message to a Channel
config:
type: object
properties:
msg:
type: string
format: expression
title: Message
examples:
- "Select message column or expression"
x-ui:
widget: expression
port: input_data
channel:
type: string
title: Channel
x-ui:
widget: input
is_preview:
type: boolean
format: is_preview
default: false
required:
- msg
- channel
additionalProperties: false
ports:
input:
- name: input_data
title: Input Data
output:
- name: output
title: Send Response Data
*/
CASE
WHEN NOT is_preview THEN
http_request(
conn => 'my_slack_connection',
method => 'POST',
path => 'chat.postMessage',
json => to_json(named_struct('channel', channel, 'text', msg)),
headers => map('Content-Type', 'application/json;charset=utf-8')
).text
ELSE 'Preview mode - no message sent to ' || channel
END
);
此 SQL 函数包含以下功能:
| 功能 | Purpose |
|---|---|
http_request() |
对外部 API 进行 HTTP 调用。 |
conn => 'my_slack_connection' |
引用用于身份验证的 UC 连接。 |
to_json() 和 named_struct() |
构造 Slack API 的 JSON 有效负载。 |
| YAML 注释块 | 由 Lakeflow Designer 用于创建操作符。 |
CASE WHEN |
实现预览模式逻辑。 |
步骤 4:测试函数
接下来,测试函数,以确保它在将它注册为运算符之前正常工作。
先在预览模式下测试,这样就不会发送任何消息。 它将返回 Preview mode - no message sent to #test-channel。
SELECT main.example_output.send_slack_msg(
msg => 'Hello from Lakeflow Designer!',
channel => '#test-channel',
is_preview => true
) AS result;
用真实的API调用测试发送消息给Slack。 请谨慎使用:它会向频道发送消息,并返回 Slack API 的 JSON 响应。
SELECT main.example_output.send_slack_msg(
msg => 'Hello from Lakeflow Designer!',
channel => '#test-channel',
is_preview => false
) AS result;
步骤 5:注册运算符
将运算符添加到 .custom_operators.yaml 文件:
operators:
- catalog: main
schema: example_output
functionName: send_slack_msg
注释
如果在用户文件夹中定义此文件,则只会为你显示该文件。 有关详细信息,请参见将运算符注册并部署到 Lakeflow Designer。
步骤 6:设置权限
对于使用 Unity 目录连接的 SQL UDF,用户需要其他权限:
GRANT USE SCHEMA ON SCHEMA main.example_output TO `<user>`;
GRANT EXECUTE ON FUNCTION main.example_output.send_slack_msg TO `<user>`;
GRANT USE CONNECTION ON CONNECTION my_slack_connection TO `<user>`;
Important
USE CONNECTION如果没有权限,即使用户可以执行该函数,用户也无法进行 API 调用。
步骤7:在Lakeflow Designer中使用操作符
- 在可视化数据准备中,打开左侧面板的 运算符 菜单,找到 发送 Slack 消息 运算符。
- 把操作符拖到画布上,然后将一个输入连接到它。
- 双击操作符打开配置面板,然后设置其字段。
- 选择操作符,在输出面板中预览其结果。
操作员有:
- 用于连接数据源的输入端口。
- 用于选择包含消息内容的列的表达式选取器。
- Slack 频道的文本输入框。
用户可以根据其数据发送通知。 例如,当超出特定阈值时发出警报。
技巧与最佳实践
在构建调用外部API的操作符时,请参考以下示例和指南。
常见用例
- 警报:检测到数据质量问题时发送通知。
- 通知:工作流完成后通知团队。
- Webhook:调用外部 API 以触发下游进程。
- 日志记录:将审核消息发送到外部系统。
生成 API 调用运算符的最佳做法
-
始终使用预览模式:添加
is_preview配置属性format: is_preview以防止意外的 API 调用。 -
使用 Unity Catalog 连接:切勿将凭据硬编码到 UDF 中。 将它们存储在 Unity Catalog 的 HTTP 连接中,并使用
http_request()调用它。 - 正常处理错误:API 调用可能会失败;考虑在错误时返回的内容。
- 全面测试:在开发期间使用预览模式。
- 记录连接设置:用户需要知道要创建哪些连接。