Support Hub/API & Integrations/Native Push a tryby Hybrid Push: drzewo decyzyjne
Translated from the English article and reviewed by a person. Read the English original
Developer

Native Push a tryby Hybrid Push: drzewo decyzyjne

Native Push a tryby Hybrid Push: drzewo decyzyjne

Każde urządzenie biometryczne łączące się z Cams Biometric Gateway robi to w jednym z dwóch trybów push. Tryb używany przez urządzenie determinuje, które API są dostępne, w jaki sposób dostarczane są zdarzenia oraz jak należy skonfigurować infrastrukturę. Ten przewodnik omawia wszystkie zmienne tej decyzji, od typu urządzenia, przez metodę komunikacji, po topologię wdrożenia, abyś mógł wybrać odpowiednią ścieżkę, zanim zaczniesz budować rozwiązanie.

Pierwsze pytanie: jakiego rodzaju urządzenie podłączasz?

Zanim wybierzesz metodę komunikacji lub topologię wdrożenia, musisz odpowiedzieć na bardziej podstawowe pytanie: czy Twoje urządzenie jest urządzeniem Cams Biometrics, czy urządzeniem zweryfikowanym w portalu deweloperskim Cams?

Odpowiedź na to pytanie w całości determinuje tryb push. Jeśli odpowiedź brzmi tak, używasz Native Push i nie są potrzebne dalsze decyzje. Jeśli odpowiedź brzmi nie, znajdujesz się w obszarze Hybrid Push i czeka Cię seria dodatkowych decyzji.

Tryb 1
Native Push
Dla wszystkich urządzeń Cams Biometrics oraz dowolnego urządzenia oznaczonego jako zweryfikowane na developer.camsbiometrics.com. Urządzenie komunikuje się bezpośrednio z Biometric Gateway przez internet, bez konieczności dodatkowej konfiguracji.

Wszystkie 38 operacji
Pełne Callback API
Pełne RESTful API

Tryb 2
Hybrid Push
Dla wszystkich pozostałych, niezweryfikowanych urządzeń. Wybierasz metodę komunikacji oraz topologię wdrożenia, które pasują do Twojego środowiska. Dostępność API zależy od wybranej kombinacji.

3 metody komunikacji
2 opcje topologii
Zmienny dostęp do API

Native Push: pełny obraz

Urządzenia Native Push uzyskują pełny dostęp do wszystkich 38 operacji Gateway bez konfiguracji wykraczającej poza podłączenie urządzenia do internetu. Callback API dostarcza zdarzenia bez opóźnienia. Polecenia RESTful API wykonują się w czasie około 15 sekund. Nie ma potrzeby stosowania SDK ani lokalnego oprogramowania, a decyzja o topologii nie jest wymagana.

Hybrid Push: trzy metody komunikacji

Jeśli Twoje urządzenie nie jest urządzeniem Cams ani zweryfikowanym, kolejną decyzją jest to, w jaki sposób Gateway faktycznie będzie komunikować się z Twoim sprzętem. Dostępne są trzy metody komunikacji, a każda z nich ma inne wymagania i inne konsekwencje dla tego, z jakich funkcji API można korzystać.

Metoda komunikacji nie dotyczy konfiguracji sieci. Dotyczy mechanizmu technicznego, za pomocą którego Gateway odczytuje dane z konkretnego urządzenia i wysyła do niego polecenia. Wybór ten ograniczają możliwości Twojego sprzętu.

a
Device SDK
Najlepsza opcja dla pełnego dostępu do API
Gateway komunikuje się ze sprzętem za pomocą SDK producenta urządzenia. SDK obsługuje niskopoziomowy protokół urządzenia, a Gateway udostępnia przez swoje API wszystkie funkcje obsługiwane przez SDK. Jest to jedyna metoda komunikacji w Hybrid Push, która umożliwia operacje RESTful API.
Pełne Callback API + pełne RESTful API (w ramach możliwości SDK)
b
DB Pull
Wyłącznie dane o obecności
Gateway odczytuje z lokalnej bazy danych, do której własne oprogramowanie do zarządzania urządzeniem zapisuje rekordy obecności. Gateway monitoruje tę bazę i w czasie rzeczywistym wysyła nowe rekordy na Twój URL callback. Nie dochodzi do bezpośredniej komunikacji z urządzeniem, co oznacza, że do urządzenia nie można wysyłać żadnych poleceń. Operacje takie jak dodawanie użytkowników, usuwanie rekordów czy ładowanie logów są niedostępne.
Callback API: wyłącznie dane o obecności i logi odbić. RESTful API: nieobsługiwane.
c
File Processing
Wyłącznie dane o obecności
Wyznaczony plik z danymi o obecności na lokalnym komputerze jest objęty ciągłym monitorowaniem. Za każdym razem, gdy oprogramowanie urządzenia aktualizuje ten plik o nowe rekordy obecności, Gateway wykrywa zmianę, wyodrębnia nowe rekordy i w czasie rzeczywistym wysyła je na Twój URL callback. Podobnie jak w przypadku DB Pull, z perspektywy urządzenia metoda ta jest wyłącznie do odczytu i ma te same ograniczenia API.
Callback API: wyłącznie dane o obecności i logi odbić. RESTful API: nieobsługiwane.
Jak wybrać metodę komunikacji

