Tworzenie makra

Makro to wielokrotnego użytku zaawansowany przepływ pracy (DAG) z zadeklarowanym kontraktem wejścia/wyjścia. Makro wywołujesz z innego przepływu pracy za pomocą kroku Macro Run lub Macro Concurrent — każde wywołanie działa we własnym, izolowanym schemacie roboczym, więc to samo makro może być wywoływane równolegle z wielu przepływów nadrzędnych lub dla wielu wierszy tabeli sterującej bez kolizji między uruchomieniami.

Użyj makra, gdy masz powtarzalną, parametryzowaną transformację danych — na przykład „przetwórz dane sprzedaży za jeden miesiąc dla jednego regionu” — którą chcesz wywoływać z przepływu sterującego raz na miesiąc, raz na region lub w obu układach. Wywołujący wiąże tabele i zmienne z zadeklarowanymi portami wejściowymi makra; po zakończeniu zadeklarowane tabele wyjściowe są kopiowane z powrotem do miejsc docelowych po stronie wywołującego.

Notatka

Makra są funkcją dostępną tylko w trybie zaawansowanym. Najpierw przekonwertuj swój przepływ pracy na zaawansowany. Kroki wewnątrz makra muszą być bezpieczne dla makr: transformacje tabel, importy, eksporty, kroki zmiennych w zakresie uruchomienia, zagnieżdżone wywołania Macro Run oraz kilka kroków sterowania przepływem. Importy wymiarów i kroki aktualizujące wymiary są odrzucane, ponieważ wymiary są globalnym stanem projektu.

Kroki

1. Otwórz projekt zawierający przepływ pracy, który chcesz zamienić w makro.
2. Przejdź na kartę Przepływy pracy i zaznacz wiersz przepływu pracy.
3. W prawym panelu Szczegóły przepływu pracy sprawdź, czy Typ przepływu pracy to Advanced. Jeśli jest to Standard, najpierw użyj akcji Konwertuj na zaawansowany.
4. W sekcji Makro panelu Szczegóły przepływu pracy kliknij Konwertuj na makro… i potwierdź w oknie dialogowym. Przepływ pracy przechodzi w tryb makra i pojawia się edytor portów.
5. Kliknij Dodaj port, aby zadeklarować każde wejście lub wyjście, które makro przyjmuje lub tworzy. Dla każdego portu:
   • Nazwa — krótki identyfikator, którego wywołujący używa do powiązania z tym portem (na przykład month, region_sales).
   • Kierunek — Dane wejściowe (wywołujący dostarcza tę wartość lub tabelę) lub Dane wyjściowe (makro tworzy ją, a wywołujący ją odbiera).
   • Rodzaj — Tabela dla tabeli danych, Skalar dla pojedynczej wartości (ciąg znaków / int / float / bool / data) lub Wymiar dla odwołania do wymiaru hierarchicznego.
   • Wymagane — wyczyść, jeśli makro może działać bez powiązania tego portu.
   • Notatka — krótka uwaga o tym, co reprezentuje ten port, wyświetlana autorom w formularzu powiązań po stronie wywołującego.
6. Kliknij Zapisz porty.

Przepływ pracy jest teraz makrem. Autorzy, którzy dodadzą krok Macro Run w innym przepływie pracy, zobaczą zadeklarowane przez Ciebie porty i powiążą się z nimi według nazwy.

Każdy port to jedno nazwane, typowane miejsce w kontrakcie makra. Wywołujący wiążą się z portami według nazwy — wejścia są kopiowane do środka, wyjścia kopiowane z powrotem na zewnątrz.

Wywoływanie makra

W przepływie pracy wywołującym:

1. Dodaj krok Makro: uruchom.
2. W polu Makro do uruchomienia wybierz projekt i przepływ pracy makra.
3. Input Port Bindings — dla każdego portu wejściowego zadeklarowanego przez makro dodaj powiązanie:
   • Porty typu Tabela przyjmują tabelę źródłową po stronie wywołującego; opcjonalnie wybierz podzbiór kolumn i dodaj filtr (klauzulę WHERE odwołującą się do skalarnych zmiennych wejściowych makra), aby do schematu uruchomienia makra trafiał tylko potrzebny fragment.
   • Porty Skalar / Wymiar przyjmują wartość (często zmienną przepływu pracy wywołującego) — ustawianą PRZED kopiowaniem tabel do środka, aby filtr tabeli wejściowej mógł się do niej odwoływać.
4. Output Port Bindings — dla każdego portu wyjściowego tworzonego przez makro wskaż docelową tabelę po stronie wywołującego (tworzoną na bieżąco, jeśli jeszcze nie istnieje).
5. Zapisz krok.

Gdy przepływ nadrzędny działa i dociera do kroku Macro Run, moduł uruchamiający:

