Support Hub/API & Integrations/Webhooki a odpytywanie: jak dane biometryczne w czasie…
Translated from the English article and reviewed by a person. Read the English original
Developer

Webhooki a odpytywanie: jak dane biometryczne w czasie rzeczywistym powinny trafiać na Twój serwer

Webhooki a odpytywanie: jak dane biometryczne w czasie rzeczywistym powinny trafiać na Twój serwer

Każda integracja danych biometrycznych musi odpowiedzieć na jedno podstawowe pytanie: jak skan przy drzwiach staje się rekordem w Twoim systemie? Istnieją dwa sposoby. Serwer może cyklicznie pytać urządzenie, czy wydarzyło się coś nowego, czyli odpytywać (polling). Albo system może powiadomić serwer w chwili, gdy coś się wydarzy, czyli wysłać webhook. W przypadku danych o obecności i dostępie wybór między webhookami a odpytywaniem wpływa na świeżość danych, obciążenie urządzeń i sieci oraz na niezawodność rekordów. Ten przewodnik wyjaśnia oba podejścia prostym językiem, pokazuje, dlaczego webhooki są lepszym domyślnym wyborem dla danych biometrycznych, opisuje budowę niezawodnego odbiornika webhooków i wyjaśnia, gdzie odpytywanie wciąż ma zastosowanie.

01 · Pobieranie a wysyłanie

Dwa sposoby przesyłania danych

Wyobraź sobie, że czekasz na ważną paczkę. Możesz co pięć minut podchodzić do drzwi wejściowych, żeby sprawdzić, czy już przyjechała. Możesz też czekać, aż zadzwoni dzwonek. Oba sposoby doprowadzą do odbioru paczki. Pierwszy generuje wiele zbędnych wyjść i i tak może oznaczać spóźnienie o nawet pięć minut. Drugi informuje Cię w chwili, gdy paczka dotrze.

Na tym polega różnica między odpytywaniem a webhookami.

Odpytywanie: Twój serwer ciągle pyta

Twój serwer

Pyta: czy są nowe skany od ostatniego razu?

→

Urządzenie lub system

Odpowiada: nic nowego

→

Czekaj

Odczekaj interwał odpytywania

→

Powtórz

Pytaj ponownie, znowu i znowu, przez cały dzień

Webhook: system informuje Twój serwer

Skan pracownika

Zweryfikowany skan odcisku palca, twarzy lub karty

→

Gateway

Natychmiast wysyła zdarzenie na Twój adres URL webhooka

→

Twój serwer

Odbiera zdarzenie i odsyła potwierdzenie done

→

Gotowe

Bez czekania i bez zbędnych żądań

Odpytywanie Webhooki
Kto inicjuje rozmowę Twój serwer System posiadający dane
Kiedy dane docierają Przy kolejnym odpytaniu, nawet o cały interwał za późno Natychmiast po skanie
Żądania, gdy nic się nie dzieje Ciągłe, z których większość jest pusta Brak
Obciążenie urządzeń i sieci Stałe, niezależnie od aktywności Tylko wtedy, gdy jest coś do wysłania
Złożoność po Twojej stronie Śledzenie tego, co już zostało pobrane Odbieranie zdarzeń i ich potwierdzanie

02 · Ukryte koszty

Dlaczego odpytywanie ma problemy z danymi biometrycznymi

Odpytywanie sprawdza się w przypadku danych, które zmieniają się powoli lub gdy opóźnienie nie ma znaczenia. Dane o obecności i dostępie biometrycznym są odwrotnością tego. Powstają w krótkich, intensywnych seriach na początku i końcu zmiany, przez większość pozostałego czasu są ciche, a często potrzebne są natychmiast.

Opóźnienie jest wbudowane

Przy odpytywaniu maksymalne opóźnienie zawsze równa się interwałowi odpytywania. Skan, który nastąpi sekundę po zapytaniu, czeka na cały interwał, zanim serwer go zobaczy.

Interwał odpytywania Maksymalne opóźnienie, zanim system to zauważy Wystarczające dla
Co 24 godziny Do pełnego dnia Tylko miesięczne wynagrodzenia
Co godzinę Do 60 minut Raporty dzienne
Co 5 minut Do 5 minut Większość pulpitów, nie alerty
Co minutę Do 60 sekund Niemal czas rzeczywisty, przy dużym koszcie żądań
Webhook Brak opóźnienia odpytywania Dane na żywo, powiadomienia i automatyzacje

