Aller au contenu principal
Dernière mise à jour le

Tutoriel : envoyer un message Slack

Dans ce tutoriel, vous créez un opérateur UDF SQL pour Lakeflow Designer qui publie des messages sur les canaux Slack. Les UDF SQL sont le bon choix lorsqu'une fonction doit appeler des APIs externes sur HTTP. Pour un aperçu plus large, consultez Opérateurs définis par l'utilisateur 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​

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

É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 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 le YAML de l'opérateur​

Maintenant, créez le fichier YAML pour l'opérateur. Pour plus de détails sur le schéma, consultez Référence YAML des opérateurs définis par l'utilisateur.

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

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

Une propriété de configuration booléenne avec format: is_preview qui permet à l'opérateur de se comporter différemment pendant un aperçu (dans ce cas, éviter de créer réellement 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

Une propriété de configuration booléenne avec format: is_preview qui permet à l'opérateur de se comporter différemment pendant un aperçu (dans ce cas, éviter de créer réellement 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.
SQL
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 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, pour éviter d'envoyer un message Slack :

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

Tester avec un appel d'API externe (envoie un message à Slack) :

SQL
-- 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 : Enregistrez l'opérateur​

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

YAML
operators:
  - catalog: main
    schema: my_schema
    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 Rendez votre opérateur visible.

É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
-- 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 l'autorisation USE CONNECTION, les utilisateurs ne pourront pas effectuer d'appels d'API même s'ils peuvent exécuter la fonction.

Utilisez l'opérateur dans Lakeflow Designer​

Une fois enregistré, l'opérateur apparaît dans Lakeflow Designer avec :

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

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​

  1. 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.
  2. Utilisez les connexions Unity Catalog : ne codez jamais les informations d’identification en dur dans votre UDF. Les connexions Unity Catalog ne sont disponibles que dans les UDF SQL.
  3. Gérez les erreurs en douceur : les appels d'API peuvent échouer ; déterminez ce qu'il faut renvoyer en cas d'erreur.
  4. Testez minutieusement : utilisez le mode aperçu pendant le développement.
  5. Documenter la configuration de la connexion : les utilisateurs doivent savoir quelle connexion créer.
Sur cette page