Esercitazione: Inviare un messaggio Slack

In questa esercitazione viene creato un operatore UDF SQL per Lakeflow Designer che invia messaggi ai canali Slack. 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é usare una UDF SQL

Gli UDF SQL possono chiamare API esterne (come Slack, endpoint REST e webhook) con questa http_request() funzione, che si autentica tramite una connessione HTTP di Unity Catalog. La connessione memorizza le credenziali, così che restino fuori dal codice di funzione. Per chiamare un'API da Python invece, usa un python-run-function operatore. Vedi il tutorial: operatore di invio email di Gmail.

Requirements

• Accesso a Lakeflow Designer in uno spazio di lavoro abilitato a Unity Catalog. Vedere Prerequisiti.
• USE CATALOG sul main catalogo, e CREATE SCHEMA su main, oppure USE SCHEMA e CREATE FUNCTION su uno schema main.example_output esistente. Per usare un catalogo o uno schema diverso, sostituisci main.example_output ovunque. Vedere Informazioni di riferimento sui privilegi del catalogo Unity.
• CREATE CONNECTION sul metastore del Catalogo Unity, per creare la connessione HTTP. Vedere Connettersi a servizi HTTP esterni.
• Un'app Slack con un token bot che può postare sul tuo canale.

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

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

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.

L'esempio crea la funzione in main.example_output. Crea prima lo schema se non esiste:

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

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.

Prova prima in modalità anteprima così non viene inviato alcun messaggio. Restituisce 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;

Prova con una chiamata API reale per inviare un messaggio a Slack. Usa questo con cautela: viene pubblicato sul canale e restituisce il JSON di risposta dell'API Slack.

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

Passaggio 5: Registrare l'operatore

Aggiungi l'operatore nel file .user_defined_operators.yaml:

operators:
  - catalog: main
    schema: example_output
    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:

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

Passo 7: Usa l'operatore in Lakeflow Designer

1. In una preparazione visuale dei dati, apri il menu Operatori nel pannello sinistro e trova l'operatore Invia messaggio Slack.
2. Trascina l'operatore nell'area di disegno e collega un input ad essa.
3. Fai doppio clic sull'operatore per aprire il suo pannello di configurazione, poi imposta i suoi campi.
4. Seleziona l'operatore per visualizzare i risultati nel pannello di output.

L'operatore ha:

• 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, l'invio di avvisi quando vengono superate determinate soglie.

Consigli e migliori pratiche

Usa i seguenti esempi e linee guida quando costruisci operatori che chiamano API esterne.

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 in modo statico le credenziali nella tua UDF. Memorizzali in una connessione HTTP del Catalogo Unity e richiamala con http_request().
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.

Risorse aggiuntive

• Operatori definiti dall'utente in Lakeflow Designer
• Scrivere la logica per gli operatori definiti dall'utente di Lakeflow Designer
• Informazioni di riferimento su YAML per l'operatore definito dall'utente