이 자습서에서는 Slack 채널에 메시지를 게시하는 Lakeflow Designer용 SQL UDF 연산자를 만듭니다. 더 넓은 개요는 Lakeflow Designer의 커스텀 오퍼레이터를 참조하세요.
Overview
이 연산자는 다음을 사용하여 Slack에 메시지를 보냅니다.
- SQL UDF: Python 대신 SQL로 작성되었습니다.
- Unity 카탈로그 HTTP 연결: Slack API 자격 증명을 안전하게 관리합니다.
- 미리 보기 모드 지원: 워크플로 미리 보기 중에 실제 Slack API 호출을 방지합니다.
- 식 매개 변수: DataFrame 열의 동적 메시지 콘텐츠를 허용합니다.
SQL UDF를 사용하는 이유
SQL UDF는 http_request() 함수로 외부 API(예: Slack, REST 엔드포인트, 웹훅)를 호출할 수 있으며, Unity 카탈로그 HTTP 연결을 통해 인증됩니다. 연결은 자격 증명을 저장하기 때문에 함수 코드에 포함되지 않습니다. 대신 Python에서 API를 호출하려면 python-run-function 연산자를 사용하세요.
튜토리얼: Gmail 이메일 발신자 연산자 참조.
Requirements
- Unity 카탈로그 지원 작업 공간에서 Lakeflow Designer에 대한 액세스 필수 조건을 참조하세요.
-
USE CATALOGmain카탈로그에서, 그리고main에서CREATE SCHEMA, 또는 기존main.example_output스키마에서USE SCHEMA및CREATE FUNCTION. 다른 카탈로그나 스키마를 사용하려면main.example_output를 문서 전체에서 교체하세요. Unity 카탈로그 권한 참조를 참조하세요. -
CREATE CONNECTIONUnity 카탈로그 메타스토어에서 HTTP 연결을 생성하기 위해 외부 HTTP 서비스에 대한 연결을 참조하세요. - 봇 토큰이 있는 슬랙 앱으로, 채널에 게시할 수 있습니다.
1단계: Unity 카탈로그 HTTP 연결 설정
UDF를 만들기 전에 Slack API 자격 증명을 안전하게 저장하기 위해 Unity 카탈로그 HTTP 연결을 설정해야 합니다.
<xoxb-your-slack-bot-token>를 실제 Slack 봇 토큰으로 바꾸세요. 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을 만듭니다. 스키마에 대한 자세한 내용은 Custom Operator YAML 참고 자료를 참조하세요.
이 연산자의 YAML에는 다음이 포함됩니다.
-
식 매개 변수 (
msg): 데이터 프레임 열의 동적 메시지 콘텐츠를 허용합니다. -
문자열 매개 변수 (
channel): 정적 채널 이름/ID입니다. -
미리 보기 모드 (
is_preview): 테스트 중에 실제 API 호출을 방지하기 위해 미리 보기 모드를 사용할 수 있는 구성 속성format: is_preview입니다.
schema: custom-operator-v0.2.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
여기에는 다음이 포함됩니다.
| 구성 키 | Widget | Purpose |
|---|---|---|
msg |
expression |
입력 데이터의 동적 메시지 콘텐츠입니다. |
channel |
input |
전송할 Slack 채널(예: #alerts) |
is_preview |
n/a |
format: is_preview가 포함된 부울 구성 속성으로, 미리보기 시 연산자가 다르게 동작할 수 있도록 합니다(이 경우 실제로 Slack 메시지를 생성하지 않도록). |
3단계: Unity 카탈로그 함수 만들기
SQL UDF를 만들 때 대부분의 SQL 쿼리에 비해 일반적이지 않은 몇 가지 사항이 있습니다.
-
RETURN대신에AS $$구문을 사용합니다. - SQL 주석 블록(
/* ... */)에 YAML 구성을 포함합니다. - 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.2.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 함수에는 다음 기능이 포함됩니다.
| 특징 | Purpose |
|---|---|
http_request() |
외부 API에 대한 HTTP 호출을 만듭니다. |
conn => 'my_slack_connection' |
인증을 위해 UC 연결을 참조합니다. |
to_json() 및 named_struct() |
Slack API에 대한 JSON 페이로드를 생성합니다. |
| YAML 주석 블록 | Lakeflow Designer에서 연산자를 만드는 데 사용됩니다. |
CASE WHEN |
미리 보기 모드 논리를 구현합니다. |
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 카탈로그 연결을 사용하는 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>`;
Important
USE CONNECTION 권한이 없으면 사용자가 함수를 실행할 수 있더라도 API 호출을 수행할 수 없습니다.
7단계: Lakeflow Designer에서 연산자 사용
- 시각적 데이터 준비 시 왼쪽 패널의 Operators 메뉴를 열고 Send Slack Message 연산자를 찾으세요.
- 오퍼레이터를 캔버스에 드래그해서 오퍼레이터에 입력을 연결하세요.
- 연산자를 더블 클릭하면 구성 패널이 열리고, 필드를 설정하세요.
- 출력 창에서 결과를 미리 보려면 연산자를 선택하세요.
운영자에게는 다음이 있습니다:
- 데이터 원본을 연결할 입력 포트입니다.
- 메시지 내용이 포함된 열을 선택하는 표현식 선택기입니다.
- Slack 채널에 대한 텍스트 입력입니다.
사용자는 자신의 데이터에 따라 알림을 보낼 수 있습니다. 예를 들어 특정 임계값을 초과하는 경우 경고합니다.
팁과 모범 사례
외부 API를 호출하는 연산자를 만들 때 다음 예시와 지침을 참고하세요.
일반적인 사용 사례
- 경고: 데이터 품질 문제가 감지되면 알림을 보냅니다.
- 알림: 워크플로가 완료되면 팀에 알립니다.
- 웹후크: 외부 API를 호출하여 다운스트림 프로세스를 트리거합니다.
- 로깅: 외부 시스템에 감사 메시지를 보냅니다.
API 호출 연산자를 빌드하기 위한 모범 사례
-
항상 미리 보기 모드 사용: 실수로 인한 API 호출을 방지하기 위해 구성 속성을
is_preview추가format: is_preview합니다. -
Unity 카탈로그 연결 사용: UDF에서 자격 증명을 하드 코딩하지 마세요. Unity 카탈로그 HTTP 연결에 저장하고
http_request()로 호출합니다. - 오류를 정상적으로 처리합니다. API 호출이 실패할 수 있습니다. 오류 발생시 반환할 내용을 고려합니다.
- 철저히 테스트: 개발 중에 미리 보기 모드를 사용합니다.
- 연결 설정 문서화: 사용자가 만들려는 연결을 알아야 합니다.