Tutorial: Enviar mensagem no Slack

Neste tutorial, cria um operador SQL UDF para o Lakeflow Designer que publica mensagens nos canais do Slack. Os UDFs SQL são a escolha certa quando uma função precisa de chamar APIs externas via HTTP. Para uma visão geral mais ampla, veja Operadores definidos pelo utilizador no Lakeflow Designer.

Overview

Este operador envia mensagens para o Slack utilizando:

• SQL UDF: Escrito em SQL em vez de Python.
• Ligação HTTP do Unity Catalog: Gerir de forma segura as credenciais da API do Slack.
• Suporte ao modo de pré-visualização: Previne chamadas reais da API do Slack durante a pré-visualização do fluxo de trabalho.
• Parâmetros de expressão: Permite conteúdo dinâmico de mensagens a partir de colunas DataFrame.

Por que usar um UDF SQL

Para os operadores que precisem de chamar APIs externas (como Slack, endpoints REST, webhooks), devem usar UDFs SQL. UDFs e UDTFs em Python não conseguem fazer pedidos HTTP. As UDFs SQL têm acesso à função http_request(), que funciona com ligações do Unity Catalog.

Passo 1: Configurar a ligação HTTP do Unity Catalog

Antes de criar o UDF, precisa de configurar uma ligação HTTP ao Unity Catalog para armazenar de forma segura as credenciais da API do Slack. Substitui <xoxb-your-slack-bot-token> pelo teu token real do Slack Bot. Podes obter isto nas definições da aplicação Slack. Pode usar esta mesma ligação através de vários UDFs. Para saber mais, consulte Ligar a serviços 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>'
);

Passo 2: Criar o operador YAML

Agora, crie o YAML para o operador. Para detalhes sobre o esquema, veja Referência YAML do operador definido pelo utilizador.

O YAML deste operador inclui:

• Parâmetro de expressão (msg): Permite conteúdo dinâmico de mensagens a partir de colunas de dataframe.
• Parâmetro da cadeia (channel): Nome/ID do canal estático.
• Modo de pré-visualização (is_preview): Uma propriedade de configuração com format: is_preview que ativa o modo de pré-visualização para evitar chamadas reais à API durante os testes.

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

Isto inclui:

Passo 3: Criar a função Unity Catalog

Ao criar UDFs SQL, há algumas coisas que são incomuns comparadas com a maioria das consultas SQL:

• Utilize a sintaxe RETURN em vez de AS $$.
• Incorpore a configuração YAML num bloco de comentários SQL (/* ... */).
• Pode usar a http_request função para chamadas 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 função SQL inclui as seguintes funcionalidades:

Passo 4: Testar a função

Em seguida, teste a função para se certificar de que funciona antes de a registar como operador.

Teste primeiro em modo de pré-visualização, para evitar enviar uma mensagem no 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"

Teste com chamada de API externa (envia uma mensagem para o 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

Passo 5: Registar o operador

Adicione o operador ao seu .user_defined_operators.yaml ficheiro:

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

Passo 6: Configurar permissões

Para UDFs SQL que utilizam ligações ao Unity Catalog, os utilizadores precisam de uma permissão 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>`;

Utilize o operador no Lakeflow Designer

Depois de registado, o operador aparece no Lakeflow Designer com:

• Uma porta de entrada para ligar a sua fonte de dados.
• Um seletor de expressões para selecionar qual coluna contém o conteúdo da mensagem.
• Uma entrada de texto para o canal do Slack.

Os utilizadores podem enviar notificações com base nos seus dados. Por exemplo, alertar quando certos limiares são ultrapassados.

Casos de uso comuns

• Alertas: Envie notificações quando forem detetados problemas de qualidade dos dados.
• Notificações: Notifique as equipas quando os fluxos de trabalho terminarem.
• Webhooks: Permitem chamar APIs externas para acionar processos subsequentes.
• Registo: Envio de mensagens de auditoria para sistemas externos.

Boas práticas para construir operadores de chamada API

1. Utilize sempre o modo de pré-visualização: Adicione uma propriedade de configuração is_preview com format: is_preview para evitar chamadas acidentais à API.
2. Use ligações ao Unity Catalog: Nunca codifique credenciais fixas no seu UDF. As ligações do Catálogo Unity só estão disponíveis em UDFs SQL.
3. Lidar com erros com elegância: as chamadas de API podem falhar; Considere o que devolver em caso de erro.
4. Teste cuidadosamente: Use o modo de pré-visualização durante o desenvolvimento.
5. Documente a configuração da ligação: Os utilizadores precisam de saber que ligação criar.