Większość żądań idzie na marne

Aby zbliżyć się do czasu rzeczywistego, odpytujesz częściej. Jednak większość tych żądań nie zwraca niczego. Odpytywanie jednego urządzenia co minutę oznacza 1440 żądań na urządzenie dziennie. Przy 50 urządzeniach daje to 72 000 żądań dziennie, z których większość zadaje pytanie, na które odpowiedzią jest „nic nowego”. Każde z tych żądań zużywa przepustowość sieci i czas przetwarzania w urządzeniu.

Śledzenie staje się kruche

Integracja oparta na odpytywaniu musi pamiętać, co już pobrała, zwykle zapisując czas lub pozycję ostatniego widzianego rekordu. Jeśli ten znacznik jest błędny, z powodu restartu, różnicy zegarów między serwerem a urządzeniem lub rekordów zapisanych, gdy urządzenie było offline, integracja albo pominie skany, albo zaimportuje je dwukrotnie. Te problemy są ciche i często ujawniają się dopiero przy sporze dotyczącym wynagrodzeń.

Z każdą lokalizacją jest trudniej

Przy jednym urządzeniu odpytywanie jest łatwe do opanowania. Przy kilkudziesięciu urządzeniach w kilku lokalizacjach i różnych markach, każde z własnym połączeniem, własnym interwałem i własnym znacznikiem ostatnio pobranych danych, odpytywanie staje się osobnym zadaniem harmonogramowania i monitorowania.

Odpytywanie zadaje to samo pytanie tysiące razy dziennie, by wychwycić kilka ważnych momentów. Webhooki odzywają się tylko wtedy, gdy coś rzeczywiście się wydarzyło.

03 · Dostarczanie typu push z Cams

Jak działają webhooki biometryczne

W przypadku Cams Biometrics Gateway dostarczanie webhooków nazywa się Callback API. Podajesz Gateway adres URL na swoim serwerze, a każdy zweryfikowany skan jest na niego wysyłany w momencie wystąpienia. Zdarzenia Callback są dostarczane bez opóźnień w przypadku urządzeń korzystających z Native Push.

Co otrzymuje Twój serwer

Callback API, żądanie wysłane przez Gateway na Twój adres URL webhooka

{
  "RealTime": {
    "OperationID": "9nu1wak5616p",
    "LabelName": "Burj Khalifa",
    "SerialNumber": "ZHM11xxxxxxxx",
    "PunchLog": {
      "Type": "CheckOut",
      "Temperature": "36.8",
      "FaceMask": false,
      "InputType": "Fingerprint",
      "UserId": "2",
      "LogTime": "2020-09-17 07:48:22 GMT +0530"
    },
    "AuthToken": "COJJ7eiIPBGUfmIQPvh2PJWWDLX7OuKs",
    "Time": "2020-09-17 04:19:03 GMT +0000"
  }
}
Pole Co mówi Twojemu serwerowi
OperationID Unikalny identyfikator tego zdarzenia
LabelName Nazwa lokalizacji lub drzwi, do których przypisane jest urządzenie
SerialNumber Konkretne urządzenie, które zarejestrowało skan
Type Czy było to wejście, czy wyjście
InputType Sposób weryfikacji osoby: odcisk palca, twarz, karta, PIN itd.
UserId Kto zeskanował, zgodnie z identyfikatorem w Twoim systemie HR
LogTime Kiedy skan nastąpił na urządzeniu, wraz z przesunięciem strefy czasowej
AuthToken Token, którego Twój serwer używa do potwierdzenia, że żądanie jest autentyczne
Time Znacznik czasu samej wiadomości, w GMT

Co Twój serwer musi odesłać

Gdy Twój serwer otrzyma zdarzenie, odsyła krótkie potwierdzenie. Informuje ono Gateway, że zdarzenie dotarło bezpiecznie.

Callback API, odpowiedź, którą webhook musi zwrócić

{ "status": "done" }

Push, nawet gdy urządzenie nie potrafi

Nie każde urządzenie potrafi samodzielnie wysyłać dane. Niektóre starsze lub niezweryfikowane urządzenia przechowują dane o obecności wyłącznie w lokalnej bazie danych lub pliku. Dzięki Cams Hybrid Push Gateway może odczytywać tę bazę (DB Pull) lub monitorować ten plik (File Processing) i nadal dostarczać nowe rekordy obecności na Twój adres URL Callback. Twój serwer otrzymuje dostarczanie typu push w obu przypadkach, nawet jeśli urządzenie wymagałoby normalnie odpytywania.

