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

Important

この機能は パブリック プレビュー段階です。

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

開始する

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

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

SQL UDF を使用する理由

外部 API (Slack、REST エンドポイント、Webhook など) を呼び出す必要がある演算子の場合は、SQL UDF を使用する必要があります。 Python UDF と UDTF は HTTP リクエストを送信できません。 SQL UDF は、Unity カタログ接続で動作する http_request() 関数にアクセスできます。

手順 1: Unity カタログ HTTP 接続を設定する

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

-- 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): テスト中に実際の API 呼び出しを防ぐためにプレビュー モードを有効にする format: is_preview を持つ構成プロパティ。
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

これには、以下のことが含まれます。

設定キー Widget Purpose
msg expression 入力データからの動的メッセージ コンテンツ。
channel text 送信先の Slack チャネル (例: #alerts)。
is_preview なし プレビュー時にオペレーターの動作を変えられるようにする、format: is_preview を含むブール型の設定プロパティ（この場合、Slack メッセージを実際には作成しないようにします）。

手順 3: Unity カタログ関数を作成する

SQL UDF を作成する場合、ほとんどの SQL クエリと比較して珍しいものがいくつかあります。

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

特徴 Purpose
http_request() 外部 API への HTTP 呼び出しを行います。
conn => 'my_slack_connection' 認証のために UC 接続を参照します。
to_json() および named_struct() Slack API の JSON ペイロードを構築します。
YAML コメント ブロック Lakeflow Designer によって演算子を作成するために使用されます。
CASE WHEN プレビュー モード ロジックを実装します。

手順 4: 関数をテストする

次に、関数をテストして、演算子として登録する前に関数が動作することを確認します。

Slack メッセージの送信を回避するために、最初にプレビュー モードでテストします。

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

外部 API 呼び出しを使用してテストします (Slack にメッセージが送信されます)。

-- 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 ファイルに演算子を追加します。

operators:
  - catalog: main
    schema: my_schema
    functionName: send_slack_msg

Note

このファイルをユーザー フォルダーに定義すると、そのファイルのみが表示されます。 詳細については、「 オペレーターを検出可能にする」を参照してください。

手順 6: アクセス許可を設定する

Unity カタログ接続を使用する SQL UDF の場合、ユーザーには追加のアクセス許可が必要です。

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

Important

USE CONNECTIONアクセス許可がないと、ユーザーは関数を実行できる場合でも API 呼び出しを行うことができなくなります。

Lakeflow Designer での演算子の使用

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

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

ユーザーは、データに基づいて通知を送信できます。たとえば、特定のしきい値を超えたときのアラートなどです。

一般的なユース ケース

  • アラート - データ品質の問題が検出されたときに通知を送信します。
  • 通知 - ワークフローが完了したときにチームに通知します。
  • Webhook — 外部 API を呼び出してダウンストリーム プロセスをトリガーします。
  • ログ記録 — 外部システムに監査メッセージを送信します。

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

  1. 常にプレビュー モードを使用する — is_previewでformat: is_preview構成プロパティを追加して、誤った API 呼び出しを防ぎます。
  2. Unity カタログ接続を使用する - UDF で資格情報をハードコーディングしないでください。 Unity カタログ接続は、SQL UDF でのみ使用できます。
  3. エラーを適切に処理 する — API 呼び出しが失敗する可能性があります。エラー時に何を返すべきかを検討してください。
  4. 十分にテスト する - 開発中はプレビュー モードを使用します。
  5. 接続のセットアップを文書化する - ユーザーは、作成する接続を知っている必要があります。
  • Last updated on