Tutorial: Mengirim pesan Slack

Dalam tutorial ini, Anda membuat operator UDF SQL untuk Lakeflow Designer yang memposting pesan ke saluran Slack. UDF SQL adalah pilihan yang tepat ketika fungsi perlu memanggil API eksternal melalui HTTP. Untuk gambaran umum yang lebih luas, lihat Operator yang ditentukan pengguna di Lakeflow Designer.

Ikhtisar

Operator ini mengirim pesan ke Slack menggunakan:

  • SQL UDF: Ditulis dalam SQL daripada Python.
  • Koneksi HTTP Katalog Unity: Mengelola kredensial Slack API dengan aman.
  • Dukungan mode pratinjau: Mencegah panggilan API Slack aktual selama pratinjau alur kerja.
  • Parameter ekspresi: Memungkinkan konten pesan dinamis dari kolom DataFrame.

Mengapa menggunakan SQL UDF

Untuk operator yang perlu memanggil API eksternal (seperti Slack, titik akhir REST, webhook), Anda harus menggunakan UDF SQL. Python UDF dan UDTF tidak dapat membuat permintaan HTTP. SQL UDF memiliki akses ke fungsi http_request() yang berfungsi dengan koneksi Unity Catalog.

Langkah 1: Siapkan koneksi HTTP Katalog Unity

Sebelum membuat UDF, Anda perlu menyiapkan koneksi HTTP Unity Catalog untuk menyimpan kredensial API Slack Anda dengan aman. Ganti <xoxb-your-slack-bot-token> dengan Token Bot Slack Anda yang sebenarnya. Anda bisa mendapatkan ini dari pengaturan aplikasi Slack Anda. Anda dapat menggunakan koneksi yang sama ini di beberapa UDF. Untuk mempelajari selengkapnya, lihat Menyambungkan ke layanan HTTP eksternal.

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

Langkah 2: Membuat YAML operator

Sekarang, buat YAML untuk operator. Untuk detail tentang skema, lihat Referensi YAML operator yang ditentukan pengguna.

YAML untuk operator ini meliputi:

  • Parameter ekspresi (msg): Memungkinkan konten pesan dinamis dari kolom dataframe.
  • Parameter string (channel): Nama/ID saluran statis.
  • Mode pratinjau (is_preview): Properti konfigurasi dengan format: is_preview yang memungkinkan mode pratinjau untuk mencegah panggilan API aktual selama pengujian.
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

Hal ini mencakup:

Kunci Konfigurasi Widget Kegunaan
msg expression Konten pesan dinamis dari data masukan.
channel input Saluran Slack tujuan pengiriman (misalnya, #alerts).
is_preview n/a Properti konfigurasi boolean dengan format: is_preview yang memungkinkan operator berperilaku berbeda selama pratinjau (dalam hal ini, hindari benar-benar membuat pesan Slack).

Langkah 3: Membuat fungsi Katalog Unity

Saat membuat UDF SQL, ada beberapa hal yang jarang dibandingkan dengan sebagian besar kueri SQL:

  • Gunakan sintaks RETURN alih-alih AS $$.
  • Sematkan konfigurasi YAML di blok komentar SQL (/* ... */).
  • Dapat menggunakan http_request fungsi untuk panggilan API.
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
);

Fungsi SQL ini mencakup fitur-fitur berikut:

Feature Kegunaan
http_request() Melakukan panggilan HTTP ke API eksternal.
conn => 'my_slack_connection' Mereferensikan koneksi UC untuk autentikasi.
to_json() dan named_struct() Membuat payload JSON untuk API Slack.
Blok komentar YAML Digunakan oleh Lakeflow Designer untuk membuat operator.
CASE WHEN Menerapkan logika mode pratinjau.

Langkah 4: Uji fungsi

Selanjutnya, uji fungsi untuk memastikan fungsi berfungsi sebelum mendaftarkannya sebagai operator.

Uji dalam mode pratinjau terlebih dahulu, untuk menghindari pengiriman pesan 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"

Uji dengan panggilan API eksternal (mengirim pesan ke 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

Langkah 5: Daftarkan operator

Tambahkan operator ke file .user_defined_operators.yaml Anda:

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

Note

Jika Anda menentukan file ini di folder pengguna Anda, file tersebut hanya muncul untuk Anda. Untuk informasi selengkapnya, lihat Membuat operator Anda dapat ditemukan.

Langkah 6: Menyiapkan izin

Untuk UDF SQL yang menggunakan koneksi Katalog Unity, pengguna memerlukan izin tambahan:

-- 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 Tanpa izin, pengguna tidak akan dapat melakukan panggilan API bahkan jika mereka dapat menjalankan fungsi.

Menggunakan operator di Lakeflow Designer

Setelah terdaftar, operator muncul di Lakeflow Designer dengan:

  • Port input untuk menyambungkan sumber data Anda.
  • Pemilih ekspresi untuk memilih kolom mana yang berisi konten pesan.
  • Input teks untuk saluran Slack.

Pengguna dapat mengirim pemberitahuan berdasarkan data mereka. Misalnya, memperingatkan ketika ambang batas tertentu terlampaui.

Kasus penggunaan umum

  • Pemberitahuan: Kirim pemberitahuan saat masalah kualitas data terdeteksi.
  • Pemberitahuan: Memberi tahu tim saat alur kerja selesai.
  • Webhook: Panggil API eksternal untuk memicu proses hilir.
  • Pencatatan log: Kirim pesan audit ke sistem eksternal.

Praktik terbaik untuk membangun operator panggilan API

  1. Selalu gunakan mode pratinjau: Tambahkan is_preview properti konfigurasi dengan format: is_preview untuk mencegah panggilan API yang tidak disengaja.
  2. Gunakan koneksi Katalog Unity: Jangan pernah mengodekan kredensial hardcode di UDF Anda. Koneksi Unity Catalog hanya tersedia di SQL UDF.
  3. Tangani error dengan baik: Panggilan API dapat gagal; pertimbangkan apa yang harus dikembalikan jika terjadi error.
  4. Uji secara menyeluruh: Gunakan mode pratinjau selama pengembangan.
  5. Dokumentasikan penyiapan koneksi: Pengguna perlu mengetahui koneksi apa yang akan dibuat.
  • Last updated on