Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
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 CATALOGauf demmainKatalog, undCREATE SCHEMAaufmain, oderUSE SCHEMAundCREATE FUNCTIONauf einem bestehendenmain.example_outputSchema. Um einen anderen Katalog oder ein anderes Schema zu verwenden, ersetzen Siemain.example_outputdurchgehend. Siehe Unity Catalog-Berechtigungsreferenz. -
CREATE CONNECTIONim 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, mitformat: is_previewder 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
RETURNSyntax anstelle vonAS $$. - Einbetten der YAML-Konfiguration in einen SQL-Kommentarblock (
/* ... */). - Kann die
http_requestFunktion 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
- In einer visuellen Datenvorbereitung öffnen Sie im linken Bereich das Menü Operatoren und finden den Operator Slack-Nachricht senden.
- Ziehe den Operator auf die Arbeitsfläche und verbinde einen Eingang damit.
- Doppelklicken Sie auf den Operator, um dessen Konfigurationsbereich zu öffnen, und legen Sie anschließend die Felder fest.
- 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
-
Verwenden Sie immer den Vorschaumodus: Fügen Sie eine
is_previewKonfigurationseigenschaft hinzuformat: is_preview, um versehentliche API-Aufrufe zu verhindern. -
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. - Fehler ordnungsgemäß behandeln: API-Aufrufe können fehlschlagen; Überlegen Sie, was beim Fehler zurückgegeben werden soll.
- Testen Sie sorgfältig: Verwenden Sie während der Entwicklung den Vorschaumodus.
- Dokumentieren Sie das Verbindungssetup: Benutzer müssen wissen, welche Verbindung erstellt werden soll.