Oprogramowanie i API do liczenia osób: Przewodnik po integracji dla programistów

Oprogramowanie do liczenia osób przekształca surowe dane z czujników na dane dotyczące obłożenia, liczby odwiedzających i czasu spędzonego w lokalu. Integracja tych danych odbywa się za pośrednictwem udokumentowanego interfejsu HTTP JSON, a nie zastrzeżonego zestawu SDK.Programista może pobrać dane liczbowe za pomocą podpisanego żądania POST lub otrzymać je w webhooku. W obu przypadkach ładunek jest taki sam.

Poniższy przewodnik po API do liczenia osób obejmuje model danych, dwa wzorce integracji, uwierzytelnianie oraz pierwsze działające żądanie. Rozpracowane przykłady bazują na interfejsie udostępnionym przez liczniki stereoskopowe Pyroglaux 3D, a ich ogólny kształt odnosi się do większości współczesnego sprzętu do liczenia.

Co tak naprawdę otrzymuje oprogramowanie do liczenia osób?

W nowoczesnym systemie liczenia osób to czujnik wykonuje liczenie na urządzeniu i emituje zdarzenia strukturalne, więc oprogramowanie do liczenia osób nigdy nie przetwarza wideo.Klatki głębokości są analizowane i odrzucane bezpośrednio przez czujnik.

Pojedyncze zdarzenie przekroczenia strefy zawiera cztery pola: unikalny indeks śledzonego obiektu, znacznik czasu UNIX oznaczający moment, w którym obiekt opuścił strefę wykrywania, kod typu zdarzenia i czas przebywania w milisekundach.

Źródło: Specyfikacja interfejsu HTTP przepływu pasażerów Pyroglaux, wersja 2.1.5.

Cztery typy zdarzeń to element, który większość osób błędnie uwzględnia przy liczeniu integracji oprogramowania. Traktowanie każdego zdarzenia jako wejścia powoduje podwójne liczenie każdego, kto przejdzie obok drzwi bez wejścia, ignorując kod ponownego wejścia, który istnieje właśnie po to, aby zapobiec liczeniu powracającego klienta jako nowego odwiedzającego.

Jak działa uwierzytelnianie za pomocą interfejsu API People Counting?

Żądania są podpisywane, a nie zawierają tokenu w nagłówku, za pomocą skrótu MD5 posortowanych parametrów połączonych ze współdzielonym tajnym kluczem usługi.Otrzymany skrót jest zapisywany wielkimi literami i wysyłany w nagłówku Sign.

Kroki podpisywania są stałe. Posortuj każdy parametr żądania w kolejności ASCII, dodaj tajny kod usługi uzgodniony z urządzeniem, pobierz skrót MD5 tego ciągu, zamień go na wielkie litery i umieść wynik w nagłówku Sign obok standardowego typu zawartości JSON.

Podpisane żądanie API do liczenia osób pozwala uniknąć przechowywania długotrwałego tokena na urządzeniu znajdującym się na hali produkcyjnej. Rotacja tajnego klucza usługi unieważnia każde wcześniej przechwycone żądanie bez listy unieważnionych tokenów.

Pull czy Push: który wzorzec integracji jest lepszy?

System typu pull sprawdza się w przypadku małych flot i wczesnego etapu rozwoju; system typu push sprawdza się w przypadku bieżących pulpitów nawigacyjnych i większych posiadłości.Oba zwracają ten sam kod JSON, więc parser napisany dla jednego wzorca działa bez zmian w przypadku drugiego.

Kiedy ludzie powinni zliczać dane za pomocą oprogramowania do sprawdzania urządzenia?

Ludzie zajmujący się oprogramowaniem do liczenia powinni w pierwszej kolejności przeprowadzać sondowanie, ponieważ debugowanie sondowania jest proste.Pojedyncze polecenie curl udowadnia łączność, uwierzytelnianie i kształt ładunku jeszcze przed powstaniem jakiegokolwiek kodu aplikacji.

Koszt sondowania to osiągalne urządzenie. Serwer musi być w stanie nawiązać połączenie z każdym czujnikiem, co oznacza VPN, stały adres lub mapowanie portów dla każdego urządzenia. Powyżej około 50 urządzeń, inwentaryzacja staje się dominującym obciążeniem konserwacyjnym.

Kiedy czujnik powinien nacisnąć?

Konfiguracja typu push zmienia czujnik w klienta, dzięki czemu urządzenie potrzebuje jedynie dostępu do sieci wychodzącej.Nie jest wymagana żadna reguła zapory sieciowej dla ruchu przychodzącego ani książka adresowa dla każdego urządzenia.

