教學：發送 Slack 訊息

在這個教學中，你會為 Lakeflow Designer 建立一個 SQL UDF 運算子，將訊息貼到 Slack 頻道。 當函式需要透過 HTTP 呼叫外部 API 時，SQL UDF 是正確的選擇。 欲了解更廣泛的概述，請參閱 Lakeflow Designer 中的使用者定義運算子。

Overview

此操作員透過以下方式向 Slack 發送訊息：

  • SQL UDF：以 SQL 撰寫，而非 Python。
  • Unity Catalog HTTP 連線：安全管理 Slack API 憑證。
  • 預覽模式支援：在工作流程預覽期間防止實際呼叫 Slack API。
  • 表達式參數：允許從 DataFrame 欄位動態擷取訊息內容。

為什麼要使用 SQL UDF

對於需要呼叫外部 API（例如 Slack、REST 端點、webhooks）的操作員，你必須使用 SQL UDF。 Python UDFs 和 UDTF 無法發出 HTTP 請求。 SQL UDF 可存取 http_request() 函式，該函式可搭配 Unity Catalog 連線運作。

步驟 1：設定 Unity Catalog HTTP 連線

在建立 UDF 之前，你需要先設定 Unity Catalog HTTP 連線，以安全儲存你的 Slack API 憑證。 將 <xoxb-your-slack-bot-token> 替換為您實際的 Slack Bot 權杖。 你可以從 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 $$。
  • 將 YAML 設定嵌入 SQL 註解區塊（/* ... */）。
  • 可以用這個 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 函式包含以下功能：

Feature Purpose
http_request() 會對外部 API 發出 HTTP 呼叫。
conn => 'my_slack_connection' 引用 UC 連線進行驗證。
to_json() 與 named_struct() 為 Slack API 建構 JSON 有效載荷。
YAML 註解區塊 由 Lakeflow Designer 用來建立運算子。
CASE WHEN 實作預覽模式邏輯。

步驟四：測試功能

接著，先測試該函式是否正常運作，再將其註冊為運算子。

請先在預覽模式測試，以避免發送 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

步驟五：註冊營運商

將操作員加入你的 .user_defined_operators.yaml 檔案：

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

Note

如果你在使用者資料夾中定義這個檔案，它只會顯示給你。 欲了解更多資訊，請參閱 「讓您的營運商可被發現」。

步驟 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 頻道的文字輸入欄位。

用戶可以根據自己的資料發送通知。 例如，當某些門檻超過時會發出警示。

常見的使用案例

  • 警示：偵測到資料品質問題時發送通知。
  • 通知：當工作流程完成時通知團隊。
  • Webhooks：呼叫外部 API 來觸發下游程序。
  • 記錄：將稽核訊息傳送至外部系統。

建構 API 呼叫運算子的最佳實務

  1. 務必使用預覽模式：新增 is_preview 設定屬性 format: is_preview 以防止意外呼叫 API。
  2. 使用 Unity 目錄連線：千萬不要在 UDF 裡硬編碼憑證。 Unity 目錄連線僅在 SQL UDF 中提供。
  3. 優雅地處理錯誤：API 呼叫可能會失敗;考慮錯誤時該回傳什麼。
  4. 徹底測試：開發期間使用預覽模式。
  5. 記錄連線設定：使用者需要知道要建立哪種連線。
  • Last updated on