メインコンテンツまでスキップ
に最終更新

チュートリアル: Slack メッセージを送信する

このチュートリアルでは、Slack チャンネルにメッセージを投稿するLakeflow Designer 用のSQL UDFオペレーターを作成します。 SQL UDFは、関数がHTTP経由で外部APIs呼び出す必要がある場合に最適な選択肢です。 より詳しい概要については、 Lakeflow Designer のユーザー定義演算子」を参照してください。

概要​

この演算子は、以下を使用して Slack にメッセージを送信します。

  • SQL UDF : Python ではなく SQL で記述されています。
  • Unity Catalog HTTP 接続 : Slack API 資格情報を安全に管理します。
  • プレビューモードのサポート ：ワークフローのプレビュー中に実際のSlack API呼び出しが行われるのを防ぎます。
  • 式の問題 : DataFrame列からの動的メッセージ コンテンツを許可します。

SQL UDF を使用する理由​

外部APIs (Slack、 RESTエンドポイント、Webhook など) を呼び出す必要があるオペレーターの場合は、 SQL UDF を使用する必要があります。 Python UDF および UDTF は HTTP リクエストを行うことができません。SQL UDF はUnity Catalog接続で動作するhttp_request()関数にアクセスできます。

ステップ 1: Unity Catalog HTTP 接続をセットアップする​

UDF を作成する前に、Slack API 資格情報を安全に保存するために Unity Catalog HTTP 接続を設定する必要があります。<xoxb-your-slack-bot-token>実際の Slack Bot トークンに置き換えます。これは Slack アプリの設定から取得できます。同じ接続を複数の UDF にわたって使用できます。詳細については、 「外部 HTTP サービスへの接続」を参照してください。

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

ステップ 2: オペレーター YAML を作成する​

それでは、演算子のYAMLを作成してください。スキーマの詳細については、ユーザー定義オペレーターの YAML リファレンスを参照してください。

この演算子の YAML には以下が含まれます。

  • 式パラメーター ( msg ): データフレーム列からの動的なメッセージ コンテンツを許可します。
  • 文字列不利 ( channel ): 静的なチャンネル名/ID。
  • プレビューモード （ is_preview ）： format: is_previewを持つ設定プロパティで、プレビューモードを有効にして、テスト中に実際の API 呼び出しを防止します。
YAML
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

これには以下が含まれます。

設定キー

ウィジェット

目的

msg

expression

入力データからの動的なメッセージ コンテンツ。

channel

input

送信先の Slack チャンネル (例: #alerts )。

is_preview

N/A

オペレーターがプレビュー中に異なる動作をするようにするブール型の設定プロパティで、値はformat: is_preview （この場合、Slackメッセージを実際に作成しないようにします）。

ステップ 3: Unity Catalog関数を作成する​

SQL UDFを作成する際には、ほとんどのSQLクエリとは異なる点がいくつかあります。

  • AS $$の代わりにRETURN構文を使用してください。
  • YAML 構成を SQL コメント ブロック ( /* ... */ ) に埋め込みます。
  • API 呼び出しにhttp_request関数を使用できます。
SQL
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
);

この SQL 関数には次の機能が含まれます。

機能

目的

http_request()

外部APIsへの HTTP 呼び出しを行います。

conn => 'my_slack_connection'

認証のために UC 接続を参照します。

to_json() そして named_struct()

Slack API の JSON ペイロードを構築します。

YAMLコメントブロック

Lakeflow Designer がオペレーターを作成するために使用されます。

CASE WHEN

プレビュー モード ロジックを実装します。

ステップ 4: 機能をテストする​

次に、関数を演算子として登録する前に、正しく動作するかどうかをテストしてください。

Slack メッセージを送信しないようにするには、まずプレビュー モードでテストします。

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

Test with external API call (Slackにメッセージを送信します):

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

ステップ 5: オペレーターを登録する​

.user_defined_operators.yamlファイルに演算子を追加します:

YAML
operators:
  - catalog: main
    schema: my_schema
    functionName: send_slack_msg
注記

このファイルをユーザーフォルダ内に定義した場合、そのファイルはあなた以外には表示されません。詳細については、 「オペレータを検出可能にする」を参照してください。

ステップ 6: 権限を設定する​

Unity Catalog接続を使用するSQL UDF の場合、ユーザーには追加の権限が必要です。

SQL
-- 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>`;
重要

USE CONNECTION権限がないと、ユーザーは関数を実行できても API 呼び出しを行うことができません。

Lakeflow Designer での演算子の使用​

登録されると、オペレーターはLakeflow Designer に次のように表示されます：

  • データソースを接続するための入力ポート。
  • メッセージの内容が含まれる列を選択するための式ピッカー。
  • Slack チャンネルのテキスト入力。

ユーザーは自身のデータに基づいて通知を送信できます。例えば、特定のしきい値を超過した場合にアラートを行います。

一般的な使用例​

  • アラート： データ品質の問題が検出されたときに通知を送信します。
  • 通知 ：ワークフローが完了したらチームに通知します。
  • **ウェブフック**: 外部 APIs を呼び出して、ダウンストリームプロセスをトリガーします。
  • ロギング ：外部システムに監査メッセージを送信します。

API呼び出し演算子を構築するためのベストプラクティス​

  1. 常にプレビューモードを使用してください : 意図しないAPI呼び出しを防ぐため、is_preview 設定プロパティに format: is_preview を指定してください。
  2. Unity Catalog 接続を使用してください ：UDF に認証情報をハードコードしないでください。Unity Catalog の接続は SQL UDF でのみ利用できます。
  3. エラーを適切に処理する ：API呼び出しは失敗する可能性があるため、エラー時に何を返すかを考慮してください。
  4. 十分にテストしてください ：開発中にプレビューモードを使用してください。
  5. 接続設定のドキュメント化 ：ユーザーは、どの接続を作成する必要があるかを知る必要があります。
このページの見出し