チュートリアル: Slack メッセージを送信する
このチュートリアルでは、Slack チャンネルにメッセージを投稿するLakeflow Designer 用のSQL UDFオペレーターを作成します。より詳しい概要については、 Lakeflow Designer のカスタム演算子」を参照してください。
概要
この演算子は、以下を使用して Slack にメッセージを送信します。
- SQL UDF : Python ではなく SQL で記述されています。
- Unity Catalog HTTP 接続 : Slack API 資格情報を安全に管理します。
- プレビューモードのサポート ：ワークフローのプレビュー中に実際のSlack API呼び出しが行われるのを防ぎます。
- 式の問題 : DataFrame列からの動的メッセージ コンテンツを許可します。
SQL UDF を使用する理由
SQL UDFは、Unity Catalog HTTP接続を通じて認証するhttp_request()関数を使用して、外部APIs（Slack、REST Endpoint、Webhookなど）を呼び出すことができます。接続には認証情報が格納されているため、関数コードには記述されません。代わりにPythonからAPIを呼び出すには、python-run-function演算子を使用します。「チュートリアル: Gmail Eメール送信者演算子」を参照してください。
要件
- Unity Catalogが有効になっているワークスペースでのLakeflow Designerへのアクセス。前提条件をご覧ください。
USE CATALOGmainカタログのCREATE SCHEMA、mainのUSE SCHEMA、または既存のmain.example_outputスキーマのCREATE FUNCTION。別のカタログまたはスキーマを使用するには、main.example_output全体を置き換えます。Unity Catalog の特権リファレンスを参照してください。CREATE CONNECTIONHTTP接続を作成するために、Unity Catalogメタストアで。外部 HTTP サービスへの接続を参照してください。- チャンネルに投稿できるボットトークンを持つSlackアプリ。
ステップ 1: Unity Catalog HTTP 接続をセットアップする
UDF を作成する前に、Slack API 資格情報を安全に保存するために Unity Catalog HTTP 接続を設定する必要があります。<xoxb-your-slack-bot-token>実際の Slack Bot トークンに置き換えます。これは Slack アプリの設定から取得できます。同じ接続を複数の UDF にわたって使用できます。詳細については、 「外部 HTTP サービスへの接続」を参照してください。
CREATE CONNECTION my_slack_connection TYPE HTTP OPTIONS (
host 'https://slack.com',
port '443',
base_path '/api/',
bearer_token '<xoxb-your-slack-bot-token>'
);
ステップ 2: オペレーター YAML を作成する
次に、演算子のYAMLを作成します。スキーマの詳細については、カスタム演算子YAMLリファレンスを参照してください。
この演算子の YAML には以下が含まれます。
- 式パラメーター (
msg): データフレーム列からの動的なメッセージ コンテンツを許可します。 - 文字列不利 (
channel): 静的なチャンネル名/ID。 - プレビューモード （
is_preview）：format: is_previewを持つ設定プロパティで、プレビューモードを有効にして、テスト中に実際の API 呼び出しを防止します。
schema: custom-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
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
これには以下が含まれます。
設定キー | ウィジェット | 目的 |
|---|---|---|
|
| 入力データからの動的なメッセージ コンテンツ。 |
|
| 送信先の Slack チャンネル (例: |
| N/A |
|
ステップ 3: Unity Catalog関数を作成する
SQL UDFを作成する際には、ほとんどのSQLクエリとは異なる点がいくつかあります。
AS $$の代わりにRETURN構文を使用してください。- YAML 構成を SQL コメント ブロック (
/* ... */) に埋め込みます。 - API 呼び出しに
http_request関数を使用できます。
この例では、main.example_outputに関数を作成します。スキーマが存在しない場合は、最初にスキーマを作成します。
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.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
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
);
この SQL 関数には次の機能が含まれます。
機能 | 目的 |
|---|---|
| 外部APIsへの HTTP 呼び出しを行います。 |
| 認証のために UC 接続を参照します。 |
| Slack API の JSON ペイロードを構築します。 |
YAMLコメントブロック | Lakeflow Designer がオペレーターを作成するために使用されます。 |
| プレビュー モード ロジックを実装します。 |
ステップ 4: 機能をテストする
次に、関数を演算子として登録する前に、正しく動作するかどうかをテストしてください。
メッセージが送信されないように、まずプレビューモードでテストしてください。Preview mode - no message sent to #test-channel を返します。
SELECT main.example_output.send_slack_msg(
msg => 'Hello from Lakeflow Designer!',
channel => '#test-channel',
is_preview => true
) AS result;
実際のAPI呼び出しでテストして、Slackにメッセージを送信します。注意して使用してください。チャンネルに投稿し、Slack APIの応答JSONを返します。
SELECT main.example_output.send_slack_msg(
msg => 'Hello from Lakeflow Designer!',
channel => '#test-channel',
is_preview => false
) AS result;
ステップ 5: オペレーターを登録する
.custom_operators.yamlファイルに演算子を追加します:
operators:
- catalog: main
schema: example_output
functionName: send_slack_msg
ユーザーフォルダーにこのファイルを定義すると、ユーザーにのみ表示されます。情報については、 「オペレーターを登録して Lakeflow Designer にデプロイする」を参照してください。
ステップ 6: 権限を設定する
Unity Catalog接続を使用するSQL UDF の場合、ユーザーには追加の権限が必要です。
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>`;
USE CONNECTION権限がないと、ユーザーは関数を実行できても API 呼び出しを行うことができません。
ステップ 7: Lakeflow Designer での演算子の使用
- ビジュアルデータの準備で、左パネルの 「演算子」 メニューを開き、 「Slack メッセージを送信」 演算子を見つけます。
- 演算子をキャンバスにドラッグし、入力を接続します。
- オペレーターをダブルクリックして構成ペインを開き、各フィールドを設定します。
- 出力ペインで結果をプレビューする演算子を選択します。
演算子には次のものがあります：
- データソースを接続するための入力ポート。
- メッセージの内容が含まれる列を選択するための式ピッカー。
- Slack チャンネルのテキスト入力。
ユーザーは自身のデータに基づいて通知を送信できます。例えば、特定のしきい値を超過した場合にアラートを行います。
ヒントとベストプラクティス
外部 APIs を呼び出すオペレーターを構築するときは、次の例とガイドラインを使用してください。
一般的な使用例
- アラート： データ品質の問題が検出されたときに通知を送信します。
- 通知 ：ワークフローが完了したらチームに通知します。
- **ウェブフック**: 外部 APIs を呼び出して、ダウンストリームプロセスをトリガーします。
- ロギング ：外部システムに監査メッセージを送信します。
API呼び出し演算子を構築するためのベストプラクティス
- 常にプレビューモードを使用してください : 意図しないAPI呼び出しを防ぐため、
is_preview設定プロパティにformat: is_previewを指定してください。 - Unity Catalog接続を使用する : UDFに認証情報をハードコードしないでください。それらをUnity CatalogのHTTP接続に格納し、
http_request()で呼び出します。 - エラーを適切に処理する ：API呼び出しは失敗する可能性があるため、エラー時に何を返すかを考慮してください。
- 十分にテストしてください ：開発中にプレビューモードを使用してください。
- 接続設定のドキュメント化 ：ユーザーは、どの接続を作成する必要があるかを知る必要があります。