Jeśli Twoje urządzenie posiada SDK producenta obsługiwane przez Cams Gateway, wybierz Device SDK (a). Jest to jedyna metoda, która odblokowuje operacje RESTful API dla urządzeń Hybrid Push. Jeśli SDK nie jest obsługiwane lub nie jest dostępne, DB Pull (b) lub File Processing (c) nadal będą dostarczać dane o obecności do Twojego endpointu callback w czasie rzeczywistym, co jest wystarczające w wielu przypadkach.

Hybrid Push: dwie topologie wdrożenia

Po wybraniu metody komunikacji druga decyzja dotyczy tego, gdzie Gateway łączy się z Twoim urządzeniem, bazą danych lub plikiem. Jest to decyzja o topologii, która zależy od środowiska sieciowego w fizycznej lokalizacji urządzenia.

Topologia X

Bezpośrednia
Komputer na miejscu, do którego podłączone jest urządzenie lub na którym działa oprogramowanie do zarządzania urządzeniem, posiada publiczny adres IP z przekierowaniem portów do sieci lokalnej. Biometric Gateway łączy się bezpośrednio z urządzeniem, bazą danych lub plikami przez internet.
Wymaga: publicznego IP + przekierowania portów na miejscu
Topologia Y

Pośrednia
Aplikacja Hybrid Connector jest zainstalowana na lokalnym komputerze na miejscu. Działa jako wychodzący most między lokalną maszyną a Biometric Gateway, nawiązując połączenie od wewnątrz zamiast wymagać połączenia przychodzącego. Po stronie klienta nie jest potrzebny publiczny IP.
Wymaga: zainstalowanego Hybrid Connector na lokalnym komputerze. Publiczny IP nie jest potrzebny.
Rekomendacja dotycząca topologii

Jeśli nie możesz skonfigurować publicznego IP ani przekierowania portów na miejscu, wybierz topologię pośrednią (Y) z Hybrid Connector. Jest to najprostsza ścieżka wdrożenia i całkowicie pozwala uniknąć konfiguracji sieci po stronie klienta. Jeśli publiczny IP jest dostępny i skonfigurowany, topologia bezpośrednia (X) również działa i nie wymaga instalacji dodatkowego oprogramowania na miejscu.

Drzewo decyzyjne: który tryb wybrać?

Przejdź przez to drzewo decyzyjne od góry do dołu. Zatrzymaj się na pierwszej odpowiedzi, która dotyczy Twojej sytuacji.

Drzewo decyzyjne, zacznij od góry
1. Czy Twoje urządzenie jest urządzeniem Cams Biometrics lub figuruje jako zweryfikowane na developer.camsbiometrics.com?
Tak Użyj Native Push. Pełny dostęp do API. Nie są potrzebne dalsze decyzje.
Nie Przejdź do pytania 2.
2. Czy Cams Gateway obsługuje SDK producenta Twojego urządzenia?
Tak Użyj Hybrid Push, Device SDK (a). Pełny dostęp do Callback i RESTful API w granicach SDK. Przejdź do pytania 3, aby wybrać topologię.
Nie Przejdź do pytania 2b.
2b. Czy oprogramowanie do zarządzania urządzeniem zapisuje rekordy obecności w lokalnej bazie danych?
Tak Użyj Hybrid Push, DB Pull (b). Wyłącznie Callback dla danych o obecności. Przejdź do pytania 3, aby wybrać topologię.
3. Czy komputer na miejscu posiada publiczny adres IP z dostępnym przekierowaniem portów?
Tak Użyj Topologia bezpośrednia (X). Na miejscu nie jest potrzebne dodatkowe oprogramowanie.
Nie Użyj topologii pośredniej (Y). Zainstaluj Hybrid Connector na lokalnym komputerze na miejscu.

Macierz dostępności funkcji Hybrid Push

Poniższa tabela pokazuje wszystkie kombinacje metody komunikacji i topologii wdrożenia oraz to, jakie funkcje API są dostępne w każdym z przypadków. Skorzystaj z niej razem z drzewem decyzyjnym, aby potwierdzić, co obsługuje wybrana konfiguracja.

Tryb Komunikacja Topologia Callback API RESTful API
Bezpośrednie urządzenie (a) Device SDK (X) Publiczny IP Pełne Pełne (obowiązują limity SDK)
Pośrednie urządzenie (a) Device SDK (Y) Hybrid Connector Pełne Pełne (obowiązują limity SDK)
Bezpośrednia baza danych (b) DB Pull (X) Publiczny IP Wyłącznie obecność Nieobsługiwane
Pośrednia baza danych (b) DB Pull (Y) Hybrid Connector Wyłącznie obecność Nieobsługiwane
Bezpośredni plik (c) File Processing (X) Publiczny IP Wyłącznie obecność Nieobsługiwane
Pośredni plik (c) File Processing (Y) Hybrid Connector Wyłącznie obecność Nieobsługiwane
Ważne zastrzeżenie dotyczące sprzętu

