Руководство по отправке сообщения Slack

Important

Эта функция доступна в общедоступной предварительной версии.

В этом руководстве вы создадите оператор SQL UDF для Конструктора Lakeflow, который публикует сообщения в каналы Slack. Пользовательские функции SQL лучше всего подходят, когда функции нужно вызывать внешние API по HTTP. Более широкий обзор см. в разделе "Определяемые пользователем операторы" в конструкторе Lakeflow.

Overview

Этот оператор отправляет сообщения в Slack с помощью:

  • SQL UDF: записано в SQL, а не Python.
  • HTTP-подключение Unity Catalog: обеспечивает безопасное управление учетными данными API Slack.
  • Поддержка режима предварительной версии: предотвращает фактические вызовы API Slack во время предварительной версии рабочего процесса.
  • Параметры выражений: позволяют динамически формировать содержимое сообщения на основе столбцов DataFrame.

Почему UDF SQL?

Для операторов, которым нужно вызывать внешние API (например, Slack, REST-конечные точки или вебхуки), необходимо использовать пользовательские функции SQL (UDF). Python UDFs и UDTFs не могут выполнять HTTP-запросы. Пользовательские функции SQL имеют доступ к функции http_request(), которая работает с подключениями Unity Catalog.

Шаг 1. Настройка HTTP-подключения каталога Unity

Перед созданием UDF необходимо настроить HTTP-подключение каталога Unity для безопасного хранения учетных данных API Slack. Замените <xoxb-your-slack-bot-token> на ваш реальный токен Slack Bot. Это можно получить из параметров приложения Slack. Одно и то же подключение можно использовать в нескольких пользовательских функциях. Дополнительные сведения см. в статье "Подключение к внешним службам 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): позволяет динамически формировать содержимое сообщения из столбцов DataFrame.
  • Строковый параметр (channel): имя или идентификатор статического канала.
  • Режим предварительного просмотра (is_preview): свойство конфигурации с format: is_preview, которое включает режим предварительного просмотра, чтобы предотвратить реальные вызовы API во время тестирования.
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-запросов:

  • RETURN Используйте синтаксис вместо AS $$.
  • Внедрение конфигурации YAML в блок комментариев SQL (/* ... */).
  • Может использовать функцию http_request для вызовов 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
);

Эта функция SQL включает следующие функции:

Функция Purpose
http_request() Выполняет вызовы HTTP к внешним API.
conn => 'my_slack_connection' Ссылается на подключение UC для проверки подлинности.
to_json() и named_struct(). Создает полезные данные JSON для API Slack.
Блок комментариев YAML Используется конструктором Lakeflow для создания оператора.
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. Настройка разрешений

Для пользовательских функций SQL, использующих подключения Unity Catalog, пользователям требуется дополнительное разрешение:

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

После регистрации оператор появится в Конструкторе Lakeflow со следующими параметрами:

  • Входной порт для подключения источника данных.
  • Средство выбора выражений для выбора столбца, содержащего содержимое сообщения.
  • Текстовое поле ввода для канала Slack.

Пользователи могут отправлять уведомления на основе своих данных, например оповещение о превышении определенных пороговых значений.

Распространенные варианты использования

  • Оповещения — отправка уведомлений при обнаружении проблем с качеством данных.
  • Уведомления — уведомлять команды о завершении рабочих процессов.
  • Вебхуки — вызов внешних API для запуска последующих процессов.
  • Ведение журнала — отправка сообщений аудита во внешние системы.

Рекомендации по созданию операторов вызовов API

  1. Всегда используйте режим предпросмотра — добавьте свойство конфигурации is_preview со значением format: is_preview, чтобы предотвратить случайные вызовы API.
  2. Используйте подключения Unity Catalog — никогда не прописывайте учетные данные в коде UDF. Подключения каталога Unity доступны только в пользовательских файлах SQL.
  3. Корректно обрабатывайте ошибки — API-вызовы могут завершиться ошибкой; подумайте, что возвращать в случае ошибки.
  4. Тщательно протестируйте — используйте режим предварительной версии во время разработки.
  5. Задокументируйте настройку подключения . Пользователи должны знать, какое соединение необходимо создать.
  • Last updated on