
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.
Bird’s real-time event webhooks są niezwykle cennym narzędziem dla nadawców do automatycznego przesyłania danych do ich systemów. Może to wspierać dalszą automatyzację, taką jak aktualizowanie list mailingowych, uruchamianie zautomatyzowanych ścieżek e-mail lub wypełnianie wewnętrznych pulpitów nawigacyjnych. Chociaż te same dane o wydarzeniach można uzyskać przez interfejs Bird UI za pomocą Event Search, lub programowo, wykorzystując Bird Events API, ograniczenia dotyczące liczby rekordów zwracanych w jednym żądaniu lub limity rate nałożone na punkt końcowy API mogą sprawić, że obie te metody będą restrykcyjne dla dużych i zaawansowanych nadawców.
Real-time event webhooks umożliwiają nadawcy skonfigurowanie punktu końcowego, do którego Bird przesyła dane, co oznacza, że dane mogą być konsumowane bez konieczności planowania zadań cron do ich pobierania. Istnieją również kompromisy logistyczne przy pobieraniu danych w porównaniu do ich przesyłania, takie jak konieczność ustalenia, jaki okres czasu i parametry zastosować dla każdego żądania API. Jeśli okresy czasowe nie są idealnie zgrane, istnieje ryzyko utraty danych, a jeśli zachodzą na siebie, konieczne jest radzenie sobie z duplikatami rekordów danych. Dzięki webhookom w czasie rzeczywistym dane o wydarzeniach są po prostu przesyłane do Twojego punktu końcowego, gdy tylko stają się dostępne w Bird.
Chociaż korzyści z otrzymywania danych o wydarzeniach w czasie rzeczywistym w celu wspierania dalszych procesów automatyzacji mogą być natychmiast 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 jesteś nieznajomy z technicznymi komponentami tworzenia punktu końcowego i programowego zarządzania danymi. Dostępne są usługi, które będą konsumować dane webhooków Bird i ETL do Twojej bazy danych automatycznie – przykładem może być StitchData, o którym pisaliśmy na blogu w przeszłości. Jednakże, jeśli 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 w poczuciu komfortu podczas tworzenia webhooków zdarzeń Bird i konsumowania danych przy użyciu infrastruktury w AWS.
Konfigurowanie Webhook Target Endpoint
Kiedy tworzone jest zdarzenie Bird, chcemy, aby dane dotyczące tego zdarzenia były przesyłane w czasie rzeczywistym do punktu końcowego w AWS, abyśmy mogli te dane wykorzystać programowo. Dane będą wysyłane z Bird do docelowego punktu końcowego, który prześle ładunek do funkcji lambda, która przetworzy i przechowa dane w wiadrze S3. Ogólny schemat opisany 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, gdzie będziemy przechowywać dane zdarzeń, a następnie będziemy dodawać każdy element składowy, który będzie się odnosił do tego, co już zbudowaliśmy.
Utwórz wiadro S3 do przechowywania danych webhook
Zanim utworzymy nasz load balancer do akceptacji danych, lub naszą funkcję lambda do przechowywania danych, musimy najpierw utworzyć nasze wiadro S3, gdzie dane będą przechowywane. Podczas gdy S3 zapewnia doskonałą pamięć dla danych webhook, organizacje, które również używają baz danych PostgreSQL do przetwarzania zdarzeń, powinny wdrożyć odpowiednie procedury backupu i przywracania w celu ochrony swoich danych strukturalnych wraz z ich strategią przechowywania S3. Aby tego dokonać, przejdź do usługi S3 w AWS i naciśnij „Create Bucket”. Zostaniesz poproszony o nadanie nazwy swojemu wiadru i ustawienie regionu – upewnij się, że używasz tego samego regionu co twój ALB i funkcja lambda. Kiedy twoje wiadro S3 jest utworzone, będzie 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 o nazwie „B Event Data”, aby przechowywać dane o zdarzeniach – zobaczysz te nazwy odniesione w naszej funkcji lambda poniżej.
Utwórz funkcję Lambda do konsumpcji danych
Rzeczywiste przetwarzanie i przechowywanie danych będzie realizowane przez funkcję lambda, która jest wywoływana przez nasz application load balancer (ALB).
Pierwszym krokiem jest utworzenie funkcji lambda, przechodząc do usługi Lambda w AWS i klikając „Create Function”. Zostaniesz poproszony o nadanie nazwy swojej funkcji lambda i wybór języka programowania, w którym napiszesz swoją funkcję. W tym przykładzie używamy Pythona jako języka wykonania.
Teraz musimy opracować naszą funkcję lambda. Na chwilę załóżmy, że nasz application load balancer został skonfigurowany i przekazuje ładunek webhook do naszej funkcji lambda – lambda otrzyma ładunek zawierający pełne nagłówki i treść. Ładunek jest przekazywany do naszej funkcji lambda za pomocą obiektu „event” jako słownik. Możesz odnieść się do nagłówków i treści ładunku niezależnie, uzyskując dostęp do obiektów „headers” i „body” w obrębie ładunku. W tym przykładzie zamierzamy po prostu odczytać nagłówek „x-messagesystems-batch-id”, gdzie batch ID jest unikalną wartością utworzoną przez Bird dla partii webhook, i użyć go jako nazwy pliku, gdy przechowujemy treść jako płaski plik w S3; jednak możesz dodać dodatkową funkcjonalność, taką jak kontrole autoryzacji lub obsługę błędów, w razie potrzeby.
Podczas przechowywania ładunku do płaskiego pliku w S3, będziemy musieli zdefiniować nazwę wiadra S3, lokalizację i nazwę pliku, gdzie dane ładunku będą przechowywane. W naszym przykładowej funkcji lambda robimy to w funkcji „store_batch”. W tym przykładzie zamierzamy przechowywać całą partię jako jeden plik, co pomaga zapewnić, że dane zostaną zebrane i przechowane przed wygaśnięciem połączenia HTTP między Bird a twoim punktem końcowym. Chociaż możesz dostosować ustawienia limitu czasu połączenia na swoim load balancer, 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. Zaleca się, aby funkcja konsumująca była jak najbardziej wydajna i rezerwowała działania przetwarzania danych dla procesów poniżej, tam gdzie to możliwe – takich jak konwersja batched JSON-formatted payload na plik CSV, lub ładowanie danych zdarzenia do bazy danych.
Ważne jest, aby pamiętać, że możesz potrzebować zaktualizować uprawnienia dla swojej funkcji lambda. Twoja rola wykonawcza będzie potrzebowała uprawnień PutObject i GetObject dla S3. Zaleca się stosowanie zasady najmniejszych przywilejów, dlatego zalecam ustawienie tych uprawnień tylko dla wiadra S3, gdzie ładunki webhook będą przechowywane.
Przykład naszej funkcji lambda konsumującej można znaleźć tutaj.
Jako szybka uwaga dotycząca batch ID: Bird będzie przekształcać zdarzenia w jeden ładunek, gdzie każda partia może zawierać od 1 do 350 lub więcej rekordów zdarzeń. Partii zostanie przypisany unikalny batch ID, który można wykorzystać do przeglądania statusu partii, używając Event Webhooks API lub w swoim koncie Bird, klikając strumień webhook i wybierając „Batch Status”. W przypadku, gdy nie można dostarczyć ładunku webhook, na przykład w przypadku wygaśnięcia połączenia, Bird automatycznie ponowi próbę partii, używając tego samego batch ID. Może się to zdarzyć, gdy twoja funkcja lambda działa blisko maksymalnego czasu podróży w obie strony wynoszącego 10 sekund i jest powodem, dla którego należy optymalizować funkcję konsumującą, aby skrócić czas wykonania.
Aby obsłużyć wszystkie działania przetwarzania danych, zalecam utworzenie osobnej funkcji lambda, która wykonuje się za każdym razem, gdy na wiadrze S3 zostanie utworzony nowy plik – w ten sposób przetwarzanie danych jest wykonywane asynchronicznie w stosunku do transmisji danych, i nie ma ryzyka utraty danych z powodu zakończonego połączenia. Opisuję funkcję przetwarzającą lambda w późniejszej sekcji.
Utwórz Application Load Balancer
Aby otrzymać payload webhook, musimy podać punkt końcowy, do którego wysyłane będą ładunki. Robimy to, tworząc application load balancer w AWS, przechodząc do EC2 > Load Balancers i klikając „Create Load Balancer”. Zostaniesz poproszony o wybór, jaki typ load balancera chcesz utworzyć – w tym przypadku chcemy utworzyć application load balancer. Musimy użyć application load balancer (ALB) do budowy naszego konsumera, ponieważ zdarzenia webhook będą wysyłane jako żądanie HTTP, a ALB są używane do routingu żądań HTTP w AWS. Można wdrożyć HTTP Gateway jako alternatywę, jednak używamy ALB do tego projektu, ponieważ jest to bardziej lekkie i kosztowo efektywne niż HTTP Gateway. Ważne jest, aby pamiętać, że jeśli zdecydujesz się używać HTTP Gateway, format zdarzenia może być inny niż w przypadku ALB, i wówczas twoja funkcja lambda będzie musiała obsłużyć obiekt żądania odpowiednio.
Po utworzeniu ALB zostaniesz poproszony o przypisanie nazwy dla ALB i skonfigurowanie schematu oraz ustawień dostępu/bezpieczeństwa – ponieważ planujemy otrzymywać dane zdarzeń z zewnętrznego źródła (Bird), chcemy, aby nasz ALB był widoczny w Internecie. Pod „Listeners and routing,” ALB powinien nasłuchiwać na HTTPS na porcie 443, i chcemy utworzyć Target group wskazującą na naszą funkcję lambda, aby nasz ALB przekierowywał przychodzące żądania do funkcji konsumującej lambda, którą stworzyliśmy wcześniej. Musisz także upewnić się, że grupa bezpieczeństwa ma pozwolenie na akceptowanie ruchu przez port 443.
Utwórz rekord DNS dla Load Balancer
Aby ułatwić korzystanie z ALB jako punktu końcowego, stworzymy rekord A w DNS, który wskazuje na 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órej chcesz używać dla swojego punktu końcowego (np. spevents.<twoja_domena>). Pracując z DNS na dużą skalę na AWS, bądź świadomy, że istnieją nieudokumentowane limity DNS, które mogą wpływać na aplikacje o dużej przepustowości, szczególnie te obsługujące duże ilości ruchu wychodzącego, jak systemy dostarczania wiadomości email. Rekord A powinien być skonfigurowany, aby wskazywać na ALB, który stworzyliśmy. Jeśli korzystasz z Route 53 do zarządzania rekordami DNS, możesz bezpośrednio odnieść 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 do testowania, czy wszystko zostało poprawnie skonfigurowane przed włączeniem webhook Bird. Możesz wykonać żądanie POST do swojego punktu końcowego i potwierdzić, że odpowiedź została otrzymana. Jeśli twoje żądanie POST nie zwróci odpowiedzi, możesz potrzebować podwójnie sprawdzić, czy twój ALB nasłuchuje na właściwym porcie.
Utwórz Webhook Bird
Teraz jesteśmy gotowi, aby utworzyć webhook w Bird i użyć nazwy hosta zdefiniowanej przez rekord A powyżej jako naszego docelowego punktu końcowego. Aby utworzyć webhook, przejdź do Webhooks section w swoim koncie Bird i kliknij „Create Webhook”. Zostaniesz poproszony o nadanie nazwy swojemu webhook i podanie docelowego URL – celem powinien być nazwa hosta rekordu A utworzonego wcześniej. Zwróć uwagę, że docelowy URL może wymagać włączenia „HTTPS://” w adresie URL.
Po zakończeniu, upewnij się, że wybrany został właściwy subkonto i zdarzenia, a następnie naciśnij „Create Webhook” aby zapisać konfigurację. Teraz dane zdarzeń dla wszystkich wybranych typów zdarzeń będą przesyłane strumieniowo do naszego docelowego URL i konsumowane przez nasz ALB do dalszego przetwarzania.