Web czy Webhook? Co wybrać w Azure Data Factory do automatyzacji wysyłki raportów.
Cykliczne otrzymywanie raportu to potrzeba wielu klientów. Czy wiesz jakie możliwości daje Azure? Dla jednego z naszych klientów potrzebowaliśmy stworzyć proces automatycznej wysyłki miesięcznego raportu. Jednym z wyzwań była wielkość pliku. Maksymalna wielkość załączonego pliku w Microsoft Outlook to 10 MB, a nasz miesięczny raport przewyższał tę wartość. Dodatkowo, ważna była dla nas możliwość monitorowania poprawnego działania tego procesu. I właśnie wtedy przy tworzeniu pipelinu w Azure Data Factory (ADF) musieliśmy zadać sobie istotne pytanie: Web czy WebHook?
Zacznijmy od początku. Proces do automatycznej wysyłki raportu mailem stworzyliśmy przy użyciu Logic Apps. Nie składa się on z wielu kroków, natomiast zawiera kilka kluczowych szczegółów. Na początku skupimy się na trzech pierwszych elementach, czyli jego głównych składowych.
Rys. 1. Schemat procesu w Logic Apps
Pierwszy krok to ‘When a HTTP request is received’. Zależało nam, aby parametry wysyłki raportu były dynamiczne i można było nimi sterować z poziomu Azure Data Factory. Dlatego w body zapytania zostały zdefiniowane poniższe parametry:
"properties": {
"EmailTo": {
"type": "string"
},
"EmailToBCC": {
"type": "string"
},
"EmailToCC": {
"type": "string"
},
"Subject": {
"type": "string"
},
"ReportPath": {
"type": "string"
},
"DaysValid": {
"type": "string"
}
},
"type": "object"
Kod 1. Definicja parametrów przekazywanych do procesu w Logic Apps
Następny krok to ‘Create SAS URI by path’. Właśnie ten krok rozwiąże nam kwestię z maksymalną wielkością pliku załączonego do maila. Zamiast dodania raportu jako załącznika, można zdefiniować link, który umożliwi pobranie pliku znajdującego się w Azure Data Lake. W tym kroku korzystamy z dwóch parametrów podanych z poziomu ADF. Pierwszy to ReportPath, który wskazuje bezpośrednio na lokalizację raportu, który ma zostać wysłany pod postacią linku. Drugi to DaysValid, który określa jak długo link będzie aktywny.
Trzeci krok to ‘Send an email’. Wykorzystujemy tu między innymi takie parametry jak Subject oraz adresatów maila. Bardzo ważne jest tutaj Body. Przy użyciu HTML możemy odpowiednio sformatować naszego emaila i w łatwy sposób sprawić, że załączony link do raportu nie będzie długim i brzydko wyglądającym ciągiem znaków.
concat(
'Hello,
<br>
<br>
Please see the report under the following link.',
'<br>
<br>
<a href="',body('Create_SAS_URI_by_path_(V2)')?['WebUrl'] ,'">Download report here</a>',
'<br>
<br>
Please note that a link is only valid for ', triggerBody()?['DaysValid'] , ' day(s).
<br>
<br>
Best regards'
)
Kod 2. Definicja treści maila
Mamy stworzoną główną część Logic Apps, ale co dalej? W jaki sposób go uruchamiać, aby móc go monitorować. Tutaj z pomocą przychodzi Azure Data Factory. W ADF możemy uruchomić Logic Apps używając jednego z dwóch rodzajów activity:
· Web Activity,
· WebHook Activity.
Jaka jest różnica między nimi i który okazał się lepszy dla tego procesu?
W naszym przypadku kluczową różnicą było to, że Web Activity działa asynchronicznie, a WebHook synchronicznie. Co to oznacza w praktyce? Web Activity po prostu uruchamia Logic Apps i nie interesuje go czy zakończył się on sukcesem czy nie. Sam fakt uruchomienia procesu traktuje jako Succeeded. I to okazało się bardzo problematyczne. Ważne jest dla nas, aby monitorować nasze procesy. Przy zastosowaniu Web Activity nie otrzymywaliśmy informacji o błędzie, gdy Logic Apps zakończył się niepowodzeniem i raport nie został wysłany.
Tu z pomocą przyszedł WebHook. W przeciwieństwie do Web Activity, WebHook czeka na odpowiedź. Dopiero, gdy cały Logic Apps zakończy się sukcesem, wtedy zwracana jest wartość Succeeded w Azure Data Factory. Natomiast samo zastosowanie WebHook w ADF pipeline nie wystarczy. Należy również poprawnie skonfigurować Logic Apps. Logic Apps musi mieć w swoim procesie kroki, które będą wysyłały odpowiednie odpowiedzi. Jeśli nie dodamy tego do naszego procesu, wtedy pipeline będzie trwał aż do czasu timeoutu jaki zostanie ustawiony. Po przekroczeniu tego czasu, pipeline zwróci wartość ‘Timed out’.
Znamy teorię, ale jak w praktyce skorzystać z WebHook Activity? Pierwszy etap to poprawna konfiguracja w Azure Data Factory.
Rys. 2. WebHook Activity w Azure Data Factory
Kluczową kwestią jest włączenie w ustawieniach ‘Report status on callback’ na True. Ta opcja pozwoli na przekazanie z poziomu Logic Apps do Azure Data Factory trzech wartości (StatusCode, Output i Error).
Rys. 3. Ustawienia WebHook – włączenie callback na True
Należy również pamiętać, aby w Body podać wartości parametrów, które mają zostać przekazane do Logic Apps. Ten krok jest kluczowy, jeśli zależy nam na przekazywaniu parametrów z poziomu Azure Data Factory.
Drugi etap to poprawna konfiguracja Logic Apps. Na końcu procesu należy dodać dwa kroki HTTP. Logic Apps musi wiedzieć co zwrócić, gdy proces się wykona lub nie. Ciekawy jest fakt, że brak dodania tych dwóch kroków spowoduje, że pipeline w ADF będzie trwał aż do momentu osiągnięcia czasu określonego w Timeout.
Zacznijmy od konfiguracji odpowiedzi, gdy Logic Apps się nie wykona. W ustawieniach należy skonfigurować ‘run after’.
Rys. 4. Konfiguracja odpowiedzi, gdy proces zakończył się niepowodzeniem.
W praktyce oznacza to zdefiniowanie odpowiedzi jaka ma zostać zwrócona, gdy poprzedni krok Logic Apps (w naszym przypadku krok ‘Send and email’) otrzyma status timed out, skipped lub failed. Każda z tych trzech opcji oznacza brak wykonania procesu, który stworzyliśmy.
Rys. 5. Konfiguracja ‘run after’ dla procesu zakończonego niepowodzeniem.
Następnie w polu URI należy wybrać Add Dynamic Content -> Expression i wpisać wartość triggerBody()[‘callBackUri’] . Istotnym elementem jest Body. Wartości Error i Output wyświetlą się w pipelinie ADF i można tu wpisać dowolną wartość. Najważniejsze jest, aby StatusCode był większy lub równy 400. Tylko w takim przypadku pipelinie w ADF rzeczywiście zwróci błąd.
Mamy już skonfigurowany krok, gdy proces nie wykona się prawidłowo. Teraz zajmijmy się zdefiniowaniem odpowiedzi jaka ma zostać zwrócona, gdy cały proces w Logic Apps zakończy się sukcesem. Tutaj również należy skonfigurować ‘run after’, ale wybierając tylko opcję ‘is successful’. Czyli co powinno się wykonać, gdy poprzedni krok ‘Send an email’ zakończony zostanie powodzeniem. Dodatkowo należy również uzupełnić URI wpisując wartość triggerBody()[‘callBackUri’].
Rys. 6. Konfiguracja odpowiedzi, gdy proces zakończył się powodzeniem
Rys. 7. Konfiguracja ‘run after’ dla procesu zakończonego powodzeniem
Stworzony w ten sposób proces nie tylko zautomatyzuje wysyłkę cyklicznego raportu, ale również umożliwia łatwe monitorowanie. Oczywistym jest, że każde zadanie wymaga indywidualnego podejścia. Jeśli ważne jest tylko uruchomienie Logic Apps i nie jest istotny status wykonania danego procesu, śmiało można użyć Web Activity. Natomiast jeśli proces ma być monitorowany i informacja o błędzie powinna zostać zwrócona do Azure Data Factory pipeline, wtedy warto skorzystać z WebHook Activity.
Joanna Bednarska
Data Engineer