Kurz: Odeslání zprávy Slack

V tomto kurzu vytvoříte operátor UDF SQL pro Návrhář Lakeflow, který publikuje zprávy do kanálů Slack. Funkce SQL UDF je správnou volbou, když funkce potřebuje volat externí rozhraní API přes protokol HTTP. Širší přehled najdete v tématu Uživatelem definované operátory v Návrháři Lakeflow.

Overview

Tento operátor odesílá zprávy do Slacku pomocí:

  • SQL UDF: Místo Python se píše v SQL.
  • Připojení HTTP v Unity Catalog: Bezpečně spravuje přihlašovací údaje k rozhraní API Slacku.
  • Podpora režimu náhledu: Zabraňuje skutečným voláním rozhraní Slack API během náhledu pracovního postupu.
  • Parametry výrazu: Umožňuje dynamický obsah zpráv ze sloupců datového rámce.

Proč používat uživatelsky definovanou funkci SQL

Pro operátory, které potřebují volat externí rozhraní API (například Slack, koncové body REST, webhooky), musíte použít UDF SQL. Uživatelsky definované funkce (UDF) a uživatelsky definované tabulkové funkce (UDTF) v Pythonu nemohou odesílat požadavky HTTP. Funkce SQL UDF mají přístup k funkci http_request(), která funguje s připojeními Unity Catalogu.

Krok 1: Nastavení připojení HTTP katalogu Unity

Před vytvořením UDF musíte nastavit připojení HTTP katalogu Unity pro bezpečné uložení přihlašovacích údajů rozhraní Slack API. Nahraďte <xoxb-your-slack-bot-token> skutečným tokenem robota Slack. Můžete to získat z nastavení aplikace Slack. Toto stejné připojení můžete použít napříč více funkcemi definovanými uživatelem. Další informace najdete v tématu Připojení k externím službám 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>'
);

Krok 2: Vytvoření operátoru YAML

Teď vytvořte YAML pro operátor. Podrobnosti o schématu naleznete v tématu Uživatelem definovaný operátor YAML reference.

YAML pro tento operátor zahrnuje:

  • Parametr výrazu (msg): Umožňuje dynamický obsah zpráv ze sloupců datového rámce.
  • Řetězcový parametr (channel): Název nebo ID statického kanálu
  • Režim náhledu (is_preview): Vlastnost konfigurace, která format: is_preview umožňuje režim náhledu, aby se zabránilo skutečným voláním rozhraní API během testová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

Sem patří:

Konfigurační klíč Widget Purpose
msg expression Dynamický obsah zprávy ze vstupních dat
channel input Kanál Slack, do kterého se má odesílat (např. #alerts).
is_preview není k dispozici Booleovská konfigurační vlastnost s format: is_preview, která umožňuje operátoru chovat se v režimu náhledu odlišně (v tomto případě se skutečně nevytvoří zpráva ve Slacku).

Krok 3: Vytvoření funkce Katalogu Unity

Při vytváření UDF SQL existuje několik věcí, které jsou ve srovnání s většinou dotazů SQL neobvyklé:

  • Použijte syntaxi RETURN místo AS $$.
  • Vložte konfiguraci YAML do bloku komentáře SQL (/* ... */).
  • Může použít http_request funkci pro volání rozhraní 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
);

Tato funkce SQL obsahuje následující funkce:

funkce Purpose
http_request() Provádí volání HTTP do externích rozhraní API.
conn => 'my_slack_connection' Odkazuje na připojení UC pro ověřování.
to_json() a named_struct() Vytvoří datový obsah JSON pro API Slacku.
Blok komentáře YAML Používá návrhář Lakeflow k vytvoření operátoru.
CASE WHEN Implementuje logiku režimu náhledu.

Krok 4: Testování funkce

Dále otestujte funkci, abyste se ujistili, že funguje, než ji zaregistrujete jako operátor.

Nejprve otestujte v režimu náhledu, abyste se vyhnuli odesílání zprávy 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"

Testování pomocí volání externího rozhraní API (odešle zprávu do Slacku):

-- 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

Krok 5: Registrace operátoru

Přidejte operátor do souboru .user_defined_operators.yaml:

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

Note

Pokud tento soubor definujete ve složce uživatele, zobrazí se vám jenom za vás. Další informace najdete v článku Jak zajistit, aby byl váš operátor dohledatelný.

Krok 6: Nastavení oprávnění

Pro uživatele uživatelsky definovaných funkcí SQL, které využívají připojení služby Unity Catalog, je vyžadováno další oprávnění:

-- 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 Bez oprávnění uživatelé nebudou moct provádět volání rozhraní API, i když můžou funkci spustit.

Použití operátoru v nástroji Lakeflow Designer

Po registraci se operátor zobrazí v Návrháři Lakeflow s následujícími informacemi:

  • Vstupní port pro připojení zdroje dat.
  • Nástroj pro výběr výrazu k určení, který sloupec obsahuje text zprávy.
  • Textový vstup pro kanál Slack.

Uživatelé můžou posílat oznámení na základě jejich dat. Například upozorňování při překročení určitých prahových hodnot.

Běžné případy použití

  • Upozornění: Odesílání oznámení při zjištění problémů s kvalitou dat
  • Oznámení: Upozorněte týmy na dokončení pracovních postupů.
  • Webhooky: Volání externích rozhraní API pro aktivaci podřízených procesů
  • Protokolování: Odesílejte zprávy auditu do externích systémů.

Osvědčené postupy pro vytváření operátorů volání rozhraní API

  1. Vždy používejte režim náhledu: Přidejte is_preview vlastnost konfigurace s format: is_preview cílem zabránit náhodným voláním rozhraní API.
  2. Používejte připojení katalogu Unity: Nikdy ve vašem UDF nezakódujte přihlašovací údaje. Připojení katalogu Unity jsou k dispozici pouze v uživatelem definovaných funkcích SQL.
  3. Elegantní zpracování chyb: Volání API mohou selhat; zvažte, co vracet v případě chyby.
  4. Důkladně otestujte: Během vývoje používejte režim náhledu.
  5. Zdokumentujte nastavení připojení: Uživatelé musí vědět, jaké připojení se má vytvořit.
  • Last updated on