Tutorial: Envío de mensajes de Slack

En este tutorial, creará un operador UDF de SQL para Lakeflow Designer que publica mensajes en canales de Slack. 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é usar una UDF de SQL

Los UDF SQL pueden llamar a APIs externas (como Slack, endpoints REST y webhooks) con la http_request() función, que se autentica mediante una conexión HTTP del Catálogo de Unity. La conexión almacena las credenciales, para que no aparezcan en el código de función. Para llamar a una API desde Python, utiliza un operador python-run-function. Consulta el tutorial: Operador de remitente de correo electrónico de Gmail.

Requirements

• Acceso a Lakeflow Designer en un espacio de trabajo habilitado con Unity Catalog. Consulte Requisitos previos.
• USE CATALOG en el main catálogo, y CREATE SCHEMA en main, o USE SCHEMA y CREATE FUNCTION en un esquema existente main.example_output . Para usar un catálogo o esquema diferente, reemplaza main.example_output en todas partes. Consulte Referencia de privilegios del catálogo de Unity.
• CREATE CONNECTION en el metastore del Catálogo de Unity, para crear la conexión HTTP. Consulte Conexión a servicios HTTP externos.
• Una app de Slack con un token de bot que le permite publicar en tu canal.

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 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, crea el 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
      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

Esto incluye lo siguiente:

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.

El ejemplo crea la función en main.example_output. Crea el esquema primero si no existe:

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

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

Paso 4: Probar la función

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

Prueba primero en modo vista previa para que no se envíe ningún mensaje. Devuelve 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;

Prueba con una llamada real a la API para enviar un mensaje a Slack. Usa esto con precaución: publica en el canal y devuelve el JSON de respuesta de la API de Slack.

SELECT main.example_output.send_slack_msg(
  msg => 'Hello from Lakeflow Designer!',
  channel => '#test-channel',
  is_preview => false
) AS result;

Paso 5: Registrar el operador

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

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

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:

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

Paso 7: Utiliza el operador en Lakeflow Designer

1. En una preparación visual de datos, abre el menú Operators en el panel izquierdo y busca el operador Send Slack Message.
2. Arrastra al operador sobre el lienzo y conecta una entrada a él.
3. Haz doble clic en el operador para abrir su panel de configuración y luego establece sus campos.
4. Selecciona el operador para previsualizar sus resultados en el panel de salida.

El operador tiene:

• 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, las alertas cuando se superan determinados umbrales.

Consejos y mejores prácticas

Utiliza los siguientes ejemplos y directrices cuando construyas operadores que llamen a APIs externas.

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. Use las conexiones de Unity Catalog: Nunca codifique las credenciales de forma fija en su UDF. Guárdalos en una conexión HTTP de Unity Catalog y úsala con http_request().
3. Gestionar los errores adecuadamente: 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.

Recursos adicionales

• Operadores definidos por el usuario en Lakeflow Designer
• Escribir la lógica para operadores personalizados de Lakeflow Designer
• Referencia de YAML del operador definido por el usuario