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 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 die functie stelt de operator in staat zich anders te gedragen tijdens een preview (in dit geval vermijd je het daadwerkelijk maken van een Slack-bericht).

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.

Het voorbeeld creëert de functie in main.example_output. Maak eerst het schema aan als het niet bestaat:

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
        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 zodat er geen bericht wordt verzonden. Het geeft Preview mode - no message sent to #test-channel terug.

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

Test met een echte API-aanroep om een bericht naar Slack te sturen. Gebruik dit voorzichtig: het plaatst een bericht in het kanaal en geeft de JSON-reactie van de Slack API terug.

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

Stap 5: De operator registreren

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

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

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

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