Poniżej znajduje się prosty przewodnik, który pomoże nadawcom poczuć się swobodnie podczas tworzenia webhooka wydarzeń Bird i korzystania z danych za pomocą infrastruktury w AWS.
W czasie rzeczywistym webhooki zdarzeń Bird są niezwykle cennym narzędziem umożliwiającym nadawcom automatyczne przesyłanie danych do ich systemów. Może to napędzać automatyzację procesu poprzez aktualizację list mailingowych, inicjowanie zautomatyzowanych ścieżek e-mailowych lub wypełnianie wewnętrznych pulpitów nawigacyjnych. Choć te same dane zdarzeń można uzyskać za pośrednictwem interfejsu użytkownika Bird za pomocą Event Search lub programowo, korzystając z Events API Bird, ograniczenia dotyczące liczby rekordów zwracanych w jednym żądaniu lub limity szybkości nałożone na punkt końcowy API mogą sprawić, że obie te metody będą restrykcyjne dla dużych i zaawansowanych nadawców.
Webhooki zdarzeń w czasie rzeczywistym umożliwiają nadawcy skonfigurowanie punktu końcowego, do którego Bird przesyła dane, a dane te mogą być konsumowane bez potrzeby planowania zadań cron, które pobierają dane. Istnieją również kompromisy logistyczne przy pobieraniu danych w porównaniu do tego, gdy dane są przesyłane do Ciebie, na przykład konieczność określenia, jaki przedział czasowy i parametry należy zastosować dla każdego żądania API. Jeśli okresy czasowe nie są idealnie zsynchronizowane, ryzykujesz utratę danych, a jeśli okresy te nakładają się, musisz poradzić sobie z powielonymi danymi. Dzięki webhookom w czasie rzeczywistym dane zdarzeń są po prostu przesyłane do Twojego punktu końcowego, gdy tylko stają się dostępne w Bird.
Mimo że korzyści wynikające z otrzymywania danych zdarzeń w czasie rzeczywistym w celu napędzania procesów automatyzacji mogą być od razu zrozumiałe dla wielu nadawców, rzeczywisty proces wdrażania i konsumowania webhooków może być onieśmielający. Może to być szczególnie prawdziwe, jeśli nie jesteś zaznajomiony z technicznymi aspektami tworzenia punktu końcowego i programowego zarządzania danymi. Dostępne są usługi, które będą konsumować dane webhooks z Bird i automatycznie ETL do Twojej bazy danych – przykładem może być StitchData, o którym pisaliśmy na naszym blogu w przeszłości. Jeśli jednak chcesz mieć większą kontrolę nad procesem, możesz łatwo zbudować komponenty samodzielnie. Poniżej znajduje się prosty przewodnik, który ma pomóc nadawcom poczuć się komfortowo przy tworzeniu webhooka zdarzeń Bird i konsumowaniu danych przy użyciu infrastruktury w AWS.
Konfigurowanie Webhook Target Endpoint
Kiedy tworzone jest zdarzenie Bird, chcemy, aby dane tego zdarzenia były strumieniowane w czasie rzeczywistym do punktu końcowego w AWS, abyśmy mogli je konsumować i wykorzystywać programowo. Dane zostaną wysłane z Bird do docelowego punktu końcowego, który przekaże ładunek do funkcji lambda, która przetworzy i zapisze dane w wiadrze S3. Wysokopoziomowy diagram opisanego przepływu danych można zobaczyć poniżej:
Aby wdrożyć ten przepływ pracy, zbudujmy go w odwrotnej kolejności, zaczynając od utworzenia wiadra S3, w którym będziemy przechowywać nasze dane zdarzeń, a następnie cofniemy się - dodając każdy komponent, który zasila to, co zbudowaliśmy.
Utwórz Wiadro S3, aby Przechowywać Dane Webhooku
Zanim utworzymy nasz load balancer do akceptacji danych lub naszą funkcję lambda do przechowywania danych, musimy najpierw utworzyć nasz wiadro S3, gdzie dane będą przechowywane. Aby to zrobić, przejdź do usługi S3 w AWS i naciśnij „Create Bucket”. Zostaniesz poproszony o przypisanie nazwy do swojego wiadra i ustawienie regionu - upewnij się, że używasz tego samego regionu co swój ALB i funkcja lambda. Po utworzeniu wiadra S3, będzie ono puste – jeśli chcesz zorganizować dane wewnątrz folderu, możesz teraz utworzyć zamierzony katalog lub katalog zostanie utworzony, gdy twoja funkcja lambda zapisze plik. W tym przykładzie nazwaliśmy nasze wiadro S3 „bird-webhooks” i utworzyliśmy folder nazwany „B Event Data”, aby przechowywać nasze dane zdarzeń – zobaczysz te nazwy odniesione w naszej funkcji lambda poniżej.
Utwórz Funkcję Lambda do Konsumcji Danych
Faktyczne przetwarzanie i przechowywanie danych będzie wykonywane przez funkcję lambda wywołaną przez nasz load balancer aplikacji (ALB).
Pierwszym krokiem jest utworzenie twojej funkcji lambda poprzez nawigację do usługi Lambda w AWS i kliknięcie „Create Function”. Zostaniesz poproszony o przypisanie nazwy do swojej funkcji lambda i wybór, w którym języku programowania napisać swoją funkcję. W tym przykładzie używamy Pythona jako języka wykonawczego.
Teraz musimy opracować naszą funkcję lambda. Na chwilę załóżmy, że nasz load balancer aplikacji został skonfigurowany i przekazuje ładunek webhooku do naszej funkcji lambda – lambda otrzyma ładunek zawierający pełne nagłówki i ciało. Ładunek jest przekazywany do naszej funkcji lambda przy użyciu obiektu „event” jako słownika. Możesz odnieść się niezależnie do nagłówków i ciała ładunku, uzyskując dostęp do obiektów „headers” i „body” w ładunku. W tym przykładzie po prostu przeczytamy nagłówek „x-messagesystems-batch-id”, gdzie batch ID jest unikalną wartością stworzoną przez Bird dla partii webhooku, i użyjemy go jako nazwy pliku przy zapisaniu ciała jako pliku płaskiego w S3; jednakże możesz chcieć dodać dodatkową funkcjonalność, taką jak sprawdzanie uwierzytelnienia czy obsługę błędów, w miarę potrzeb.
Podczas przechowywania ładunku do pliku płaskiego w S3, musimy zdefiniować nazwę wiadra S3, lokalizację i nazwę pliku, w którym zostaną przechowane dane ładunku. W naszej przykładowej funkcji lambda robimy to w ramach funkcji „store_batch”. W tym przykładzie zamierzamy przechowywać całą partię jako jeden plik, co pomaga zapewnić, że dane są zebrane i przechowywane zanim połączenie HTTP między Bird a twoim punktem końcowym wygaśnie. Mimo że możesz dostosować ustawienia czasu oczekiwania połączenia na twoim load balancerze, nie ma gwarancji, że połączenie nie wygaśnie po stronie transmisji (w tym przypadku Bird) lub że połączenie nie zostanie zakończone przed zakończeniem wykonywania twojej funkcji lambda. Jest to najlepsza praktyka, aby zachować funkcję konsumującą możliwie jak najwydajniejszą i rezerwować działania przetwarzania danych dla procesów dółstrumieniowych, jeśli to możliwe – takich jak konwersja batched JSON-formatted payload na plik CSV czy ładowanie danych zdarzeń do bazy danych.
Ważne jest, aby zauważyć, że możesz potrzebować zaktualizować uprawnienia dla swojej funkcji lambda. Twoja rola wykonawcza będzie potrzebować uprawnień PutObject i GetObject dla S3. Jest to najlepsza praktyka, aby egzekwować zasadę najmniejszych przywilejów, więc polecam ustawienie tych uprawnień wyłącznie dla wiadra S3, w którym ładunki webhooku będą przechowywane.
Przykład naszej funkcji konsumenta lambda można znaleźć tutaj.
Krótka uwaga o batch ID: Bird grupuje zdarzenia w jeden ładunek, gdzie każda partia może zawierać od 1 do 350 lub więcej rekordów zdarzeń. Partia otrzyma unikalny batch ID, który można wykorzystać do przeglądania statusu partii, korzystając z Event Webhooks API lub w ramach swojego konta Bird, klikając strumień webhooku i wybierając „Batch Status.” W przypadku, gdy ładunek webhooku nie mógł zostać dostarczony, na przykład podczas wygaśnięcia połączenia, Bird automatycznie spróbuje ponownie przesłać partię przy użyciu tego samego batch ID. Może się to zdarzyć, gdy twoja funkcja lambda działa blisko maksymalnego czasu rundowego 10 sekund i jest to powód, aby optymalizować funkcję konsumenta w celu skrócenia czasu wykonania.
Aby obsłużyć wszystkie działania przetwarzania danych, zalecam utworzenie osobnej funkcji lambda, która wykonuje się za każdym razem, gdy zostanie utworzony nowy plik w wiadrze S3 – w ten sposób przetwarzanie danych odbywa się asynchronicznie w stosunku do transmisji danych i nie ma ryzyka utraty danych na skutek zakończonego połączenia. Omawiam funkcję przetwarzającą lambda w późniejszej części.
Utwórz Load Balancer Aplikacji
Aby otrzymać ładunek webhooku, musimy zapewnić punkt końcowy do przesyłania ładunków. Robimy to, tworząc load balancer aplikacji w AWS przez nawigację do EC2 > Load Balancers i kliknięcie „Create Load Balancer”. Zostaniesz poproszony o wybór, jaki rodzaj load balancera chcesz utworzyć – w tym przypadku chcemy utworzyć load balancer aplikacji. Musimy używać load balancer aplikacji (ALB) do zbudowania naszego konsumenta, ponieważ zdarzeniowe webhoksy będą wysyłane jako żądanie HTTP, a ALB są używane do routingu żądań HTTP w ramach AWS. Moglibyśmy wdrożyć Bramę HTTP jako alternatywę; jednakże używamy ALB w tym projekcie, ponieważ jest on lżejszy i bardziej opłacalny niż Brama HTTP. Ważne jest, aby zauważyć, że jeśli zdecydujesz się używać Bramę HTTP, format zdarzeń może być inny niż w przypadku ALB, i dlatego twoja funkcja lambda będzie musiała obsługiwać obiekt żądania odpowiednio.
Po utworzeniu ALB będziesz poproszony o przypisanie nazwy do swojego ALB i skonfigurowanie schematu i ustawień dostępności/bezpieczeństwa – ponieważ planujemy otrzymywać dane zdarzeń z zewnętrznego źródła (Bird), chcemy, aby nasz ALB był internet-faced. Pod „Listeners and routing,” ALB powinno nasłuchiwać do HTTPS na porcie 443, i chcemy utworzyć Grupę Docelową, która wskazuje naszą funkcję lambda tak, aby nasz ALB przekazywał przychodzące żądania do funkcji konsumpcyjnej lambda, którą utworzyliśmy powyżej. Musisz również upewnić się, że grupa bezpieczeństwa ma pozwolenie na akceptację ruchu przez port 443.
Utwórz Rekord DNS dla Load Balanceru
Aby ułatwić nam korzystanie z naszego ALB jako punktu końcowego, utworzymy rekord A w DNS, który wskazuje nasz ALB. Do tego możemy użyć usługi AWS Route 53 (lub obecnego dostawcy DNS) i utworzyć rekord A dla nazwy hosta, którą chcesz używać dla swojego punktu końcowego (np. spevents.<your_domain>). Rekord A powinien być skonfigurowany, aby wskazywał na nasz utworzony ALB. Jeśli używasz Route 53 do zarządzania rekordami DNS, możesz bezpośrednio odnosić się do instancji ALB, włączając „Alias” i wybierając ALB; w przeciwnym razie, jeśli używasz zewnętrznego dostawcy DNS, powinieneś wskazać rekord A na publiczny adres IP instancji ALB.
Zalecam użycie narzędzia takiego jak Postman, aby przetestować, czy wszystko zostało skonfigurowane poprawnie przed włączeniem webhooku Bird. Możesz złożyć żądanie POST do swojego punktu końcowego i potwierdzić, że otrzymano odpowiedź. Jeśli twoje żądanie POST nie zwraca odpowiedzi, może być konieczne, aby ponownie sprawdzić, czy twój ALB słucha na poprawnym porcie.
Utwórz Webhook w Bird
Teraz jesteśmy gotowi do utworzenia webhooku w Bird i użycia nazwy hosta zdefiniowanej przez rekord A jako naszego docelowego punktu końcowego. Aby utworzyć webhook, przejdź do Sekcja Webhooków w swoim koncie Bird i kliknij „Create Webhook”. Zostaniesz poproszony o przypisanie nazwy do swojego webhooku i podanie docelowego URL – cel powinien być nazwą hosta rekordu A, który utworzyłeś wcześniej. Zwróć uwagę, że docelowy URL może wymagać włączenia „HTTPS://” do URL.
Po zakończeniu, zweryfikuj, że wybrano odpowiednie subkonto i zdarzenia, a następnie naciśnij „Create Webhook”, aby zapisać swoją konfigurację. Dane zdarzeń dla wszystkich wybranych typów zdarzeń będą teraz strumieniowane do naszego docelowego URL i będą konsumowane przez nasz ALB do przetwarzania dołstawnego.
