Tutoriel : envoyer un message Slack

Dans ce tutoriel, vous créez un opérateur UDF SQL pour Lakeflow Designer qui publie des messages dans des canaux de distribution Slack. Pour une vue d'ensemble plus large, voir Opérateurs personnalisés dans Lakeflow Designer.

Présentation

Cet opérateur envoie des messages à Slack en utilisant :

SQL UDF : Écrite en SQL plutôt qu'en Python.
Connexion HTTP Unity Catalog : gère de manière sécurisée les identifiants de l'API Slack.
Prise en charge du mode aperçu : empêche les appels réels de Slack API pendant l'aperçu du workflow.
Paramètres d'expression : Permet un contenu de message dynamique à partir des colonnes de DataFrame.

Pourquoi utiliser une UDF SQL

Les UDF SQL peuvent appeler des APIs externes (comme Slack, des Endpoint REST et des webhooks) avec la fonction http_request(), qui s'authentifie via une connexion HTTP Unity Catalog. La connexion stocke les identifiants pour qu’ils ne restent pas dans le code de la fonction. Pour appeler une API à partir de Python, utilisez un opérateur python-run-function. Voir Didacticiel : opérateur d'expéditeur d'e-mail Gmail.

Exigences

Accès à Lakeflow Designer dans un workspace activé pour Unity Catalog. Voir les Prérequis.
USE CATALOG dans le catalogue main et CREATE SCHEMA sur main, ou USE SCHEMA et CREATE FUNCTION sur un schéma main.example_output existant. Pour utiliser un catalogue ou un schéma différent, remplacez main.example_output partout. Voir Référence des privilèges Unity Catalog.
CREATE CONNECTION sur le métastore Unity Catalog pour créer la connexion HTTP. Voir Connexion à des services HTTP externes.
Une application Slack avec un jeton de bot qui peut publier sur votre Canal de distribution.

Étape 1 : Configurez la connexion HTTP au Unity Catalog.

Avant de créer l'UDF, vous devez configurer une connexion HTTP Unity Catalog pour stocker en toute sécurité vos identifiants d'API Slack. Remplacez <xoxb-your-slack-bot-token> par votre jeton de bot Slack réel. Vous pouvez l'obtenir à partir des paramètres de votre application Slack. Vous pouvez utiliser cette même connexion pour plusieurs UDF. Pour en savoir plus, consultez Connecter à des services HTTP externes.

SQL
CREATE CONNECTION my_slack_connection TYPE HTTP OPTIONS (
  host 'https://slack.com',
  port '443',
  base_path '/api/',
  bearer_token '<xoxb-your-slack-bot-token>'
);

Étape 2 : Créer le YAML de l'opérateur

Maintenant, créez le YAML pour l’opérateur. Pour plus de détails sur le schéma, consultez la référence YAML de l’opérateur personnalisé.

Le YAML de cet opérateur comprend :

Paramètre d'expression (msg) : Permet un contenu de message dynamique à partir des colonnes de dataframe.
parameter de chaîne (channel) : nom/ID de canal de distribution statique.
Mode de prévisualisation (is_preview) : Une propriété de configuration avec format: is_preview qui active le mode de prévisualisation afin d'éviter les appels d'API réels pendant les tests.

YAML
schema: custom-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

Sont concernés :

Clé de configuration	Widget	Objectif
`msg`	`expression`	Contenu dynamique du message à partir des données d'entrée.
`channel`	`input`	Canal Slack où envoyer (par ex., `#alerts`).
`is_preview`	N/A	Propriété de configuration booléenne avec `format: is_preview` qui permet à l’opérateur de se comporter différemment lors d’un aperçu (dans ce cas, éviter la création effective d’un message Slack).

Clé de configuration	Widget	Objectif
`msg`	`expression`	Contenu dynamique du message à partir des données d'entrée.
`channel`	`input`	Canal Slack où envoyer (par ex., `#alerts`).
`is_preview`	N/A	Propriété de configuration booléenne avec `format: is_preview` qui permet à l’opérateur de se comporter différemment lors d’un aperçu (dans ce cas, éviter la création effective d’un message Slack).

Étape 3 : créez la fonction Unity Catalog

Lors de la création de fonctions UDF SQL, certaines choses sont inhabituelles par rapport à la plupart des requêtes SQL :

Utilisez la syntaxe RETURN au lieu de AS $$.
Intégrer la configuration YAML dans un bloc de commentaires SQL (/* ... */).
Peut utiliser la fonction http_request pour les appels d'API.

L’exemple crée la fonction dans main.example_output. Créez d’abord le schéma s’il n’existe pas :

SQL
CREATE SCHEMA IF NOT EXISTS main.example_output