Urządzenie otrzymuje docelowy adres URL za pośrednictwem punktu końcowego konfiguracji, po czym zdarzenia przejściowe są publikowane na tym adresie URL w miarę ich występowania. Opóźnienie spada z interwału odpytywania do niemal czasu rzeczywistego, co ma znaczenie dla limitów zajętości i wyświetlania kolejek na żywo.

Jak złożyć pierwsze zamówienie?

Trzy punkty końcowe API zliczające liczbę osób obejmują niemal każdą integrację: bieżące liczniki, historyczne sumy i listę surowych zdarzeń.Urządzenie nasłuchuje na stałym porcie i akceptuje żądania POST RESTful z treścią JSON.

Źródło: Specyfikacja interfejsu HTTP Pyroglaux Passenger Flow, wersja 2.1.5. Dokładne ścieżki można znaleźć w aktualnej dokumentacji urządzenia, ponieważ nazwy punktów końcowych różnią się w zależności od generacji oprogramowania sprzętowego.

Osoby liczące oprogramowanie, wysyłając pierwsze żądanie, powinny poprosić o małą partię zdarzeń, a nie o cały dzień. Wysłanie indeksu początkowego równego zero z liczbą 100 zwraca maksymalnie 100 rekordów, a odpowiedź informuje o liczbie faktycznie dostępnych rekordów.

Każda odpowiedź API licznika osób zawiera obiekt wyniku zawierający flagę błędu, kod numeryczny i komunikat czytelny dla człowieka. Sprawdzenie flagi błędu przed analizą danych zapobiega cichemu odczytaniu pustego wyniku jako zerowej liczby odwiedzających.

Jakie ograniczenia warto znać przed rozpoczęciem budowy?

Pamięć masowa na urządzeniu jest buforem, a nie bazą danych.Urządzenie liczące zwykle przechowuje historię z trzech dni, co wystarcza na przetrwanie weekendowej przerwy w działaniu sieci, ale nie wystarcza, aby służyć jako system rejestrujący.

Każdy system zliczania osób zbudowany na tych urządzeniach ma trzy konsekwencje. Utrwalaj zdarzenia we własnym magazynie podczas pobierania. Śledź ostatni pomyślnie pobrany indeks lub znacznik czasu, aby restart był wznawiany, a nie restartowany. Uzgadniaj dzienne sumy z historycznym punktem końcowym, ponieważ zapytanie zbiorcze i lista zdarzeń są obliczane oddzielnie na urządzeniu.

Dryf zegara zasługuje na uwagę w każdym wielooddziałowym systemie zliczania osób. Znaczniki czasu pochodzą z zegara urządzenia, więc niezsynchronizowany czujnik generuje zdarzenia, które nieprawidłowo sortują dane z POS. Skonfiguruj serwer czasu podczas uruchamiania, a nie po pierwszym niezgodnym raporcie.

W jaki sposób dane trafiają do narzędzia BI?

Integracja danych o liczbie odwiedzających powinna przechowywać zdarzenia w postaci surowej i agregować je przy odczycie.Zapisywanie w magazynie wstępnie zagregowanych przedziałów godzinowych jest kuszące i sprawia, że ​​późniejsze pytania o czas przebywania lub ponownego wprowadzania danych stają się niemożliwe do odpowiedzi.

Minimalny, praktyczny schemat integracji danych o liczbie odwiedzających to jeden wiersz na wydarzenie z identyfikatorem urządzenia, identyfikatorem strefy, znacznikiem czasu, typem wydarzenia i czasem przebywania. Godzinowa liczba odwiedzających, dane o konwersji w stosunku do danych kasowych oraz rozkład czasu przebywania – wszystkie te dane pochodzą z tej jednej tabeli za pomocą standardowego SQL.

Oprogramowanie do zliczania transakcji w kasie, które łączy je na podstawie identyfikatora urządzenia i godziny, generuje bezpośrednio wskaźnik konwersji. Zespoły sprzedaży detalicznej stosujące tę metrykę powinny zapoznać się zsłownik wskaźników sprzedaży detalicznejdla definicji, których będzie potrzebować tablica rozdzielcza.

Czy oprogramowanie do liczenia osób przetwarza dane osobowe?

Proces zliczania oparty na głębokości, który przesyła wyłącznie dane liczbowe, nie przetwarza danych osobowych, ponieważ żaden obraz ani identyfikator nie opuszcza czujnika.Opisany powyżej ładunek zawiera indeks obejmujący sesję, znacznik czasu i czas trwania.

