Samouczek: wysyłanie komunikatu slack

W tym samouczku utworzysz operator SQL UDF w Lakeflow Designer, który wysyła wiadomości do kanałów Slacka. Szersze omówienie znajduje się w Operatorach niestandardowych w Lakeflow Designer.

Overview

Ten operator wysyła komunikaty do usługi Slack przy użyciu:

• SQL UDF: napisane w języku SQL, a nie Python.
• Połączenie HTTP Unity Catalog: bezpiecznie zarządza poświadczeniami interfejsu API usługi Slack.
• Obsługa trybu podglądu: uniemożliwia rzeczywiste wywołania interfejsu API usługi Slack podczas podglądu przepływu pracy.
• Parametry wyrażenia: zezwala na zawartość komunikatu dynamicznego z kolumn ramek danych.

Dlaczego warto używać funkcji SQL UDF

Funkcje SQL UDF mogą wywoływać zewnętrzne interfejsy API (takie jak Slack, punkty końcowe REST i webhooki) za pomocą funkcji http_request(), która uwierzytelnia się przy użyciu połączenia HTTP w Unity Catalog. Połączenie przechowuje dane uwierzytelniające, więc nie są one przechowywane w kodzie funkcji. Aby zamiast tego wywołać API z Pythona, użyj operatora python-run-function. Zobacz samouczek: Operator nadawcy e-mail w Gmailu.

Requirements

• Dostęp do Lakeflow Designer w przestrzeni roboczej z Unity Catalog. Zobacz Wymagania wstępne.
• USE CATALOG w katalogu main, oraz CREATE SCHEMA na main, lub USE SCHEMA oraz CREATE FUNCTION na istniejącym main.example_output schemacie. Aby użyć innego katalogu lub schematu, zastąp main.example_output w całym tekście. Zobacz odniesienie dotyczące uprawnień Unity Catalog.
• CREATE CONNECTION Kliknij na metastore katalogu Unity, aby utworzyć połączenie HTTP. Zobacz Łączenie z zewnętrznymi usługami HTTP.
• Aplikacja Slack z tokenem bota, który może publikować wiadomości na Twoim kanale.

Krok 1. Skonfiguruj połączenie HTTP usługi Unity Catalog

Przed utworzeniem funkcji UDF należy skonfigurować połączenie HTTP usługi Unity Catalog, aby bezpiecznie przechowywać poświadczenia interfejsu API Slack. Zastąp <xoxb-your-slack-bot-token> element rzeczywistym tokenem bota usługi Slack. Możesz to uzyskać z ustawień aplikacji Usługi Slack. Tego samego połączenia można używać w wielu funkcjach zdefiniowanych przez użytkownika. Aby dowiedzieć się więcej, zobacz Nawiązywanie połączenia z zewnętrznymi usługami HTTP.

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

Krok 2. Tworzenie operatora YAML

Teraz utwórz kod YAML dla operatora . Szczegółowe informacje o schemacie można znaleźć w dokumentacji YAML niestandardowego operatora.

Kod YAML dla tego operatora obejmuje:

• Parametr wyrażenia (msg): umożliwia dynamiczną zawartość komunikatu z kolumn ramek danych.
• Parametr ciągu (channel): nazwa/identyfikator kanału statycznego.
• Tryb podglądu (is_preview): właściwość konfiguracji, format: is_preview która umożliwia tryb podglądu, aby zapobiec rzeczywistym wywołaniom interfejsu API podczas testowania.

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

Obejmuje to:

Krok 3. Utwórz funkcję w Unity Catalog

Podczas tworzenia funkcji zdefiniowanych przez użytkownika SQL istnieje kilka rzeczy, które są nietypowe w porównaniu z większością zapytań SQL:

• RETURN Użyj składni zamiast AS $$.
• Osadź konfigurację YAML w bloku komentarzy SQL (/* ... */).
• Może używać funkcji http_request do wywołań API.

Przykład tworzy funkcję w main.example_output. Najpierw stwórz schemat, jeśli nie istnieje:

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

Ta funkcja SQL obejmuje następujące funkcje:

Krok 4. Testowanie funkcji

Następnie przetestuj funkcję, aby upewnić się, że działa, zanim zarejestrujesz ją jako operator.

Najpierw testuj w trybie podglądu, żeby nie wysyłać wiadomości. Zwraca wartość Preview mode - no message sent to #test-channel.

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

Testuj za pomocą prawdziwego wywołania API, aby wysłać wiadomość do Slacka. Używaj tego ostrożnie: publikuje w kanale i zwraca odpowiedź interfejsu Slack API w formacie JSON.

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

Krok 5. Rejestrowanie operatora

Dodaj operator do pliku .custom_operators.yaml:

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

Krok 6. Konfigurowanie uprawnień

W przypadku funkcji UDF SQL korzystających z połączeń Unity Catalog użytkownicy wymagają dodatkowego uprawnienia:

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

Krok 7: Użyj operatora w Lakeflow Designer

1. W wizualnym przygotowaniu danych otwórz menu Operatorów w lewym panelu i znajdź operatora Send Slack Message.
2. Przeciągnij operator na obszar roboczy i podłącz do niego wejście.
3. Kliknij dwukrotnie operatora, aby otworzyć panel konfiguracyjny, a następnie wypełnij jego pola.
4. Wybierz operatora, aby podglądać jego wyniki w panelu wyjściowym.

Operator posiada:

• Port wejściowy umożliwiający połączenie ze źródłem danych.
• Selektor wyrażeń do wybrania kolumny zawierającej zawartość komunikatu.
• Wprowadzanie tekstu dla kanału usługi Slack.

Użytkownicy mogą wysyłać powiadomienia na podstawie swoich danych. Na przykład alerty po przekroczeniu określonych progów.

Porady i najlepsze praktyki

Korzystaj z poniższych przykładów i wytycznych przy budowaniu operatorów wywołujących zewnętrzne API.

Typowe przypadki użycia

• Alerty: wysyłaj powiadomienia, gdy wykryto problemy z jakością danych.
• Powiadomienia: powiadom zespoły po zakończeniu przepływów pracy.
• Webhooki: wywołuj zewnętrzne interfejsy API, aby uruchamiać kolejne procesy.
• Rejestrowanie: Wysyłaj komunikaty audytowe do systemów zewnętrznych.

Najlepsze rozwiązania dotyczące tworzenia operatorów wywołujących interfejs API

1. Zawsze używaj trybu podglądu: dodaj właściwość konfiguracyjną is_preview z wartością format: is_preview, aby zapobiec przypadkowym wywołaniom API.
2. Używaj połączeń Unity Catalog: nigdy nie zapisuj poświadczeń na stałe w kodzie funkcji UDF. Przechowuj je w połączeniu HTTP Unity Catalog i wywołuj je za pomocą http_request().
3. Obsługuj błędy z wdziękiem: wywołania interfejsu API mogą zakończyć się niepowodzeniem; rozważ, co zwrócić w przypadku błędu.
4. Dokładnie przetestuj: użyj trybu podglądu podczas programowania.
5. Udokumentowanie konfiguracji połączenia: użytkownicy muszą wiedzieć, jakie połączenie należy utworzyć.

Dodatkowe zasoby

• Operatorzy niestandardowi w Lakeflow Designer
• Napisz logikę dla niestandardowych operatorów Lakeflow Designer
• Niestandardowa referencja operatora YAML