자습서: Slack 메시지 보내기

Important

이 기능은 공개 미리보기 단계에 있습니다.

이 자습서에서는 Slack 채널에 메시지를 게시하는 Lakeflow Designer용 SQL UDF 연산자를 만듭니다. 함수가 HTTP를 통해 외부 API를 호출해야 하는 경우 SQL UDF는 올바른 선택입니다. 자세한 개요는 Lakeflow Designer의 사용자 정의 연산자를 참조하세요.

Overview

이 연산자는 다음을 사용하여 Slack에 메시지를 보냅니다.

  • SQL UDF: Python 대신 SQL로 작성되었습니다.
  • Unity 카탈로그 HTTP 연결: Slack API 자격 증명을 안전하게 관리합니다.
  • 미리 보기 모드 지원: 워크플로 미리 보기 중에 실제 Slack API 호출을 방지합니다.
  • 식 매개 변수: DataFrame 열의 동적 메시지 콘텐츠를 허용합니다.

SQL UDF를 왜 사용합니까?

외부 API(예: Slack, REST 엔드포인트, 웹후크)를 호출해야 하는 연산자는 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 n/a 미리보기 중에 연산자가 다르게 동작할 수 있도록 하는 format: is_preview가 있는 불리언 구성 속성입니다(이 경우 실제로 Slack 메시지를 생성하지 않도록 함).

3단계: Unity 카탈로그 함수 만들기

SQL UDF를 만들 때 대부분의 SQL 쿼리에 비해 일반적이지 않은 몇 가지 사항이 있습니다.

  • AS $$ 대신에 RETURN 구문을 사용합니다.
  • 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

메모

사용자 폴더에 이 파일을 정의하면 본인에게만 표시됩니다. 자세한 내용은 오퍼레이터를 검색 가능하게 만들기를 참조하세요.

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 채널에 대한 텍스트 입력입니다.

사용자는 데이터를 기반으로 알림을 보낼 수 있습니다(예: 특정 임계값을 초과하는 경우 경고).

일반적인 사용 사례

  • 경고 - 데이터 품질 문제가 감지되면 알림을 보냅니다.
  • 알림 - 워크플로가 완료되면 팀에게 알립니다.
  • 웹후크 - 외부 API를 호출하여 다운스트림 프로세스를 트리거합니다.
  • 로깅 - 외부 시스템에 감사 메시지를 보냅니다.

API 호출 연산자를 빌드하기 위한 모범 사례

  1. 항상 미리 보기 모드 사용 - 실수로 인한 API 호출을 방지하기 위해 구성 속성을 is_preview 추가 format: is_preview 합니다.
  2. Unity 카탈로그 연결 사용 - UDF에서 자격 증명을 하드 코딩하지 마세요. Unity 카탈로그 연결은 SQL UDF에서만 사용할 수 있습니다.
  3. 오류를 정상적으로 처리합니다. API 호출이 실패할 수 있습니다. 오류 발생시 반환할 내용을 고려합니다.
  4. 철저히 테스트 - 개발 중에 미리 보기 모드를 사용합니다.
  5. 연결 설정 문서화 - 사용자가 만들 연결을 알아야 합니다.
  • Last updated on