Självstudie: Skicka Slack-meddelande

I den här självstudien skapar du en SQL UDF-operator för Lakeflow Designer som publicerar meddelanden till Slack-kanaler. SQL-UDF:er är rätt val när en funktion behöver anropa externa API:er via HTTP. En bredare översikt finns i Användardefinierade operatorer i Lakeflow Designer.

Overview

Den här operatorn skickar meddelanden till Slack med hjälp av:

  • SQL UDF: Skrivet i SQL i stället för Python.
  • HTTP-anslutning för Unity Catalog: Hanterar Slack API-autentiseringsuppgifter på ett säkert sätt.
  • Stöd för förhandsversionsläge: Förhindrar faktiska Slack API-anrop under förhandsversionen av arbetsflödet.
  • Uttrycksparametrar: Tillåter dynamiskt meddelandeinnehåll från DataFrame-kolumner.

Varför använda en SQL UDF

För operatorer som behöver anropa externa API:er (till exempel Slack, REST-slutpunkter, webhooks) måste du använda SQL-UDF:er. Python UDF:er och UDTF:er kan inte skicka HTTP-begäranden. SQL-UDF:er har åtkomst till funktionen http_request() som fungerar med Unity Catalog-anslutningar.

Steg 1: Konfigurera HTTP-anslutningen för Unity Catalog

Innan du skapar UDF måste du konfigurera en HTTP-anslutning för Unity Catalog för att lagra dina Slack API-autentiseringsuppgifter på ett säkert sätt. Ersätt <xoxb-your-slack-bot-token> med din faktiska Slack Bot-token. Du kan hämta detta från dina Slack-appinställningar. Du kan använda samma anslutning mellan flera UDF:er. Mer information finns i Ansluta till externa HTTP-tjänster.

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

Steg 2: Skapa operatorn YAML

Skapa nu YAML för operatorn. Mer information om schemat finns i Användardefinierad operatörs YAML-referens.

YAML för den här operatorn innehåller:

  • Uttrycksparameter (msg): Tillåter dynamiskt meddelandeinnehåll från dataramskolumner.
  • Strängparameter (channel): Statiskt kanalnamn/ID.
  • Förhandsgranskningsläge (is_preview): En konfigurationsegenskap med format: is_preview som aktiverar förhandsgranskningsläge för att förhindra faktiska API-anrop under testningen.
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

Detta omfattar:

Konfigurationsnyckel Widget Purpose
msg expression Dynamiskt meddelandeinnehåll från indata.
channel input Slack-kanal att skicka till (t.ex. #alerts).
is_preview Inte tillämpligt En boolesk konfigurationsegenskap med format: is_preview som gör att operatorn kan bete sig annorlunda under en förhandsversion (i det här fallet undviker du att skapa ett Slack-meddelande).

Steg 3: Skapa funktionen Unity Catalog

När du skapar SQL UDF:er finns det några saker som är ovanliga jämfört med de flesta SQL-frågor:

  • Använd syntaxen RETURN i stället för AS $$.
  • Bädda in YAML-konfigurationen i ett SQL-kommentarsblock (/* ... */).
  • Kan använda http_request funktionen för API-anrop.
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
);

Den här SQL-funktionen innehåller följande funktioner:

Feature Purpose
http_request() Gör HTTP-anrop till externa API:er.
conn => 'my_slack_connection' Refererar till UC-anslutningen för autentisering.
to_json() och named_struct() Konstruerar JSON-nyttolasten för Slack-API:et.
YAML-kommentarsblock Används av Lakeflow Designer för att skapa operatorn.
CASE WHEN Implementerar logik för förhandsgranskningsläge.

Steg 4: Testa funktionen

Testa sedan funktionen för att se till att den fungerar innan du registrerar den som operatör.

Testa först i förhandsgranskningsläge för att undvika att skicka ett Slack-meddelande:

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

Testa med externt API-anrop (skickar ett meddelande till 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

Steg 5: Registrera operatorn

Lägg till operatorn i din .user_defined_operators.yaml-fil:

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

Note

Om du definierar den här filen i användarmappen visas den bara för dig. Mer information finns i Gör operatören identifierbar.

Steg 6: Konfigurera behörigheter

För SQL UDF:er som använder Unity Catalog-anslutningar behöver användarna ytterligare behörighet:

-- 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 Utan behörighet kan användarna inte göra API-anrop även om de kan köra funktionen.

Använda operatorn i Lakeflow Designer

När den har registrerats visas operatorn i Lakeflow Designer med:

  • En indataport för att ansluta din datakälla.
  • En uttrycksväljare för att välja vilken kolumn som innehåller meddelandeinnehållet.
  • En textinmatning för Slack-kanalen.

Användare kan skicka meddelanden baserat på sina data. Till exempel aviseringar när vissa tröskelvärden överskrids.

Vanliga användningsfall

  • Aviseringar: Skicka meddelanden när datakvalitetsproblem identifieras.
  • Meddelanden: Meddela team när arbetsflödena har slutförts.
  • Webhooks: Anropa externa API:er för att utlösa underordnade processer.
  • Loggning: Skicka granskningsmeddelanden till externa system.

Metodtips för att skapa API-anropande operatorer

  1. Använd alltid förhandsgranskningsläge: Lägg till en is_preview konfigurationsegenskap med format: is_preview för att förhindra oavsiktliga API-anrop.
  2. Använd Unity Catalog-anslutningar: Hårdkoda aldrig autentiseringsuppgifter i din UDF. Unity Catalog-anslutningar är endast tillgängliga i SQL UDF:er.
  3. Hantera fel på ett korrekt sätt: API-anrop kan misslyckas; överväg vad som ska returneras vid fel.
  4. Testa noggrant: Använd förhandsgranskningsläget under utvecklingen.
  5. Dokumentera anslutningskonfigurationen: Användarna måste veta vilken anslutning som ska skapas.
  • Last updated on