Oktatóanyag: Slack-üzenet küldése

Ebben az oktatóanyagban létrehoz egy SQL UDF-operátort a Lakeflow Designerhez, amely üzeneteket küld a Slack-csatornákra. Az SQL UDF-ek a megfelelő választás, ha egy függvénynek HTTP-n keresztül kell meghívnia a külső API-kat. A szélesebb körű áttekintésért tekintse meg a Felhasználó által definiált operátorokat a Lakeflow Designerben.

Overview

Ez az operátor az alábbi módon küld üzeneteket a Slacknek:

SQL UDF: Python helyett SQL-ben íródott.
Unity Catalog HTTP-kapcsolat: Biztonságosan kezeli a Slack API hitelesítő adatait.
Előzetes verziójú mód támogatása: Megakadályozza a tényleges Slack API-hívásokat a munkafolyamat előzetes verziója során.
Kifejezésparaméterek: Lehetővé teszi a DataFrame-oszlopokból származó dinamikus üzenettartalmak megjelenítését.

Miért érdemes SQL UDF-et használni?

Külső API-kat (például Slack, REST-végpontok, webhookok) meghívni kívánó operátorok esetén SQL UDF-eket kell használnia. Python UDF-ek és UDTF-ek nem tudnak HTTP-kéréseket küldeni. Az SQL UDF-ek hozzáférhetnek a http_request() Unity Catalog-kapcsolatokhoz használható függvényhez.

1. lépés: A Unity-katalógus HTTP-kapcsolatának beállítása

Az UDF létrehozása előtt be kell állítania egy Unity Catalog HTTP-kapcsolatot a Slack API hitelesítő adatainak biztonságos tárolásához. Cserélje le a(z) <xoxb-your-slack-bot-token> elemet a tényleges Slack Bot Tokenre. Ezt a Slack-alkalmazás beállításaiból szerezheti be. Ezt a kapcsolatot több UDF-ben is használhatja. További információ: Csatlakozás külső HTTP-szolgáltatásokhoz.

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. lépés: A YAML operátor létrehozása

Most készítse el az operátor YAML-fájlját. A sémával kapcsolatos részletekért tekintse meg a felhasználó által definiált operátor YAML-hivatkozását.

Az operátorHOZ tartozó YAML a következőket tartalmazza:

Kifejezésparaméter (msg): Lehetővé teszi a dinamikus üzenettartalmak adatkeretoszlopokból való megjelenítését.
Sztringparaméter (channel): Statikus csatorna neve/azonosítója.
Előnézeti mód (is_preview): Olyan konfigurációs tulajdonság, amely format: is_preview lehetővé teszi az előzetes verziójú módot, hogy megakadályozza a tényleges API-hívásokat a tesztelés során.

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

Ezek közé tartoznak a következők:

Konfigurációs kulcs	Widget	Alkalmazás célja
`msg`	`expression`	Dinamikus üzenettartalom bemeneti adatokból.
`channel`	`input`	Az üzenetküldéshez használt Slack-csatorna (pl. `#alerts`).
`is_preview`	nincs adat	Egy logikai konfigurációs tulajdonság `format: is_preview`, amely lehetővé teszi, hogy az operátor előnézet során másképp viselkedjen (ebben az esetben például ne hozzon létre ténylegesen Slack-üzenetet).

3. lépés: A Unity Catalog függvény létrehozása

SQL UDF-ek létrehozásakor néhány dolog nem gyakori a legtöbb SQL-lekérdezéshez képest:

Használja a RETURN szintaxist ahelyett, hogy AS $$.
A YAML-konfiguráció beágyazása SQL-megjegyzésblokkba (/* ... */).
Használhatja a függvényt http_request API-hívásokhoz.

A példa létrehozza a függvényt -ben main.example_output. Először hozd létre a sémát, ha nem létezik:

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: 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
);

Ez az SQL-függvény a következő funkciókat tartalmazza:

Funkció	Alkalmazás célja
`http_request()`	HTTP-hívásokat kezdeményez külső API-khoz.
`conn => 'my_slack_connection'`	A hitelesítéshez az UC-kapcsolatra hivatkozik.
`to_json()` és `named_struct()`	Összeállítja a Slack API JSON-kéréstörzsét.
YAML-megjegyzésblokk	A Lakeflow Designer használja az operátor létrehozásához.
`CASE WHEN`	Az előnézeti mód logikáját implementálja.

4. lépés: A függvény tesztelése

Ezután tesztelje a függvényt, hogy megbizonyosodjon arról, hogy megfelelően működik, mielőtt operátorként regisztrálja.

Először tesztelj előnézeti módban, így nem küldenek üzenetet. Visszaadja a Preview mode - no message sent to #test-channel értéket.

SELECT main.example_output.send_slack_msg(
  msg => 'Hello from Lakeflow Designer!',
  channel => '#test-channel',
  is_preview => true
) AS result;

Tesztelj egy valódi API hívással, hogy üzenetet küldj a Slacknek. Óvatosan használd: posztol a csatornára, és visszaadja a Slack API válasz JSON-ját.

SELECT main.example_output.send_slack_msg(
  msg => 'Hello from Lakeflow Designer!',
  channel => '#test-channel',
  is_preview => false
) AS result;

5. lépés: Az operátor regisztrálása

Adja hozzá az operátort a(z) .user_defined_operators.yaml fájlhoz:

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

Note

Ha ezt a fájlt a felhasználói mappában definiálja, az csak Ön számára jelenik meg. További információ: Az operátor felderíthetővé tétele.

6. lépés: Engedélyek beállítása

A Unity Catalog-kapcsolatokat használó SQL UDF-ekhez a felhasználóknak további engedélyre van szükségük:

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

Az engedély nélkül a USE CONNECTION felhasználók akkor sem tudnak API-hívásokat kezdeményezni, ha végrehajthatják a függvényt.

Az operátor használata a Lakeflow Designerben

A regisztrálás után az operátor a Lakeflow Designerben a következőkkel jelenik meg:

Egy bemeneti port az adatforrás csatlakoztatásához.
Egy kifejezésválasztó, amely kiválasztja, hogy melyik oszlop tartalmazza az üzenet tartalmát.
A Slack-csatorna szöveges bemenete.

A felhasználók az adataik alapján küldhetnek értesítéseket. Riasztás például bizonyos küszöbértékek túllépésekor.

Gyakori használati esetek

Riasztások: Értesítések küldése az adatminőségi problémák észlelésekor.
Értesítések: A munkafolyamatok befejeződésekor értesítse a csapatokat.
Webhookok: Külső API-k meghívása az alsóbb rétegbeli folyamatok aktiválásához.
Naplózás: Auditüzenetek küldése külső rendszereknek.

Ajánlott eljárások API-hívó operátorok létrehozásához

Mindig használjon előnézeti módot: Adjon hozzá egy is_preview konfigurációs tulajdonságot format: is_preview a véletlen API-hívások elkerülése érdekében.
Unity Catalog-kapcsolatok használata: Soha ne kódoljon hitelesítő adatokat az UDF-ben. A Unity Catalog-kapcsolatok csak SQL UDF-ekben érhetők el.
Kezelje a hibákat elegánsan: az API-hívások meghiúsulhatnak; gondolja át, mit adjon vissza hiba esetén.
Alaposan tesztelje: Előzetes verziójú mód használata a fejlesztés során.
Dokumentálja a kapcsolat beállítását: A felhasználóknak tudniuk kell, hogy milyen kapcsolatot kell létrehozniuk.

Visszajelzés

Hasznosnak találta ezt az oldalt?

Last updated on 2026-09-10