04 · Dobre praktyki

Budowa niezawodnego odbiornika webhooków

Odbiornik webhooków jest prosty w budowie, ale kilka praktyk decyduje o tym, czy działa on poprawnie w testach, czy także przez lata w codziennej pracy.

Praktyka Co zrobić Dlaczego to ważne
Najpierw potwierdź Odeślij status done zaraz po odebraniu zdarzenia, a dopiero potem wykonuj wolniejsze zadania Utrzymuje krótkie żądanie Gateway, nawet gdy systemy zależne działają wolno
Kolejkuj zadania Umieszczaj każde odebrane zdarzenie w kolejce lub tabeli i przetwarzaj je osobno Obsługuje szczyty na początku zmiany bez gubienia zdarzeń
Weryfikuj AuthToken Sprawdzaj token w każdym żądaniu, zanim zaufasz danym Uniemożliwia komukolwiek innemu wysyłanie fałszywych danych o obecności na Twój adres URL
Używaj HTTPS Udostępniaj webhook wyłącznie przez HTTPS, z opcjonalnym szyfrowaniem AES-256 z Gateway Dane o obecności są danymi osobowymi i muszą być chronione podczas przesyłania
Zapewnij idempotentność Używaj OperationID, aby wykrywać i ignorować zdarzenia, które już przetworzyłeś Powtórne dostarczenie nigdy nie tworzy zduplikowanego rekordu obecności
Ufaj LogTime przy obecności Rejestruj obecność na podstawie LogTime, a nie czasu odebrania zdarzenia przez serwer Zdarzenia zapisane podczas awarii docierają później, ale zachowują prawdziwy czas skanu
Sortuj według LogTime Ustaw zdarzenia według LogTime przed obliczeniem godzin Buforowane zdarzenia mogą dotrzeć w złej kolejności po zerwaniu połączenia
Zapisuj wszystko Prowadź rejestr każdego odebranego zdarzenia i każdej wysłanej odpowiedzi Ułatwia rozwiązywanie problemów i audyty

Planuj pod szczyty, a nie średnie

Lokalizacja z 300 pracownikami może przez większość dnia nie otrzymywać prawie nic, a potem 300 zdarzeń w ciągu dziesięciu minut podczas zmiany. Zaprojektuj odbiornik pod ten szczyt. Najprostszym sposobem obsługi jest szybkie potwierdzanie i kolejkowanie zadań.

Gdzie może znajdować się webhook

Webhook potrzebuje publicznego adresu HTTPS, do którego Gateway ma dostęp. Może to być punkt końcowy w Twojej aplikacji, mała funkcja chmurowa lub przychodzący webhook w narzędziu do automatyzacji, takim jak n8n czy Make. Same urządzenia nie potrzebują publicznego IP. Lokalizacje za zaporami sieciowymi mogą łączyć się z Gateway przez Hybrid Connector, który działa przez połączenie wychodzące.

Twój system decyduje, co dalej

Gateway dostarcza zweryfikowane zdarzenia i czeka na Twoje potwierdzenie. To, co dzieje się potem, na przykład zapis w HRMS, aktualizacja pulpitu, wysłanie powiadomienia o spóźnieniu lub uruchomienie przepływu pracy, zależy od Twojego oprogramowania i reguł.

05 · Używanie obu sposobów razem

Gdzie odpytywanie wciąż ma zastosowanie

Webhooki powinny być domyślnym wyborem dla danych biometrycznych na żywo. Pobieranie danych na żądanie nadal ma jednak przydatne, konkretne zastosowania. Najlepsze integracje wykorzystują webhooki do dostarczania w czasie rzeczywistym, a okazjonalne pobieranie na żądanie do sprawdzania i odzyskiwania danych.

Sytuacja Najlepsze podejście Dlaczego
Obecność na żywo, pulpity, powiadomienia Webhooki (Callback API) Dane docierają w chwili wystąpienia skanu
Twój serwer był przez pewien czas offline Pobierz logi na żądanie Uzupełnia wszelkie luki i potwierdza, że nic nie zostało pominięte
Nocne lub tygodniowe uzgadnianie Pobieraj logi według harmonogramu Porównanie z tym, co dostarczyły webhooki, jako siatka bezpieczeństwa
Konfiguracja nowej integracji Pobierz historyczne logi jednorazowo Import istniejącej historii, zanim przejmą to webhooki
Audyt określonego okresu Pobierz logi za ten okres Tworzy kompletny zapis do przeglądu