Ograniczenia sprzętowe mogą dodatkowo zawężać funkcje API nawet w trybie Device SDK. Konkretne API mogą nie działać w zależności od wersji firmware modelu urządzenia lub możliwości udostępnianych przez SDK producenta. Powyższa macierz opisuje to, co obsługuje architektura Gateway, a nie to, co na pewno obsługuje każdy pojedynczy model urządzenia. Zawsze testuj na swoim konkretnym sprzęcie i weryfikuj przypadki brzegowe z zespołem wsparcia Cams przed wdrożeniem produkcyjnym.

Na co wpływa, a na co nie wpływa decyzja o topologii

Częstym źródłem nieporozumień jest zależność między topologią a dostępnością API. Wybór topologii, bezpośredniej lub pośredniej, nie wpływa na to, które funkcje API są dostępne. Zestaw funkcji API jest określany wyłącznie przez metodę komunikacji.

Topologia wpływa natomiast na to, w jaki sposób ustanawiane jest połączenie sieciowe między Gateway a Twoim lokalnym środowiskiem. Topologia bezpośrednia wymaga publicznego IP i przekierowania portów na miejscu. Topologia pośrednia wymaga zainstalowania Hybrid Connector na lokalnej maszynie. Dostępne funkcje API są identyczne dla Direct Device SDK i Indirect Device SDK oraz identyczne dla Direct DB Pull i Indirect DB Pull.

“Wybierz metodę komunikacji na podstawie funkcji API, których potrzebuje Twoja integracja. Wybierz topologię na podstawie tego, co obsługuje Twoje środowisko sieciowe. Są to decyzje niezależne od siebie.”

Najczęściej zadawane pytania

Czy mogę używać DB Pull lub File Processing razem z poleceniami RESTful API?
Nie. DB Pull i File Processing to metody integracji tylko do odczytu. Pozwalają Gateway obserwować dane o obecności generowane przez własne oprogramowanie urządzenia, ale nie tworzą kanału, przez który można wysyłać polecenia z powrotem do urządzenia. Operacje RESTful API, takie jak dodawanie użytkowników, usuwanie rekordów czy ładowanie logów, wymagają trybu Device SDK, który tworzy dwukierunkowy kanał komunikacji.
Czy Hybrid Connector musi być zainstalowany na tej samej maszynie co oprogramowanie urządzenia?
Tak. Hybrid Connector musi być zainstalowany na tym samym lokalnym komputerze, do którego podłączone jest urządzenie lub na którym działa oprogramowanie do zarządzania urządzeniem. Wynika to z tego, że potrzebuje lokalnego dostępu do urządzenia, lokalnej bazy danych lub pliku z danymi o obecności, w zależności od wybranej metody komunikacji. Connector następnie nawiązuje wychodzący tunel do Gateway, dzięki czemu w tej lokalizacji nie jest potrzebny publiczny IP.
Jaka jest różnica w opóźnieniach między Native Push a Hybrid Push?
W przypadku Native Push zdarzenia Callback API są dostarczane bez opóźnienia, a polecenia RESTful API wykonują się w czasie około 30 sekund. W przypadku Hybrid Push z Device SDK opóźnienie zależy od własnego cyklu komunikacji SDK i różni się w zależności od producenta urządzenia. Opóźnienie DB Pull i File Processing zależy od tego, jak często lokalne oprogramowanie zapisuje nowe rekordy oraz jak szybko Gateway wykrywa zmianę, zwykle w ciągu kilku sekund od zarejestrowania zdarzenia przez urządzenie.

Podsumowanie: dopasuj tryb do swoich ograniczeń

Decyzja o trybie połączenia z Cams Biometric Gateway nie jest kwestią preferencji, lecz ograniczeń. Native Push jest właściwym wyborem, jeśli Twoje urządzenie się kwalifikuje, ponieważ zapewnia największe możliwości przy najmniejszej konfiguracji. Hybrid Push jest odpowiedzią dla wszystkich pozostałych przypadków, a w jego ramach tryb Device SDK zapewnia najbliższy odpowiednik Native Push pod względem dostępu do API.

Gdy pełny dostęp do SDK nie jest dostępny, DB Pull i File Processing są praktycznymi ścieżkami, które nadal dostarczają dane o obecności do Twoich systemów w czasie rzeczywistym. Decyzja o topologii jest wtedy osobnym wyborem na poziomie infrastruktury, który nie zmienia tego, co może zrobić API.

Zacznij od drzewa decyzyjnego, porównaj swój wybór z macierzą funkcji, przetestuj na swoim sprzęcie i zweryfikuj wszelkie przypadki brzegowe z zespołem wsparcia Cams przed wdrożeniem produkcyjnym.

Was this article helpful?