教程：发送 Slack 消息

在本教程中，你将为 Lakeflow Designer 创建一个 SQL UDF 运算符，用于将消息发布到 Slack 通道。 当函数需要通过 HTTP 调用外部 API 时，SQL UDF 是正确的选择。 有关更广泛的概述，请参阅 Lakeflow Designer 中的用户定义的运算符。

Overview

此运算符使用以下方法将消息发送到 Slack：

  • SQL UDF：用 SQL 而不是Python编写。
  • Unity 目录 HTTP 连接：安全地管理 Slack API 凭据。
  • 预览模式支持：在工作流预览期间防止实际的 Slack API 调用。
  • 表达式参数：允许来自 DataFrame 列的动态消息内容。

为何使用 SQL UDF

对于需要调用外部 API（如 Slack、REST 终结点、Webhook）的运算符，必须使用 SQL UDF。 Python UDF 和 UDDF 无法发出 HTTP 请求。 SQL UDF 可访问适用于 Unity Catalog 连接的 http_request() 函数。

步骤 1：设置 Unity 目录 HTTP 连接

在创建 UDF 之前，需要设置 Unity 目录 HTTP 连接，以安全地存储 Slack API 凭据。 用您实际的 Slack 机器人令牌替换 <xoxb-your-slack-bot-token>。 可以从 Slack 应用设置中获取此信息。 可以在多个 UDF 之间使用此相同的连接。 若要了解详细信息，请参阅 “连接到外部 HTTP 服务”。

-- Create a connection to store Slack credentials securely
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: user-defined-operator-v0.1.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
    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 调用。
CREATE OR REPLACE FUNCTION main.my_schema.send_slack_msg(
    msg STRING,
    channel STRING,
    is_preview BOOLEAN
)
RETURNS STRING
RETURN (/*
    schema: user-defined-operator-v0.1.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
        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：测试函数

接下来，测试函数，以确保它在将它注册为运算符之前正常工作。

首先在预览模式下进行测试，以避免发送 Slack 消息：

-- Test in preview mode (won't send real message)
SELECT main.my_schema.send_slack_msg(
  'Hello from Lakeflow Designer!',
  '#test-channel',
  true  -- is_preview = true
) AS result;

-- Expected result: "Preview mode - no message sent to #test-channel"

使用外部 API 调用进行测试（向 Slack 发送消息）：

-- Test with real API call (USE WITH CAUTION!)
SELECT main.my_schema.send_slack_msg(
  'Hello from Lakeflow Designer!',
  '#test-channel',
  false  -- is_preview = false
) AS result;

-- Expected: Slack API response JSON

步骤 5：注册运算符

将运算符添加到 .user_defined_operators.yaml 文件：

operators:
  - catalog: main
    schema: my_schema
    functionName: send_slack_msg

注释

如果在用户文件夹中定义此文件，则只会为你显示该文件。 有关详细信息，请参阅使您的操作符可被发现。

步骤 6：设置权限

对于使用 Unity 目录连接的 SQL UDF，用户需要其他权限：

-- Schema and function access
GRANT USE SCHEMA ON SCHEMA main.my_schema TO `<user>`;
GRANT EXECUTE ON FUNCTION main.my_schema.send_slack_msg TO `<user>`;

-- Connection access (required for API calls)
GRANT USE CONNECTION ON CONNECTION my_slack_connection TO `<user>`;

Important

USE CONNECTION如果没有权限，即使用户可以执行该函数，用户也无法进行 API 调用。

在 Lakeflow Designer 中使用运算符

注册完成后，该运算符会显示在 Lakeflow Designer 中，并包含以下内容：

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

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

常见用例

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

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

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