Tutorial: Envío de mensajes de Slack

Important

Esta característica está en versión preliminar pública.

En este tutorial, creará un operador UDF de SQL para Lakeflow Designer que publica mensajes en canales de Slack. Las UDF de SQL son la opción correcta cuando una función necesita llamar a api externas a través de HTTP. Para obtener información general más amplia, consulte Operadores definidos por el usuario en Lakeflow Designer.

Información general

Este operador envía mensajes a Slack mediante:

  • SQL UDF: escrito en SQL en lugar de Python.
  • Conexión HTTP del catálogo de Unity: administra de forma segura las credenciales de la API de Slack.
  • Compatibilidad con el modo de vista previa: impide las llamadas reales de la API de Slack durante la versión preliminar del flujo de trabajo.
  • Parámetros de expresión: permite el contenido dinámico del mensaje de las columnas DataFrame.

¿Por qué SQL UDF?

Para los operadores que necesiten llamar a APIs externas (como Slack, extremos REST o webhooks), deben usar UDF de SQL. Las UDF y las UDTF de Python no pueden hacer solicitudes HTTP. Las UDF de SQL tienen acceso a la función http_request(), que funciona con las conexiones de Unity Catalog.

Paso 1: Configurar la conexión HTTP del catálogo de Unity

Antes de crear la UDF, debe configurar una conexión HTTP del catálogo de Unity para almacenar de forma segura las credenciales de la API de Slack. Reemplace <xoxb-your-slack-bot-token> por el token real de su bot de Slack. Puede obtener esto en la configuración de la aplicación slack. Puede usar esta misma conexión en múltiples UDF. Para más información, consulte Conexión a servicios HTTP externos.

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

Paso 2: Creación del operador YAML

Ahora creará el código YAML para el operador . Para obtener más información sobre el esquema, consulte Referencia de YAML del operador definido por el usuario.

YaML para este operador incluye:

  • Parámetro de expresión (msg): permite el contenido dinámico de mensajes de columnas de trama de datos.
  • Parámetro de cadena (channel): nombre o identificador del canal estático.
  • Modo de vista previa (is_preview): propiedad config con format: is_preview que permite el modo de vista previa evitar llamadas API reales durante las pruebas.
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

Esto incluye lo siguiente:

Clave de configuración Widget propósito
msg expression Contenido dinámico del mensaje a partir de los datos de entrada.
channel text Canal de Slack al que se va a enviar (por ejemplo, #alerts).
is_preview n/a Una propiedad de configuración booleana con format: is_preview que permite al operador comportarse de forma diferente durante una versión preliminar (en este caso, evite realmente crear un mensaje de Slack).

Paso 3: Crear la función catálogo de Unity

Al crear UDF de SQL, hay algunas cosas que son poco frecuentes en comparación con la mayoría de las consultas SQL:

  • Use la RETURN sintaxis en lugar de AS $$.
  • Inserte la configuración de YAML en un bloque de comentarios de SQL (/* ... */).
  • Puede usar la http_request función para las llamadas 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
);

Esta función SQL incluye las siguientes características:

Feature propósito
http_request() Realiza llamadas HTTP a api externas.
conn => 'my_slack_connection' Hace referencia a la conexión UC para la autenticación.
to_json() y named_struct() Construye la carga JSON para la API de Slack.
Bloque de comentarios de YAML Lo usa Lakeflow Designer para crear el operador .
CASE WHEN Implementa la lógica del modo de vista previa.

Paso 4: Probar la función

A continuación, pruebe la función para asegurarse de que funciona antes de registrarla como operador.

Pruebe primero en modo de vista previa para evitar enviar un mensaje de 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"

Pruebe con una llamada API externa (enviará un mensaje a 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

Paso 5: Registrar el operador

Añada el operador a su archivo .user_defined_operators.yaml:

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

Note

Si define este archivo en la carpeta de usuario, solo aparece para usted. Para obtener más información, consulte Hacer que el operador sea reconocible.

Paso 6: Configuración de permisos

Para las UDF de SQL que usan conexiones de Catálogo de Unity, los usuarios necesitan un permiso adicional:

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

Sin el USE CONNECTION permiso, los usuarios no podrán realizar llamadas API aunque puedan ejecutar la función.

Usar el operador en Lakeflow Designer

Una vez registrado, el operador aparecerá en Lakeflow Designer con:

  • Un puerto de entrada para conectar el origen de datos.
  • Selector de expresiones para seleccionar qué columna contiene el contenido del mensaje.
  • Entrada de texto para el canal de Slack.

Los usuarios pueden enviar notificaciones en función de sus datos, por ejemplo, alertando cuando se superan determinados umbrales.

Casos de uso comunes

  • Alertas : envíe notificaciones cuando se detecten problemas de calidad de datos.
  • Notificaciones : notifique a los equipos cuando se completen los flujos de trabajo.
  • Webhooks — Llamar a API externas para activar procesos posteriores.
  • Registro : enviar mensajes de auditoría a sistemas externos.

Procedimientos recomendados para compilar operadores de llamadas API

  1. Usar siempre el modo de vista previa : agregue una is_preview propiedad config con format: is_preview para evitar llamadas API accidentales.
  2. Usar conexiones de Unity Catalog — Nunca codificar las credenciales directamente en la UDF. Las conexiones del catálogo de Unity solo están disponibles en UDF de SQL.
  3. Gestione los errores de forma adecuada — las llamadas a la API pueden fallar; considere qué devolver en caso de error.
  4. Prueba exhaustiva: use el modo de vista previa durante el desarrollo.
  5. Documente la configuración de la conexión : los usuarios deben saber qué conexión crear.
  • Last updated on