SQL
CREATE OR REPLACE FUNCTION main.example_output.send_slack_msg(
    msg STRING,
    channel STRING,
    is_preview BOOLEAN
)
RETURNS STRING
RETURN (/*
    schema: custom-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
);

Cette fonction SQL comprend les fonctionnalités suivantes :

Fonctionnalité	Objectif
`http_request()`	Effectue des appels HTTP vers des APIs externes.
`conn => 'my_slack_connection'`	Fait référence à la connexion UC pour l'authentification.
`to_json()` et `named_struct()`	Construit la charge utile JSON pour l'API Slack.
Bloc de commentaires YAML	Utilisé par Lakeflow Designer pour créer l'opérateur.
`CASE WHEN`	Implémente la logique du mode aperçu.

Fonctionnalité	Objectif
`http_request()`	Effectue des appels HTTP vers des APIs externes.
`conn => 'my_slack_connection'`	Fait référence à la connexion UC pour l'authentification.
`to_json()` et `named_struct()`	Construit la charge utile JSON pour l'API Slack.
Bloc de commentaires YAML	Utilisé par Lakeflow Designer pour créer l'opérateur.
`CASE WHEN`	Implémente la logique du mode aperçu.

Étape 4 : Testez la fonction

Ensuite, testez la fonction pour vous assurer qu'elle fonctionne avant de l'enregistrer en tant qu'opérateur.

Testez d’abord en mode aperçu afin qu’aucun message ne soit envoyé. Il renvoie Preview mode - no message sent to #test-channel.

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

Testez avec un véritable appel d’API pour envoyer un message à Slack. Utilisez cette fonction avec précaution : elle publie des messages sur le canal de distribution et renvoie le JSON de la réponse de l’API Slack.

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

Étape 5 : Enregistrez l'opérateur

Ajoutez l'opérateur à votre fichier .custom_operators.yaml :

YAML
operators:
  - catalog: main
    schema: example_output
    functionName: send_slack_msg

remarque

Si vous définissez ce fichier dans votre dossier utilisateur, il n’apparaît que pour vous. Pour plus d'informations, consultez la section Inscription et déploiement de votre opérateur dans Lakeflow Designer.

Étape 6 : Configurez les autorisations

Pour les UDF SQL qui utilisent les connexions Unity Catalog, les utilisateurs ont besoin d'une autorisation supplémentaire :

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

important

Sans l'autorisation USE CONNECTION, les utilisateurs ne pourront pas effectuer d'appels d'API même s'ils peuvent exécuter la fonction.

Étape 7 : Utiliser l’opérateur dans Lakeflow Designer

Dans une préparation de données visuelles, ouvrez le menu Opérateurs dans le panneau de gauche et recherchez l’opérateur Envoyer un message Slack .
Faites glisser l’opérateur sur la toile et connectez-lui une entrée.
Double-cliquez sur l’opérateur pour ouvrir son panneau de configuration, puis définissez ses champs.
Sélectionnez l'opérateur pour prévisualiser ses résultats dans le volet de sortie.

L'opérateur a :

Un port d'entrée pour connecter votre source de données.
Un sélecteur d'expressions pour sélectionner la colonne qui contient le contenu du message.
Un champ de saisie de texte pour le canal Slack.

Les utilisateurs peuvent envoyer des notifications basées sur leurs données. Par exemple, déclencher des alertes lorsque certains seuils sont dépassés.

Conseils et bonnes pratiques

Utilisez les exemples et consignes suivants lorsque vous créez des opérateurs qui appellent des APIs externes.

Cas d'utilisation courants

Alertes : envoyer des notifications lorsque des problèmes de qualité des données sont détectés.
Notifications : Avertissez les équipes lorsque les workflows sont terminés.
Webhooks : Appelez des APIs externes pour Trigger des processus en aval.
**Journalisation** : Envoyer les messages d'audit vers des systèmes externes.

Bonnes pratiques pour créer des opérateurs appelant des API

Toujours utiliser le mode de prévisualisation : ajoutez une propriété de configuration is_preview avec format: is_preview pour éviter les appels d’API accidentels.
Utilisez les connexions Unity Catalog : ne codez jamais d'identifiants en dur dans vos UDF. Stockez-les dans une connexion HTTP Unity Catalog et appelez-la avec http_request().
Gérez les erreurs en douceur : les appels d'API peuvent échouer ; déterminez ce qu'il faut renvoyer en cas d'erreur.
Testez minutieusement : utilisez le mode aperçu pendant le développement.
Documenter la configuration de la connexion : les utilisateurs doivent savoir quelle connexion créer.

Présentation​

Pourquoi utiliser une UDF SQL​

Exigences​

Étape 1 : Configurez la connexion HTTP au Unity Catalog.​

Étape 2 : Créer le YAML de l'opérateur​

Étape 3 : créez la fonction Unity Catalog​

Étape 4 : Testez la fonction​

Étape 5 : Enregistrez l'opérateur​

Étape 6 : Configurez les autorisations​

Étape 7 : Utiliser l’opérateur dans Lakeflow Designer​

Conseils et bonnes pratiques​

Cas d'utilisation courants​

Bonnes pratiques pour créer des opérateurs appelant des API​

Ressources supplémentaires​