Tutorial: Enviar mensagem do Slack

Importante

Esse recurso está em Visualização Pública.

Neste tutorial, você criará um operador UDF do SQL para o Lakeflow Designer que posta mensagens nos canais do Slack. UDFs do SQL são a escolha certa quando uma função precisa chamar APIs externas por HTTP. Para obter uma visão geral mais ampla, consulte operadores definidos pelo usuário no Lakeflow Designer.

Visão geral

Esse operador envia mensagens para o Slack usando:

• SQL UDF: escrito em SQL em vez de Python.
• Conexão HTTP do Unity Catalog: gerencia com segurança as credenciais da API do Slack.
• Suporte ao modo de visualização: impede chamadas reais da API do Slack durante a visualização do fluxo de trabalho.
• Parâmetros de expressão: Permitem inserir conteúdo dinâmico em mensagens a partir de colunas do DataFrame.

Por que usar SQL UDF?

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

Etapa 1: Configurar a conexão HTTP do Catálogo do Unity

Antes de criar o UDF, você precisa configurar uma conexão HTTP do Catálogo do Unity para armazenar com segurança suas credenciais de API do Slack. Substitua <xoxb-your-slack-bot-token> pelo token de bot do Slack real. Você pode obter isso nas configurações do aplicativo Slack. Você pode usar essa mesma conexão em vários UDFs. Para saber mais, confira Conectar-se 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>'
);

Etapa 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 dinâmico de mensagens a partir de colunas do dataframe.
• Parâmetro de cadeia de caracteres (channel): nome/ID do canal estático.
• Modo de visualização (is_preview): uma propriedade de configuração com format: is_preview que permite o modo de visualização para impedir chamadas de API reais durante o teste.

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	Purpose
msg	expression	Conteúdo dinâmico da mensagem a partir de dados de entrada.
channel	text	Canal do Slack para o qual enviar (por exemplo, #alerts).
is_preview	n/a	Uma propriedade de configuração booleana com format: is_preview que permite que o operador se comporte de forma diferente durante uma pré-visualização (neste caso, evitar criar de fato uma mensagem no Slack).

Etapa 3: Criar a função catálogo do Unity

Ao criar UDFs do SQL, há algumas coisas incomuns em comparação com a maioria das consultas SQL:

• Use a sintaxe RETURN em vez de AS $$.
• Insira a configuração do YAML em um 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
);

Essa função SQL inclui os seguintes recursos:

Característica	Purpose
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 o conteúdo JSON para a API do Slack.
Bloco de comentários YAML	Usado pelo Lakeflow Designer para criar o operador.
CASE WHEN	Implementa a lógica do modo de visualização.

Etapa 4: Testar a função

Em seguida, teste a função para verificar se ela funciona antes de registrá-la como um operador.

Teste primeiro no modo de visualização para evitar o envio de uma mensagem do 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 a chamada à API externa (enviará uma mensagem ao 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

Etapa 5: Registrar o operador

Adicione o operador ao seu .user_defined_operators.yaml arquivo:

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

Note

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

Etapa 6: Configurar permissões

Para UDFs SQL que usam conexões do Unity Catalog, os usuários 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>`;

Importante

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

Usando o operador no Lakeflow Designer

Depois de registrado, o operador aparecerá no Lakeflow Designer com:

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

Os usuários podem enviar notificações com base em seus dados , por exemplo, alertando quando determinados limites são excedidos.

Casos de uso comuns

• Alertas – Enviar notificações quando forem detectados problemas de qualidade de dados.
• Notificações – Notifique as equipes quando os fluxos de trabalho forem concluídos.
• Webhooks — chame APIs externas para disparar processos downstream.
• Registro — Enviar mensagens de auditoria para sistemas externos.

Práticas recomendadas para a criação de operadores de chamada de API

1. Sempre use o modo de pré-visualização — Adicione uma propriedade de configuração is_preview com format: is_preview para evitar chamadas acidentais de API.
2. Usar conexões do Catálogo do Unity – Nunca codificar credenciais em seu UDF. As conexões do Catálogo do Unity só estão disponíveis em UDFs do SQL.
3. Trate os erros adequadamente — as chamadas de API podem falhar; considere o que retornar em caso de erro.
4. Teste minuciosamente – use o modo de visualização durante o desenvolvimento.
5. Documente a configuração da conexão – os usuários precisam saber qual conexão criar.