Tutoriel : Envoyer un message Slack

Important

Cette fonctionnalité est disponible en préversion publique.

Dans ce tutoriel, vous allez créer un opérateur UDF SQL pour Lakeflow Designer qui publie des messages sur des canaux Slack. Les fonctions SQL définies par l’utilisateur constituent le choix approprié lorsqu’elles doivent appeler des API externes via le protocole HTTP. Pour une vue d’ensemble plus large, consultez les opérateurs définis par l’utilisateur dans Lakeflow Designer.

Vue d’ensemble

Cet opérateur envoie des messages à Slack à l’aide de :

  • SQL UDF : écrit dans SQL plutôt que Python.
  • Connexion HTTP du catalogue Unity : gère en toute sécurité les informations d’identification de l’API Slack.
  • Prise en charge du mode préversion : empêche les appels réels de l’API Slack pendant la préversion du flux de travail.
  • Paramètres d’expression : autorise le contenu de message dynamique à partir de colonnes DataFrame.

Pourquoi les UDF SQL ?

Pour les opérateurs qui doivent appeler des API externes (comme Slack, des points de terminaison d’API REST ou des webhooks), vous devez utiliser des UDF SQL. Les UDF et UDTF Python ne peuvent pas effectuer de requêtes HTTP. Les fonctions SQL définies par l’utilisateur ont accès à la fonction http_request(), qui fonctionne avec les connexions Unity Catalog.

Étape 1 : Configurer la connexion HTTP du catalogue Unity

Avant de créer la fonction UDF, vous devez configurer une connexion HTTP du catalogue Unity pour stocker en toute sécurité vos informations d’identification d’API Slack. Remplacez <xoxb-your-slack-bot-token> par votre jeton de bot Slack réel. Vous pouvez l’obtenir à partir de vos paramètres d’application Slack. Vous pouvez utiliser cette même connexion dans plusieurs fonctions définies par l’utilisateur. Pour plus d’informations, consultez Se connecter aux services HTTP externes.

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

Étape 2 : Créer l’opérateur YAML

Vous allez maintenant créer le YAML pour l’opérateur. Pour plus d’informations sur le schéma, consultez la référence YAML de l’opérateur défini par l’utilisateur.

Le YAML pour cet opérateur inclut :

  • Paramètre d’expression (msg) : autorise le contenu de message dynamique à partir de colonnes de trame de données.
  • Paramètre de chaîne (channel) : nom/ID de canal statique.
  • Mode préversion (is_preview) : propriété de configuration avec format: is_preview laquelle permet le mode d’aperçu pour empêcher les appels d’API réels pendant le 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

Cela inclut les éléments suivants :

Clé de configuration Widget Purpose
msg expression Contenu de message dynamique à partir de données d’entrée.
channel text Canal Slack à envoyer (par exemple, #alerts).
is_preview n/a Propriété de configuration booléenne avec format: is_preview qui permet à l’opérateur d’adopter un comportement différent lors d’un aperçu (dans ce cas, éviter de créer réellement un message Slack).

Étape 3 : Créer la fonction Catalogue Unity

Lors de la création de fonctions SQL définies par l’utilisateur, certains aspects sont peu courants par rapport aux requêtes SQL classiques :

  • Utilisez la RETURN syntaxe au lieu de AS $$.
  • Incorporer la configuration YAML dans un bloc de commentaires SQL (/* ... */).
  • Peut utiliser la fonction http_request pour effectuer des appels d’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
);

Cette fonction SQL inclut les fonctionnalités suivantes :

Fonctionnalité Purpose
http_request() Effectue des appels HTTP aux API 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 d’aperçu.

Étape 4 : Tester la fonction

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

Testez d’abord en mode préversion pour éviter d’envoyer un message 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"

Testez avec un appel d’API externe (envoie un message à 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

Étape 5 : Inscrire l’opérateur

Ajoutez l’opérateur au fichier .user_defined_operators.yaml :

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

Note

Si vous définissez ce fichier dans votre dossier utilisateur, il s’affiche uniquement pour vous. Pour plus d’informations, consultez Rendre votre opérateur détectable.

Étape 6 : Configurer les autorisations

Pour les fonctions SQL définies par l’utilisateur qui utilisent des connexions Unity Catalog, les utilisateurs doivent disposer d’une autorisation supplémentaire :

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

Important

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

Utilisation de l’opérateur dans Lakeflow Designer

Une fois inscrit, l’opérateur s’affiche dans Lakeflow Designer avec :

  • Port d’entrée pour connecter votre source de données.
  • Sélecteur d’expressions pour sélectionner la colonne qui contient le contenu du message.
  • Entrée de texte pour le canal Slack.

Les utilisateurs peuvent envoyer des notifications en fonction de leurs données , par exemple, alerter quand certains seuils sont dépassés.

Cas d’usage courants

  • Alertes : envoyer des notifications lorsque des problèmes de qualité des données sont détectés.
  • Notifications : notifier les équipes lorsque les flux de travail sont terminés.
  • Webhooks : appelez des API externes pour déclencher des processus en aval.
  • Journalisation : envoyer des messages d’audit à des systèmes externes.

Meilleures pratiques pour la création d’opérateurs d’appel d’API

  1. Utilisez toujours le mode d’aperçu : ajoutez une is_preview propriété de configuration pour format: is_preview empêcher les appels d’API accidentels.
  2. Utilisez les connexions Unity Catalog — N’encodez jamais les informations d’identification en dur dans votre UDF. Les connexions Unity Catalog ne sont disponibles que dans les fonctions SQL définies par l’utilisateur.
  3. Gérer correctement les erreurs : les appels d’API peuvent échouer ; considérez ce qu’il faut retourner en cas d’erreur.
  4. Testez soigneusement : utilisez le mode d’aperçu pendant le développement.
  5. Documenter la configuration de la connexion : les utilisateurs doivent savoir quelle connexion créer.
  • Last updated on