Dwie decyzje projektowe utrzymują oprogramowanie liczące w tej sytuacji. Przetwarzanie w głąb urządzenia zamiast strumieniowego przesyłania ramek do serwera w celu analizy. Unikaj łączenia indeksu sesji z jakimkolwiek rekordem klienta lub pracownika, ponieważ łączenie tworzyłoby dane osobowe tam, gdzie ich nie było.

Funkcje ponownej identyfikacji, które pozwalają programowi liczącemu zduplikować tego samego użytkownika w ciągu dnia, są dostępne w niektórych wersjach oprogramowania sprzętowego i zmieniają sposób analizy. Należy traktować każdą funkcję deduplikacji jako osobną kontrolę prywatności, a nie automatyczną aktualizację.

Najczęściej zadawane pytania dotyczące oprogramowania i interfejsów API do liczenia osób

Czy do korzystania z interfejsu API do liczenia osób wymagany jest zestaw SDK?

Nie, podpisany komunikat HTTP POST z treścią JSON jest wystarczający dla interfejsu API liczenia osób.Integracja jest możliwa w dowolnym języku z klientem HTTP i funkcją MD5. Zestawy SDK dostawców obejmują ten sam interfejs i są wygodne, a nie konieczne, a brak zestawu SDK zapewnia przenośność integracji między generacjami urządzeń.

Jak często ludzie powinni sprawdzać działanie oprogramowania liczącego na urządzeniu?

Czas od jednej do pięciu minut zaspokaja większość potrzeb związanych ze sprawozdawczością.Szybsze sondowanie rzadko się sprawdza, ponieważ liczba przechodniów jest raportowana dla każdego przejścia dla pieszych, a następnie agregowana. Wyjątkiem są wyświetlacze zajętości na żywo, które powinny korzystać z funkcji push, a nie szybszego sondowania.

Co dzieje się z licznikami podczas awarii sieci?

Urządzenie buforuje zdarzenia lokalnie i obsługuje zaległości po przywróceniu łączności.Typowy czas retencji wynosi około trzech dni. Ingester, który śledzi ostatnio przetworzony indeks, automatycznie odzyskuje lukę; ingester, który zawsze żąda najnowszych rekordów, trwale traci okno przestoju.

Czy kilka systemów może wywoływać to samo API licznika osób?

Tak, interfejs pull jest bezstanowy i obsługuje jednoczesne odczytywanie.Każdy wywołujący podaje indeks początkowy lub zakres czasu, dzięki czemu zarówno potok BI, jak i pulpit nawigacyjny na żywo mogą wysyłać zapytania do tego samego urządzenia. Miejsca docelowe push są zazwyczaj ograniczone do niewielkiej liczby, dlatego rozsyłanie danych lepiej jest obsługiwać za pomocą przekaźnika we własnej infrastrukturze.

Jak oblicza się czas przebywania?

Czas przebywania jest mierzony dla każdego zdarzenia jako czas pobytu (stayTime) w milisekundach, mierzony od wejścia do wyjścia ze strefy wykrywania.Czas przebywania w strefie to nie to samo, co czas przebywania w sklepie. Pomiar czasu przebywania klienta w sklepie wymaga zdarzenia wejścia i odpowiadającego mu zdarzenia wyjścia lub funkcji ponownej identyfikacji, która łączy te dwa zdarzenia.

Co należy najpierw sprawdzić w teście integracji oprogramowania do liczenia osób?

Przejdź przez drzwi znaną liczbę razy i porównaj liczbę przejść.Dziesięć kontrolowanych przejazdów w każdym kierunku weryfikuje przypisanie kierunku, mapowanie typów zdarzeń i obsługę znaczników czasu w jednym ćwiczeniu. Wszelkie niezgodności na tym etapie stanowią problem z konfiguracją, a nie z kodem.

Następne kroki

Rozpocznij integrację danych o ruchu pieszym za pomocą jednego urządzenia, skryptu sondażowego i dziesięciu kontrolowanych przejść. Gdy liczby się zrównają, zdecyduj, czy wdrożenie wymaga wdrożenia push, i zaprojektuj magazyn zdarzeń przed skalowaniem poza jedną lokalizację.

Pyroglaux publikuje pełną specyfikację interfejsu HTTP dla każdego urządzenia i nie wymaga subskrypcji, aby umożliwić integrację. PrzeglądajZasięg czujnika zliczającego 3DLubpoproś o dokumentację API i przykładową jednostkę dla programisty.