Lernprogramm: Senden einer Slack-Nachricht

In diesem Lernprogramm erstellen Sie einen SQL UDF-Operator für Lakeflow Designer, der Nachrichten in Slack-Kanälen veröffentlicht. Für einen umfassenderen Überblick siehe Benutzerdefinierte Operatoren 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.

Gründe für die Verwendung einer SQL-UDF

SQL-UDFs können externe APIs (wie Slack, REST-Endpunkte und Webhooks) mit der http_request() Funktion aufrufen, wobei die Authentifizierung über eine HTTP-Verbindung im Unity Catalog erfolgt. Die Verbindung speichert die Zugangsdaten, sodass sie nicht im Funktionscode enthalten sind. Um stattdessen eine API aus Python aufzurufen, verwenden Sie einen python-run-function Operator. Siehe Tutorial: Gmail-E-Mail-Absenderoperator.

Requirements

  • Zugriff auf Lakeflow Designer in einem Arbeitsbereich mit aktiviertem Unity Catalog. Siehe Voraussetzungen.
  • USE CATALOG auf dem main Katalog, und CREATE SCHEMA auf main, oder USE SCHEMA und CREATE FUNCTION auf einem bestehenden main.example_output Schema. Um einen anderen Katalog oder ein anderes Schema zu verwenden, ersetzen Sie main.example_output durchgehend. Siehe Unity Catalog-Berechtigungsreferenz.
  • CREATE CONNECTION im Unity Catalog Metastore, um die HTTP-Verbindung herzustellen. Siehe Herstellen einer Verbindung mit externen HTTP-Diensten.
  • Eine Slack-App mit einem Bot-Token, das auf deinem Kanal posten kann.

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

Erstellen Sie nun das YAML für den Operator. Für Details zum Schema siehe Referenz zum benutzerdefinierten Operator YAML.

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: custom-operator-v0.2.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
      x-ui:
        widget: input
    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 input Slack-Kanal, an den gesendet werden soll (z. B. #alerts).
is_preview n/a Eine boolesche Konfigurationseigenschaft mit format: is_preview, die bewirkt, dass sich der Operator bei einer Vorschau anders verhält (in diesem Fall, ohne tatsächlich eine Slack-Nachricht zu erstellen).

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.

Das Beispiel erzeugt die Funktion in main.example_output. Erstelle zuerst das Schema, falls es nicht existiert:

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: custom-operator-v0.2.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
          x-ui:
            widget: input
        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.

Teste zuerst im Vorschaumodus, damit keine Nachricht gesendet wird. Er gibt Preview mode - no message sent to #test-channel zurück.

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

Testen Sie mit einem echten API-Aufruf, um eine Nachricht an Slack zu senden. Verwenden Sie dies mit Vorsicht: Es postet auf dem Kanal und liefert das Slack API Response-JSON zurück.

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

Schritt 5: Registrieren des Operators

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

operators:
  - catalog: main
    schema: example_output
    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 Registrieren und Ihren Operator in Lakeflow Designer bereitstellen.

Schritt 6: Einrichten von Berechtigungen

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

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

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

Schritt 7: Verwenden Sie den Operator in Lakeflow Designer

  1. In einer visuellen Datenvorbereitung öffnen Sie im linken Bereich das Menü Operatoren und finden den Operator Slack-Nachricht senden.
  2. Ziehe den Operator auf die Arbeitsfläche und verbinde einen Eingang damit.
  3. Doppelklicken Sie auf den Operator, um dessen Konfigurationsbereich zu öffnen, und legen Sie anschließend die Felder fest.
  4. Wählen Sie den Operator aus, um seine Ergebnisse im Ausgabefenster vorab anzuzeigen.

Der Operator hat:

  • 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. Warnungen beispielsweise, wenn bestimmte Schwellenwerte überschritten werden.

Tipps und bewährte Verfahren

Verwenden Sie die folgenden Beispiele und Richtlinien, wenn Sie Operatoren erstellen, die externe APIs aufrufen.

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-Katalogverbindungen: Nie hartcodieren Sie Anmeldeinformationen in Ihrer UDF. Speichere sie in einer Unity-Katalog-HTTP-Verbindung und rufe sie mit http_request()auf.
  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 während der Entwicklung den Vorschaumodus.
  5. Dokumentieren Sie das Verbindungssetup: Benutzer müssen wissen, welche Verbindung erstellt werden soll.

Zusätzliche Ressourcen