1. Generuje nowy run_id dla tego wywołania makra.
2. Tworzy schemat roboczy dla uruchomienia (macrorun_<run_id>) w katalogu projektu.
3. Kopiuje powiązane tabele wejściowe do schematu roboczego (projekcja kolumn i filtr są stosowane przy kopiowaniu do środka, więc filtr jest wypychany w dół).
4. Ustawia powiązane skalarne zmienne wejściowe i zmienne wymiarów w nakładce zmiennych makra w zakresie uruchomienia.
5. Wykonuje kroki makra w tym samym procesie. Każdy krok SQL wewnątrz makra odczytuje i zapisuje schemat roboczy zamiast schematu projektu.
6. Kopiuje zadeklarowane tabele wyjściowe z powrotem do miejsc docelowych wywołującego.
7. Usuwa schemat roboczy (zawsze — nawet jeśli krok wewnątrz makra się nie powiódł).

Każde wywołanie dostaje nowy run_id i własny schemat roboczy. Kroki odczytują i zapisują wyłącznie ten schemat, a po zakończeniu uruchomienia jest on usuwany — niezależnie od tego, czy zakończyło się sukcesem, błędem czy zatrzymaniem.

Ponieważ każde wywołanie ma własny schemat roboczy, dwa równoległe wywołania tego samego makra (z pętli, z rozgałęzienia lub z niezależnych przepływów pracy) nigdy nie kolidują ze sobą w nazwach tabel pośrednich.

Uruchamianie jednego makra na wiersz tabeli sterującej

Użyj kroku Makro: uruchomienie współbieżne, gdy jedna tabela wywołującego ma sterować wieloma niezależnymi wywołaniami makra.

1. Dodaj krok Makro: uruchomienie współbieżne.
2. Na karcie Driver wybierz tabelę sterującą po stronie wywołującego i ustaw Uruchomienia równoległe na maksymalną liczbę wywołań makra podrzędnego uruchamianych jednocześnie.
3. Na karcie Wybór danych tabeli zmapuj kolumny tabeli sterującej, których potrzebuje każde wywołanie podrzędne.
4. Na karcie Filtr tabeli sterującej opcjonalnie ogranicz wiersze tabeli sterującej do przetworzenia.
5. Na karcie Makro wybierz przepływ pracy makra.
6. Na karcie Powiązania wejściowe powiąż wartości kolumn tabeli sterującej ze skalarnymi zmiennymi lub zmiennymi wymiarów makra oraz powiąż tabele po stronie wywołującego z portami tabel makra.
7. Na karcie Powiązania wyjściowe zmapuj porty wyjściowe makra na tabele docelowe po stronie wywołującego.

Każdy wybrany wiersz tabeli sterującej otrzymuje osobny run_id i schemat roboczy. Zatrzymanie kroku nadrzędnego zatrzymuje wszystkie aktywne wywołania podrzędne i usuwa ich schematy uruchomień.

Jedno wywołanie na wiersz tabeli sterującej, każde we własnym schemacie roboczym — dzięki temu tabele pośrednie nigdy nie kolidują. Uruchomienia równoległe określają, ile wywołań działa jednocześnie, a każdy wiersz zapisuje własną tabelę results_{region}.

Zmiana makra z powrotem na zaawansowany przepływ pracy

W dowolnej chwili możesz usunąć znacznik makra, klikając Zmień na zaawansowany… w panelu Szczegóły przepływu pracy. Przepływ pracy wraca do zwykłego zaawansowanego przepływu pracy, a wszystkie kroki Macro Run po stronie wywołującego, które się do niego odwołują, zakończą się w czasie działania błędem „not a macro”. Zadeklarowane porty pozostają w rekordzie, więc ponowna konwersja później je przywróci.

Ograniczenia (v1)

• Makra mogą zawierać transformacje tabel, importy i eksporty, ponieważ odczyty i zapisy tabel są izolowane do schematu roboczego wywołania. Importy wymiarów i kroki aktualizujące wymiary nie są dozwolone, ponieważ wymiary są globalnym stanem projektu. Inne kroki z efektami ubocznymi niezwiązanymi z tabelami, takie jak operacje na dokumentach i wywołania agentów, nie są w wersji v1 bezpieczne dla makr.
• Makra muszą znajdować się w tym samym projekcie co wywołujący. Makra między projektami nie są jeszcze obsługiwane.
• Kroku Macro Run nie można wywołać z kroku Uruchom przepływ pracy, Workflow Loop ani warunkowego kroku Uruchom przepływ pracy — te kroki działają bez izolacji i naruszyłyby kontrakt schematu dla uruchomienia. Zamiast tego użyj kroku Macro Run w przepływie wywołującym.

Następne kroki

• Dokumentacja referencyjna kroku Macro Run — opis poszczególnych pól kroku wywołującego.
• Dokumentacja referencyjna kroku Macro Concurrent — uruchom jedno wywołanie makra na każdy wiersz tabeli sterującej.
• Krok Uruchom przepływ pracy — dla podprzepływów pracy, które nie wymagają izolacji wywołania.