Połącz aplikację z automatyzacją
Wyślij zdarzenie z aplikacji, gdy w Twoim systemie coś się wydarzy, na przykład zostanie utworzone zamówienie lub wpłynie płatność. Zdarzenie może uruchomić przebieg, kontynuować przebieg oczekujący na to zdarzenie lub anulować przebieg z pasującą regułą anulowania. Każda automatyzacja ma jeden URL zdarzeń do wszystkich trzech zastosowań.
Automations is in Early access. Your workspace permissions determine which actions you can perform.
Jeśli nie możesz otworzyć Automations ani utworzyć wersji roboczej, zobacz dostęp do obszaru roboczego i kontrola edycji.
Skonfiguruj zdarzenie uruchamiające przebieg
- Utwórz automatyzację z wyzwalaczem Event from your application.
- Ustaw Event name, na przykład order.created. Nazwy rozróżniają wielkość liter i mogą zawierać litery, cyfry, kropki, podkreślenia oraz myślniki.
- Zdefiniuj Event fields dla danych wysyłanych przez aplikację. Dla zamówienia dodaj pole tekstowe o nazwie order_id. Późniejsze kroki mogą korzystać z tych pól.
- Opublikuj automatyzację. Ekran potwierdzenia wyświetla sekcję How to start a run z adresem URL zdarzenia i przykładowym żądaniem.
Aby ponownie znaleźć szczegóły połączenia, zaznacz wyzwalacz i kliknij How to connect your application w szybkiej edycji. Rozwinięty edytor pokazuje kontrolki połączenia.
Symuluj wersję roboczą lub wykonaj opublikowaną wersję
Użyj Preview workflow z przykładowymi danymi, aby zasymulować wersję roboczą bez wysyłania wiadomości i zmieniania danych. Uruchomienie polecenia cURL, kliknięcie Send event… lub użycie Start run wykonuje opublikowaną automatyzację i może realizować rzeczywiste akcje. Zapisane i niezapisane zmiany wersji roboczej nie mają wpływu na te przebiegi.
Opublikuj automatyzację przed wysłaniem zdarzeń. Jeśli nie ma opublikowanej wersji, żądanie jest natychmiast odrzucane; zdarzenie nie trafia do kolejki ani nie jest zapisywane na później. Przykłady w edytorze mogą odzwierciedlać zmiany w wersji roboczej, więc opublikuj je przed wysłaniem danych, które na nich polegają.
Skopiuj URL i wyślij zdarzenie
Użyj Copy request, aby uzyskać polecenie cURL zawierające URL, nagłówki i przykładowe ciało żądania. Zastąp przykładowe wartości danymi ze swojej aplikacji.
URL zawiera identyfikatory obszaru roboczego i automatyzacji:
Przykład kodu
POST https://<your-regional-api-host>/v1/hooks/automations/<workspace-id>/<automation-id>Użyj pełnego URL skopiowanego z dashboardu. Nie potrzebujesz nagłówka X-Workspace-Id. Bieżąca opcja uwierzytelniania to No authentication: każdy, kto ma ten URL, może wysyłać zdarzenia. Przechowuj go w konfiguracji serwera.
Dla automatyzacji skonfigurowanej na order.created ustaw AUTOMATION_EVENT_URL na skopiowany URL i wyślij:
Przykład kodu
curl --request POST "$AUTOMATION_EVENT_URL" \
--header 'Content-Type: application/json' \
--data '{
"type": "order.created",
"data": { "order_id": "order_123" }
}'Ustaw type na skonfigurowaną nazwę zdarzenia, a data na obiekt odpowiadający polom zdarzenia. Możesz też podać occurred_at jako znacznik czasu RFC 3339; domyślnie przyjmuje czas nadejścia zdarzenia.
Odpowiedź 202 Accepted z status: "queued" potwierdza, że zdarzenie trafiło do kolejki. Bird generuje identyfikator zdarzenia i zwraca go jako event_id. Otwórz kartę Runs automatyzacji, aby sprawdzić wykonanie. Przyjęcie do kolejki nie potwierdza, że zdarzenie pasowało do wyzwalacza ani że przebieg się rozpoczął.
Możesz też użyć Send event… w dashboardzie, aby przesłać przykład bez terminala. Wysyła to rzeczywiste zdarzenie.
Kontynuuj przebieg oczekujący na zdarzenie
Krok oczekiwania korzysta z tego samego URL automatyzacji co wyzwalacz. Nazwa zdarzenia i subject_key identyfikują, co się wydarzyło i który przebieg powinien je otrzymać.
- W Automation settings włącz Skip overlapping runs i Use a business key. Ustaw Business key na wartość identyfikującą zamówienie, fakturę lub inny obiekt. Dla przykładu z zamówieniem użyj wyrażenia trigger.data.data.order_id.
- Dodaj Wait for application event i skonfiguruj nazwę zdarzenia, pola zdarzenia oraz limit czasu. Na przykład czekaj na order.paid z polem tekstowym payment_id.
- Opublikuj, wyślij zdarzenie startowe i poczekaj, aż jego przebieg pojawi się w zakładce Runs.
- Wyślij zdarzenie kontynuujące na ten sam URL, z subject_key równym kluczowi biznesowemu przebiegu:
Przykład kodu
{
"type": "order.paid",
"subject_key": "order_123",
"data": { "payment_id": "payment_456" }
}subject_key to wartość klucza biznesowego, na przykład order_123; to nie jest identyfikator zdarzenia ani identyfikator uruchomienia. Rozwinięty widok połączenia w kroku oczekiwania zawiera wskazówki dotyczące skonfigurowanego klucza.
Pasujące zdarzenie może zostać przechwycone po rozpoczęciu przebiegu, nawet zanim dotrze on do kroku oczekiwania. Zdarzenia przetworzone przed istnieniem pasującego przebiegu nie są zapisywane dla przyszłego przebiegu. Oczekiwanie z filtrem jest kontynuowane tylko wtedy, gdy pola zdarzenia i filtr jednocześnie pasują. Przebieg podąża ścieżką limitu czasu, jeśli przed upływem terminu nie zostanie przetworzone żadne kwalifikujące się zdarzenie.
Reguły anulowania w Automation settings również korzystają z tego URL. Reguła może obejmować wszystkie aktywne przebiegi automatyzacji lub przebieg pasujący do subject_key. Skonfiguruj filtr, aby zawęzić, które przebiegi są anulowane. Anulowanie nie może cofnąć akcji, która już została wykonana.
Opublikowane wersje i wstrzymane automatyzacje
Nowe przebiegi korzystają z wersji aktywnej w momencie przetwarzania zdarzenia. Istniejące przebiegi zachowują swoją pierwotną wersję, w tym pola zdarzenia i warunki oczekiwania. Opublikowanie zmienionego formatu zdarzenia nie aktualizuje przebiegów, które już się rozpoczęły.
Wstrzymanie opublikowanej automatyzacji zatrzymuje nowe przebiegi. Zdarzenia nadal mogą kontynuować lub anulować istniejące przebiegi, gdy automatyzacja jest wstrzymana.
Obsługa dostarczania i ponawiania
Zdarzenia są przetwarzane asynchronicznie i mogą być ponawiane lub przetwarzane w innej kolejności. Poczekaj, aż przebieg startowy zaistnieje, zanim wyślesz zdarzenie kontynuujące. occurred_at zdarzenia nie kontroluje kolejności przetwarzania, nie wydłuża oczekiwania ani nie zapobiega przekroczeniu limitu czasu.
Ochrona przed ponownym przetworzeniem jest ograniczona czasowo. Jeśli rekordy ponowień wygasną lub zostaną utracone, zdarzenie może zostać przetworzone ponownie, potencjalnie względem nowszej wersji lub innego aktywnego przebiegu. Zaprojektuj aplikację tak, aby tolerowała zduplikowane zdarzenia.
Aby włączyć ochronę przed powtórzeniami, podaj Idempotency-Key przy pierwszej próbie, a następnie użyj go ponownie z tym samym adresem URL i niezmienioną treścią żądania przy kolejnych próbach. Dla każdego nowego żądania użyj nowego klucza. Powtórzone żądanie zwraca ten sam event_id. Przewodnik po idempotentności opisuje ograniczone okno powtórzeń i odpowiedzi dotyczące konfliktów.
Rozwiązywanie problemów ze zdarzeniem
- Żądanie zwraca 4xx: Sprawdź szczegóły błędu w odpowiedzi, URL oraz wymagane pola type i obiekt data. Wyślij Content-Type: application/json. Całe ciało żądania musi mieścić się w 25 KB (25 000 bajtów); większe ciała zwracają 413.
- Automatyzacja nie została opublikowana: Opublikuj ją przed wysłaniem zdarzenia. Odrzucone zdarzenie nie jest zachowywane; wyślij nowe żądanie po opublikowaniu.
- Żądanie zwraca 202, ale żaden przebieg się nie uruchamia: Sprawdź, czy automatyzacja jest aktywna, nazwa zdarzenia pasuje do jej wyzwalacza, a dane odpowiadają opublikowanym polom zdarzenia. Ochrona przed nakładaniem się może pominąć nowy przebieg, gdy inny jest aktywny. Sprawdź też miesięczny limit przebiegów; uruchomienia pominięte po osiągnięciu limitu nie są kolejkowane na następny miesiąc.
- Przebieg zatrzymał się na kroku oczekiwania: Sprawdź nazwę zdarzenia, dokładny klucz biznesowy, pola danych, filtr i limit czasu. Użyj formatu zdarzenia z pierwotnej opublikowanej wersji przebiegu.
- Ponowienie zwraca konflikt: Ponów żądanie z oryginalnym kluczem i niezmienionym żądaniem. Jeśli chcesz wysłać inne zdarzenie, użyj nowego klucza.
Koperta żądania jest sprawdzana przed dodaniem do kolejki. Dane zdarzenia są sprawdzane względem wyzwalacza, oczekiwania i reguł anulowania podczas przetwarzania, więc zdarzenie w kolejce może nie pasować do żadnego z nich.
Następne kroki
- Otwórz Automations, aby skonfigurować i opublikować workflow.
- Obsługuj idempotentne ponawianie w swojej aplikacji.
- Czekaj na zdarzenie w działającym workflow.
- Przeglądaj przewodniki Automations.
Powiązane zasoby
Kontynuuj z dokumentacją, przewodnikami i przykładami dotyczącymi tego tematu. Zasoby są w języku angielskim.