教程:发送 Slack 消息

在本教程中,你将为 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中使用操作符

  1. 在可视化数据准备中,打开左侧面板的 运算符 菜单,找到 发送 Slack 消息 运算符。
  2. 把操作符拖到画布上,然后将一个输入连接到它。
  3. 双击操作符打开配置面板,然后设置其字段。
  4. 选择操作符,在输出面板中预览其结果。

操作员有:

  • 用于连接数据源的输入端口。
  • 用于选择包含消息内容的列的表达式选取器。
  • Slack 频道的文本输入框。

用户可以根据其数据发送通知。 例如,当超出特定阈值时发出警报。

技巧与最佳实践

在构建调用外部API的操作符时,请参考以下示例和指南。

常见用例

  • 警报:检测到数据质量问题时发送通知。
  • 通知:工作流完成后通知团队。
  • Webhook:调用外部 API 以触发下游进程。
  • 日志记录:将审核消息发送到外部系统。

生成 API 调用运算符的最佳做法

  1. 始终使用预览模式:添加 is_preview 配置属性 format: is_preview 以防止意外的 API 调用。
  2. 使用 Unity Catalog 连接:切勿将凭据硬编码到 UDF 中。 将它们存储在 Unity Catalog 的 HTTP 连接中,并使用 http_request() 调用它。
  3. 正常处理错误:API 调用可能会失败;考虑在错误时返回的内容。
  4. 全面测试:在开发期间使用预览模式。
  5. 记录连接设置:用户需要知道要创建哪些连接。

其他资源