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

Gründe für die Verwendung einer 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 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. 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 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: 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.

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 .user_defined_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 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:

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.

Verwenden Sie den Operator in Lakeflow Designer

Nachdem der Operator registriert ist, erscheint er im 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. Warnungen beispielsweise, 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-Katalogverbindungen: Nie hartcodieren Sie Anmeldeinformationen 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 während der Entwicklung den Vorschaumodus.
  5. Dokumentieren Sie das Verbindungssetup: Benutzer müssen wissen, welche Verbindung erstellt werden soll.
  • Zuletzt aktualisiert um