Zelfstudie: Slack-bericht verzenden

In deze zelfstudie maakt u een SQL UDF-operator voor Lakeflow Designer waarmee berichten worden geplaatst in Slack-kanalen. SQL UDF's zijn de juiste keuze wanneer een functie externe API's via HTTP moet aanroepen. Zie Door de gebruiker gedefinieerde operators in Lakeflow Designer voor een breder overzicht.

Overview

Deze operator verzendt berichten naar Slack met behulp van:

  • SQL UDF: geschreven in SQL in plaats van Python.
  • HTTP-verbinding met Unity Catalog: Slack API-referenties veilig beheren.
  • Ondersteuning voor preview-modus: hiermee voorkomt u werkelijke Slack API-aanroepen tijdens de voorbeeldweergave van de werkstroom.
  • Expressieparameters: Hiermee staat u dynamische berichtinhoud uit DataFrame-kolommen toe.

Waarom een SQL UDF gebruiken

Voor operators die externe API's moeten aanroepen (zoals Slack, REST-eindpunten, webhooks), moet u SQL UDF's gebruiken. Python UDF's en UDDF's kunnen geen HTTP-aanvragen indienen. SQL UDF's hebben toegang tot de http_request() functie die werkt met Unity Catalog-verbindingen.

Stap 1: De HTTP-verbinding voor De Unity Catalog instellen

Voordat u de UDF maakt, moet u een UNITY Catalog HTTP-verbinding instellen om uw Slack API-referenties veilig op te slaan. Vervang <xoxb-your-slack-bot-token> door je daadwerkelijke Slack Bot Token. U kunt dit verkrijgen via uw Slack-app-instellingen. U kunt dezelfde verbinding gebruiken voor meerdere UDF's. Zie Verbinding maken met externe HTTP-services voor meer informatie.

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

Stap 2: de YAML-operator maken

Maak nu de YAML voor de operator. Zie de YAML-referentie voor door de gebruiker gedefinieerde operator voor meer informatie over het schema.

De YAML voor deze operator omvat:

  • Expressieparameter (msg): Maakt dynamische berichtinhoud uit dataframekolommen mogelijk.
  • Tekenreeksparameter (channel): Naam/id van statisch kanaal.
  • Preview-modus (is_preview): Een configuratie-eigenschap waarmee format: is_preview de preview-modus werkelijke API-aanroepen tijdens het testen kan voorkomen.
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

Dit omvat:

Configuratiesleutel Widget Purpose
msg expression Dynamische berichtinhoud van invoergegevens.
channel input Slack-kanaal om naar te verzenden (bijvoorbeeld #alerts).
is_preview n/a Een booleaanse configuratie-eigenschap met format: is_preview, waarmee de operator zich tijdens een voorvertoning anders kan gedragen (in dit geval door te voorkomen dat er daadwerkelijk een Slack-bericht wordt aangemaakt).

Stap 3: de unity-catalogusfunctie maken

Bij het maken van SQL UDF's zijn er enkele dingen die ongebruikelijk zijn vergeleken met de meeste SQL-query's:

  • Gebruik de RETURN syntaxis in plaats van AS $$.
  • Neem de YAML-configuratie op in een SQL-commentaarblok (/* ... */).
  • Kan de http_request functie gebruiken voor API-aanroepen.
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
);

Deze SQL-functie bevat de volgende functies:

Feature Purpose
http_request() Maakt HTTP-aanroepen naar externe API's.
conn => 'my_slack_connection' Verwijst naar de UC-verbinding voor verificatie.
to_json() en named_struct() Hiermee wordt de JSON-nettolading voor de Slack-API samengesteld.
YAML-commentaarblok Wordt gebruikt door Lakeflow Designer om de operator te maken.
CASE WHEN Hiermee wordt preview-moduslogica geïmplementeerd.

Stap 4: De functie testen

Test vervolgens de functie om te controleren of deze werkt voordat u deze registreert als operator.

Test eerst in de preview-modus om te voorkomen dat er een Slack-bericht wordt verzonden:

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

Testen met externe API-aanroep (verzendt een bericht naar 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

Stap 5: De operator registreren

Voeg de operator toe aan uw .user_defined_operators.yaml bestand:

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

Note

Als u dit bestand in uw gebruikersmap definieert, wordt het alleen voor u weergegeven. Zie Uw operator detecteerbaar maken voor meer informatie.

Stap 6: Machtigingen instellen

Voor SQL UDF's die gebruikmaken van Unity Catalog-verbindingen hebben gebruikers een extra machtiging nodig:

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

Zonder de USE CONNECTION machtiging kunnen gebruikers geen API-aanroepen uitvoeren, zelfs niet als ze de functie kunnen uitvoeren.

Operator gebruiken in Lakeflow Designer

Nadat deze is geregistreerd, wordt de operator weergegeven in Lakeflow Designer met:

  • Een invoerpoort om verbinding te maken met uw gegevensbron.
  • Een expressiekiezer om te selecteren welke kolom de inhoud van het bericht bevat.
  • Een tekstinvoer voor het Slack-kanaal.

Gebruikers kunnen meldingen verzenden op basis van hun gegevens. Bijvoorbeeld waarschuwingen wanneer bepaalde drempelwaarden worden overschreden.

Veelvoorkomende gebruiksvoorbeelden

  • Waarschuwingen: meldingen verzenden wanneer problemen met de gegevenskwaliteit worden gedetecteerd.
  • Meldingen: Stel teams op de hoogte wanneer de werkstromen zijn voltooid.
  • Webhooks: externe API's aanroepen om downstreamprocessen te activeren.
  • Logboekregistratie: Controleberichten verzenden naar externe systemen.

Praktische richtlijnen voor het ontwikkelen van operators die API's aanroepen

  1. Altijd de preview-modus gebruiken: voeg een is_preview configuratie-eigenschap toe om format: is_preview onbedoelde API-aanroepen te voorkomen.
  2. Gebruik Unity Catalog-verbindingen: codeer nooit referenties in uw UDF. Unity Catalog-verbindingen zijn alleen beschikbaar in SQL UDF's.
  3. Fouten probleemloos afhandelen: API-aanroepen kunnen mislukken; bedenk wat er moet worden geretourneerd bij een fout.
  4. Test grondig: Gebruik de preview-modus tijdens de ontwikkeling.
  5. Documenteer de verbindingsinstellingen: gebruikers moeten weten welke verbinding moet worden gemaakt.
  • Last updated on