Esercitazione: Inviare un messaggio Slack

In questa esercitazione viene creato un operatore UDF SQL per Lakeflow Designer che invia messaggi ai canali Slack. Le UDF SQL sono la scelta giusta quando una funzione deve chiamare API esterne tramite HTTP. Per una panoramica più ampia, vedere Operatori definiti dall'utente in Lakeflow Designer.

Informazioni generali

Questo operatore invia messaggi a Slack usando:

• SQL UDF: scritto in SQL anziché in Python.
• Connessione HTTP del catalogo Unity: gestisce in modo sicuro le credenziali dell'API Slack.
• Supporto della modalità di anteprima: impedisce le chiamate EFFETTIVe dell'API Slack durante l'anteprima del flusso di lavoro.
• Parametri di espressione: consente il contenuto dinamico dei messaggi dalle colonne del dataframe.

Perché UDF SQL?

Per gli operatori che devono effettuare chiamate a API esterne (ad esempio Slack, endpoint REST, webhook), è necessario utilizzare UDF SQL. Le UDF e le UDTF di Python non possono effettuare richieste HTTP. Le UDF SQL hanno accesso alla funzione http_request(), che funziona con le connessioni di Unity Catalog.

Passaggio 1: Configurare la connessione HTTP del catalogo Unity

Prima di creare l'UDF, devi configurare una connessione HTTP in Unity Catalog per archiviare in modo sicuro le credenziali dell'API di Slack. Sostituire <xoxb-your-slack-bot-token> con il token del bot Slack effettivo. È possibile ottenerlo dalle impostazioni dell'app Slack. È possibile usare questa stessa connessione in più funzioni definite dall'utente. Per altre informazioni, vedere Connettersi a servizi HTTP esterni.

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

Passaggio 2: Creare l'operatore YAML

A questo scopo, si creerà il file YAML per l'operatore . Per i dettagli sullo schema, vedi Riferimento YAML per l'operatore definito dall'utente.

YAML per questo operatore include:

• Parametro di espressione (msg): consente il contenuto dinamico dei messaggi dalle colonne del dataframe.
• Parametro di tipo stringa (channel): nome/ID del canale statico.
• Modalità di anteprima (is_preview): proprietà config con format: is_preview che consente la modalità di anteprima per impedire le chiamate API effettive durante i test.

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

Sono inclusi:

Passaggio 3: Creare la funzione Catalogo Unity

Quando si creano UDF SQL, ci sono alcune particolarità rispetto alla maggior parte delle query SQL:

• Usare la RETURN sintassi anziché AS $$.
• Incorporare la configurazione YAML in un blocco di commenti SQL (/* ... */).
• Può usare la http_request funzione per le chiamate 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
);

Questa funzione SQL include le funzionalità seguenti:

Passaggio 4: Testare la funzione

Testare quindi la funzione per assicurarsi che funzioni prima di registrarla come operatore.

Eseguire prima il test in modalità di anteprima per evitare di inviare un messaggio 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"

Eseguire il test con una chiamata ALL'API esterna (invierà un messaggio 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

Passaggio 5: Registrare l'operatore

Aggiungi l'operatore nel file .user_defined_operators.yaml:

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

Passaggio 6: Configurare le autorizzazioni

Per le funzioni SQL definite dall'utente che utilizzano connessioni di Unity Catalog, gli utenti devono disporre di un'autorizzazione aggiuntiva:

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

Utilizzo dell'operatore in Lakeflow Designer

Dopo la registrazione, l'operatore verrà visualizzato in Lakeflow Designer con:

• Porta di ingresso per collegare l'origine dei dati.
• Un selettore di espressioni per scegliere quale colonna contiene il contenuto del messaggio.
• Input di testo per il canale Slack.

Gli utenti possono inviare notifiche in base ai dati, ad esempio avvisi quando vengono superate determinate soglie.

Casi d'uso comuni

• Avvisi : inviare notifiche quando vengono rilevati problemi di qualità dei dati.
• Notifiche : notificare ai team al termine dei flussi di lavoro.
• Webhook: chiamare API esterne per attivare processi downstream.
• Registrazione : inviare messaggi di controllo a sistemi esterni.

Procedure consigliate per la creazione di operatori per chiamate API

1. Usare sempre la modalità di anteprima : aggiungere una is_preview proprietà config con format: is_preview per evitare chiamate API accidentali.
2. Usa le connessioni di Unity Catalog — Non codificare mai le credenziali direttamente nella tua UDF. Le connessioni di Unity Catalog sono disponibili solo nelle UDF SQL.
3. Gestire gli errori normalmente : le chiamate API possono avere esito negativo; considerare cosa restituire in caso di errore.
4. Test approfondito : usare la modalità di anteprima durante lo sviluppo.
5. Documentare la configurazione della connessione : gli utenti devono conoscere la connessione da creare.