Lernprogramm: Senden einer Slack-Nachricht

Important

Dieses Feature befindet sich in der Public Preview.

In diesem Lernprogramm erstellen Sie einen SQL UDF-Operator für Lakeflow Designer, der Nachrichten in Slack-Kanälen veröffentlicht. SQL UDFs sind die richtige Wahl, wenn eine Funktion externe APIs über HTTP aufrufen muss. Eine umfassendere Übersicht finden Sie unter User-defined operators in Lakeflow Designer.

Überblick

Dieser Operator sendet Nachrichten an Slack über:

  • SQL UDF: Geschrieben in SQL und nicht in Python.
  • Unity Catalog HTTP-Verbindung: Slack-API-Anmeldeinformationen sicher verwaltet.
  • Unterstützung des Vorschaumodus: Verhindert tatsächliche Slack-API-Aufrufe während der Workflowvorschau.
  • Ausdrucksparameter: Ermöglicht dynamische Nachrichteninhalte aus DataFrame-Spalten.

Warum SQL UDF?

Für Operatoren, die externe APIs aufrufen müssen (z. B. Slack, REST-Endpunkte, Webhooks), müssen Sie SQL UDFs verwenden. Python UDFs und UDTFs können keine HTTP-Anforderungen ausführen. SQL UDFs haben Zugriff auf die http_request() Funktion, die mit Unity-Katalogverbindungen funktioniert.

Schritt 1: Einrichten der Unity-Katalog-HTTP-Verbindung

Bevor Sie die UDF erstellen, müssen Sie eine Unity-Katalog-HTTP-Verbindung einrichten, um Ihre Slack-API-Anmeldeinformationen sicher zu speichern. Ersetzen Sie <xoxb-your-slack-bot-token> durch Ihr tatsächliches Slack-Bot-Token. Sie können dies über Ihre Slack-App-Einstellungen abrufen. Sie können diese gleiche Verbindung über mehrere UDFs hinweg verwenden. Weitere Informationen finden Sie unter Herstellen einer Verbindung mit externen HTTP-Diensten.

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

Schritt 2: Erstellen des Operators YAML

Jetzt erstellen Sie das YAML für den Operator. Ausführliche Informationen zum Schema finden Sie in der YAML-Referenz zum benutzerdefinierten Operator.

Der YAML für diesen Operator umfasst:

  • Expression-Parameter (msg): Ermöglicht dynamische Nachrichteninhalte aus Datenframespalten.
  • String-Parameter (channel): Statischer Kanalname/ID.
  • Vorschaumodus (is_preview): Eine Konfigurationseigenschaft, mit format: is_preview der der Vorschaumodus aktiviert wird, um tatsächliche API-Aufrufe während des Tests zu verhindern.
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

Dazu gehören:

Konfigurationsschlüssel Widget Purpose
msg expression Dynamische Nachrichteninhalte aus Eingabedaten.
channel text Slack-Kanal, an den gesendet werden soll (z. B. #alerts).
is_preview n/a Eine Boolesche Konfigurationseigenschaft mit format: is_preview, die es dem Operator ermöglicht, sich bei einer Vorschau anders zu verhalten (in diesem Fall wird das tatsächliche Erstellen einer Slack-Nachricht vermieden).

Schritt 3: Erstellen der Unity-Katalogfunktion

Beim Erstellen von SQL UDFs gibt es einige Dinge, die im Vergleich zu den meisten SQL-Abfragen ungewöhnlich sind:

  • Verwenden Sie die RETURN Syntax anstelle von AS $$.
  • Einbetten der YAML-Konfiguration in einen SQL-Kommentarblock (/* ... */).
  • Kann die http_request Funktion für API-Aufrufe verwenden.
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
);

Diese SQL-Funktion enthält die folgenden Features:

Funktion Purpose
http_request() Führt HTTP-Aufrufe an externe APIs durch.
conn => 'my_slack_connection' Verweist auf die UC-Verbindung für die Authentifizierung.
to_json() und named_struct() Erstellt die JSON-Nutzlast für die Slack-API.
YAML-Kommentarblock Wird von Lakeflow Designer zum Erstellen des Operators verwendet.
CASE WHEN Implementiert die Logik für den Vorschaumodus.

Schritt 4: Testen der Funktion

Testen Sie als Nächstes die Funktion, um sicherzustellen, dass sie funktioniert, bevor Sie sie als Operator registrieren.

Testen Sie zuerst im Vorschaumodus, um das Senden einer Slack-Nachricht zu vermeiden:

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

Testen mit externem API-Aufruf (sendet eine Nachricht an 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

Schritt 5: Registrieren des Operators

Fügen Sie den Operator Ihrer .user_defined_operators.yaml-Datei hinzu:

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

Note

Wenn Sie diese Datei in Ihrem Benutzerordner definieren, wird sie nur für Sie angezeigt. Weitere Informationen finden Sie unter Machen Sie Ihren Operator auffindbar.

Schritt 6: Einrichten von Berechtigungen

Für SQL-UDFs, die Unity-Katalogverbindungen verwenden, benötigen Benutzer eine zusätzliche Berechtigung:

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

Ohne die USE CONNECTION Berechtigung können Benutzer keine API-Aufrufe tätigen, auch wenn sie die Funktion ausführen können.

Den Operator in Lakeflow Designer verwenden

Nach der Registrierung wird der Operator in Lakeflow Designer mit:

  • Ein Eingabeport zum Verbinden der Datenquelle.
  • Ein Auswahlfeld für Ausdrücke, mit dem ausgewählt wird, welche Spalte den Inhalt der Nachricht enthält.
  • Eine Texteingabe für den Slack-Kanal.

Benutzer können Benachrichtigungen basierend auf ihren Daten senden, z. B. Warnungen, wenn bestimmte Schwellenwerte überschritten werden.

Häufige Anwendungsfälle

  • Warnungen – Benachrichtigungen senden, wenn Probleme mit der Datenqualität erkannt werden.
  • Benachrichtigungen – Benachrichtigen Sie Teams, wenn Workflows abgeschlossen sind.
  • Webhooks – Rufen Sie externe APIs auf, um nachgeschaltete Prozesse auszulösen.
  • Protokollierung – Senden von Überwachungsmeldungen an externe Systeme.

Bewährte Methoden zum Erstellen von API-aufrufenden Operatoren

  1. Verwenden Sie immer den Vorschaumodus – Fügen Sie eine is_preview Konfigurationseigenschaft hinzu format: is_preview , um versehentliche API-Aufrufe zu verhindern.
  2. Verwenden Sie Unity Catalog-Verbindungen — Codieren Sie Anmeldeinformationen niemals fest in Ihrer UDF. Unity-Katalogverbindungen sind nur in SQL-UDFs verfügbar.
  3. Fehler ordnungsgemäß behandeln – API-Aufrufe können fehlschlagen; Überlegen Sie, was beim Fehler zurückgegeben werden soll.
  4. Testen Sie sorgfältig – Verwenden Sie den Vorschaumodus während der Entwicklung.
  5. Dokumentieren Sie die Verbindungseinrichtung – Benutzer müssen wissen, welche Verbindung erstellt werden soll.
  • Last updated on