Do tych zadań służy Cams RESTful API, które zawiera operacje wczytywania logów z urządzeń. Używane okazjonalnie i celowo, pobieranie logów uzupełnia webhooki, zamiast z nimi konkurować. Różnica tkwi w intencji: pobierasz dane, gdy masz ku temu powód, zamiast pytać co minutę na wszelki wypadek.

Najczęściej zadawane pytania

Czy odpytywanie bywa lepsze od webhooków przy danych biometrycznych?

Odpytywanie bywa prostsze, gdy Twój system nie może udostępnić żadnego publicznego punktu końcowego, albo przy jednorazowych importach historycznych. W przypadku bieżących danych o obecności i dostępie webhooki są szybsze, mniej obciążają urządzenia i sieci oraz łatwiej je skalować między lokalizacjami.

Co się dzieje ze skanami, gdy mój serwer webhooków nie działa?

Jeśli Twój serwer webhooków nie działa, dane o obecności są zapisywane w kolejce Cams. Gdy serwer znów będzie dostępny, rekordy z kolejki zostaną automatycznie wysłane na Twój serwer. Kolejka uruchamia się automatycznie co 3 godziny, a w dowolnym momencie możesz ją też uruchomić ręcznie w Cams Portal. Dzięki temu rekordy obecności nie giną z powodu chwilowych przestojów serwera.

Czy moje urządzenia biometryczne potrzebują publicznego IP, aby webhooki działały?

Nie. Twój adres URL webhooka musi być dostępny dla Gateway, ale urządzenia nie muszą. Lokalizacje bez publicznego IP mogą łączyć się przez Hybrid Connector, który wykorzystuje połączenie wychodzące.

Czy mogę odbierać webhooki w n8n, Make lub Zapier?

Tak. Każde narzędzie, które potrafi odebrać przychodzący webhook, może odbierać zdarzenia Cams Callback. n8n i Make mogą także bezpośrednio zwrócić wymagane potwierdzenie done. Zapier może wymagać małego przekaźnika przed sobą, aby wysłać tę odpowiedź.

Dlaczego LogTime i Time różnią się w ładunku?

LogTime to moment, w którym osoba faktycznie zeskanowała kartę, zapisany z przesunięciem strefy czasowej urządzenia. Time to znacznik czasu samej wiadomości, w GMT. Jeśli urządzenie było offline, wiadomość może zostać wysłana znacznie po skanie. Do obecności zawsze używaj LogTime.

Podsumowanie: niech zadzwoni dzwonek

Odpytywanie miało sens, gdy urządzenia biometryczne można było odczytać wyłącznie na żądanie, a nikt nie oczekiwał, że dane o obecności będą na bieżąco. Dziś pulpity HR, systemy płacowe, narzędzia automatyzacji i asystenci AI działają najlepiej, gdy dane są dostępne w chwili ich powstania. Zadawanie urządzeniu tego samego pytania tysiące razy dziennie to powolny i marnotrawny sposób, by to osiągnąć.

Webhooki zamieniają każdy zweryfikowany skan w zdarzenie, które Twoje systemy odbierają natychmiast, bez zbędnych żądań i bez kruchego śledzenia tego, co już pobrano. Pobieranie logów na żądanie zachowaj do tego, do czego się nadaje: uzupełniania luk i sprawdzania kompletności, a wszystko inne niech przenoszą webhooki.

Cams Biometrics Gateway jest zbudowany wokół dostarczania typu push. Jego Callback API wysyła każdy zweryfikowany skan na Twój webhook w czasie rzeczywistym, z urządzeń ponad 15 marek, w jednym spójnym formacie JSON. Tryby Hybrid Push dostarczają zdarzenia push nawet z urządzeń, które nie potrafią same wysyłać danych, a RESTful API zapewnia operacje na żądanie, takie jak wczytywanie logów do uzgadniania. Cała komunikacja odbywa się przez HTTP/HTTPS z walidacją tokena uwierzytelniającego i opcjonalnym szyfrowaniem AES-256. Poznaj platformę na stronie CamsBiometrics.com i przeczytaj pełną dokumentację Callback API na stronie developer.camsbiometrics.com.

Was this article helpful?