Tutorial: Enviar mensagem no Slack

info

Visualização

Este recurso está em Pré-visualização Pública.

Neste tutorial, você criará um operador UDF SQL para o LakeFlow Designer que publica mensagens no canal do Slack. As UDFs SQL são a escolha certa quando uma função precisa chamar APIs externas via HTTP. Para uma visão geral mais ampla, consulte Operadores definidos pelo usuário no LakeFlow Designer.

Visão geral

Este operador envia mensagens para o Slack usando:

• Função definida pelo usuário (UDF) em SQL : Escrita em SQL em vez de Python.
• Conexão HTTPUnity Catalog : Gerencie com segurança as credenciais API do Slack.
• Suporte ao modo de pré-visualização : Impede chamadas reais à API do Slack durante a pré-visualização do fluxo de trabalho.
• Parâmetros de expressão : Permite conteúdo de mensagem dinâmico a partir de colunas do DataFrame.

Por que usar UDF em SQL?

Para operadores que precisam chamar APIs externas (como Slack, endpoint REST , webhooks), é necessário usar UDFs SQL . As UDFs e UDTFs em Python não podem fazer requisições HTTP. As UDFs SQL têm acesso à função http_request() que funciona com conexões Unity Catalog .

Passo 1: Configurar a conexão HTTP Unity Catalog

Antes de criar a UDF, você precisa configurar uma conexão HTTP do Unity Catalog para armazenar com segurança suas credenciais da API do Slack. Substitua <xoxb-your-slack-bot-token> pelos seus tokens reais do Slack Bot. Você pode obter essa informação nas configurações do seu aplicativo Slack. Você pode usar essa mesma conexão em várias UDFs (Funções Definidas pelo Usuário). Para saber mais, consulte Conectar-se a um serviço HTTP externo.

SQL

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

o passo 2: Criar o operador YAML

Agora você criará o YAML para o operador. Para obter detalhes sobre o esquema, consulte a Referência YAML do operador definido pelo usuário.

O YAML para este operador inclui:

• Parâmetro de expressão (msg): Permite conteúdo de mensagem dinâmico de colunas do dataframe.
• parâmetro strings (channel): Nome/ID estático do canal.
• 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 impedir chamadas reais à API durante o teste.

YAML

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

Isso inclui:

Chave de configuração	Widget	Propósito
msg	expression	Conteúdo dinâmico da mensagem a partir de dados de entrada.
channel	text	Canal de folga para enviar (ex: #alerts).
is_preview	N/A	Uma propriedade de configuração booleana com o format: is_preview que permite ao operador se comportar de maneira diferente durante uma pré-visualização (neste caso, evitar a criação de uma mensagem no Slack).

o passo 3: Criar a função Unity Catalog

Ao criar UDFs em SQL, existem alguns aspectos que são incomuns em comparação com a maioria das consultas SQL:

• Use a sintaxe RETURN em vez de AS $$.
• Incorpore a configuração YAML em um bloco de comentário SQL (/* ... */).
• Pode-se usar a função http_request para chamadas de API.

SQL

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 o seguinte recurso:

Recurso	Propósito
http_request()	Faz chamadas HTTP para APIs externas.
conn => 'my_slack_connection'	Faz referência à conexão UC para autenticação.
to_json() e named_struct()	Constrói a carga útil JSON para a API do Slack.
Bloco de comentários YAML	Utilizado pelo LakeFlow Designer para criar o operador.
CASE WHEN	Implementa a lógica do modo de pré-visualização.

o passo 4: Teste a função

Em seguida, teste a função para garantir que ela funcione corretamente antes de registrá-la como um operador.

Faça o teste primeiro no modo de pré-visualização para evitar o envio de uma mensagem para o Slack:

SQL

-- 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 (enviará uma mensagem para o Slack):

SQL

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

o passo 5: registrar a operadora

Adicione o operador ao seu arquivo .user_defined_operators.yaml :

YAML

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

nota

Se você definir esse arquivo na sua pasta de usuário, ele aparecerá apenas para você. Para obter mais informações, consulte Torne seu operador detectável.

o passo 6: Configurar permissões

Para UDFs SQL que usam conexões do Unity Catalog, os usuários precisam de uma permissão adicional:

SQL

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

importante

Sem a permissão USE CONNECTION , os usuários não poderão fazer chamadas de API, mesmo que possam executar a função.

Utilizando o operador no LakeFlow Designer

Após o registro, o operador aparecerá no LakeFlow Designer com as seguintes características:

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

Os usuários podem enviar notificações com base em seus dados — por exemplo, alertas quando determinados limites forem excedidos.

Casos de uso comuns

• Alerta — Enviar notificações quando forem detectados problemas de qualidade de dados.
• Notificações — Notifique as equipes quando o fluxo de trabalho for concluído.
• Webhooks — Chamam APIs externas para acionar processos subsequentes.
• Registro de logs — Enviar mensagens de auditoria para sistemas externos.

Melhores práticas para a criação de operadores de chamada de API

1. Use 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 conexões Unity Catalog — Nunca codifique credenciais diretamente em sua UDF. As conexões do Unity Catalog estão disponíveis apenas em UDFs SQL.
3. Lide com erros de forma elegante — chamadas de API podem falhar; considere o que retornar em caso de erro.
4. Teste minuciosamente — Utilize o modo de pré-visualização durante o desenvolvimento.
5. Documente a configuração da conexão — Os usuários precisam saber qual conexão criar.