Elk biometrisch apparaat dat verbinding maakt met de Cams Biometric Gateway doet dit via een van de twee push-modi. De modus die uw apparaat gebruikt, bepaalt welke API's beschikbaar zijn, hoe gebeurtenissen worden afgeleverd en hoe uw infrastructuur moet worden geconfigureerd. Deze gids doorloopt elke variabele in de beslissing, van apparaattype tot communicatiemethode en implementatietopologie, zodat u het juiste pad kunt kiezen voordat u begint met bouwen.
De eerste vraag: welk type apparaat wilt u aansluiten?
Voordat u een communicatiemethode of implementatietopologie kiest, is er een meer fundamentele vraag te beantwoorden: is uw apparaat een Cams Biometrics-apparaat, of een apparaat dat is geverifieerd op het Cams-ontwikkelaarsportaal?
Het antwoord op deze vraag bepaalt volledig uw push-modus. Als het antwoord ja is, gebruikt u Native Push en is geen verdere beslissing nodig. Als het antwoord nee is, bevindt u zich in het gebied van Hybrid Push en volgt een reeks aanvullende beslissingen.
Modus 1
Native Push
Voor alle Cams Biometrics-machines en elk apparaat dat is vermeld als geverifieerd op developer.camsbiometrics.com. Het apparaat communiceert rechtstreeks met de Biometric Gateway via internet, zonder dat aanvullende configuratie nodig is.
Alle 38 bewerkingen
Volledige Callback API
Volledige RESTful API
Modus 2
Hybrid Push
Voor alle overige niet-geverifieerde apparaten. U selecteert een communicatiemethode en implementatietopologie die past bij uw omgeving. De beschikbaarheid van API's hangt af van de combinatie die u kiest.
3 communicatiemethoden
2 topologieopties
Variabele API-toegang
Native Push: het volledige plaatje
Native Push-apparaten krijgen volledige toegang tot alle 38 Gateway-bewerkingen, zonder configuratie buiten het verbinden van het apparaat met internet. De Callback API levert gebeurtenissen zonder vertraging. RESTful API-opdrachten worden in ongeveer 15 seconden uitgevoerd. Geen SDK, geen lokale software en geen topologiebeslissing vereist.
Hybrid Push begrijpen: drie communicatiemethoden
Als uw apparaat geen Cams- of geverifieerd apparaat is, is de volgende beslissing hoe de Gateway daadwerkelijk met uw hardware communiceert. Er zijn drie communicatiemethoden beschikbaar, en elk heeft andere vereisten en andere gevolgen voor de API-functies die u kunt gebruiken.
De communicatiemethode gaat niet over uw netwerkconfiguratie. Het gaat over het technische mechanisme dat de Gateway gebruikt om gegevens van uw specifieke apparaat te lezen en opdrachten naar dat apparaat te sturen. Deze keuze wordt beperkt door wat uw hardware ondersteunt.
a
Device SDK
Beste optie voor volledige API-toegang
De Gateway communiceert met de hardware via de SDK van de fabrikant van het apparaat. De SDK verwerkt het protocol op laag niveau van het apparaat, en de Gateway stelt via zijn API alle functies beschikbaar die de SDK ondersteunt. Dit is de enige communicatiemethode binnen Hybrid Push die RESTful API-bewerkingen mogelijk maakt.
Volledige Callback API + volledige RESTful API (binnen de mogelijkheden van de SDK)
b
DB Pull
Alleen aanwezigheidsgegevens
De Gateway leest uit een lokale database waarnaar de eigen beheersoftware van het apparaat aanwezigheidsregistraties schrijft. De Gateway bewaakt deze database en stuurt nieuwe registraties in realtime naar uw callback-URL. Er vindt geen directe communicatie met het apparaat plaats, wat betekent dat er geen opdrachten naar het apparaat kunnen worden verzonden. Bewerkingen zoals gebruikers toevoegen, registraties verwijderen of logs laden zijn niet beschikbaar.
Callback API: alleen aanwezigheids- en ponslogs. RESTful API: niet ondersteund.
c
Bestandsverwerking
Alleen aanwezigheidsgegevens
Een aangewezen aanwezigheidsbestand op de lokale computer wordt continu gecontroleerd. Telkens wanneer de apparaatsoftware dit bestand bijwerkt met nieuwe aanwezigheidsregistraties, detecteert de Gateway de wijziging, haalt de nieuwe registraties op en stuurt deze in realtime naar uw callback-URL. Net als DB Pull is deze methode vanuit het perspectief van het apparaat alleen-lezen en gelden dezelfde API-beperkingen.
Callback API: alleen aanwezigheids- en ponslogs. RESTful API: niet ondersteund.
Een communicatiemethode kiezen
Als uw apparaat een SDK van de fabrikant heeft die wordt ondersteund door de Cams Gateway, kies dan Device SDK (a). Dit is de enige methode die RESTful API-bewerkingen ontgrendelt voor Hybrid Push-apparaten. Als de SDK niet wordt ondersteund of niet beschikbaar is, leveren DB Pull (b) of Bestandsverwerking (c) nog steeds aanwezigheidsgegevens in realtime aan uw callback-eindpunt, wat voor veel toepassingen voldoende is.
Hybrid Push begrijpen: twee implementatietopologieën
Zodra u een communicatiemethode heeft gekozen, is de tweede beslissing waar de Gateway verbinding maakt met uw apparaat, database of bestand. Dit is de topologiebeslissing, en die hangt af van uw netwerkomgeving op de fysieke locatie van het apparaat.
Topologie X
Direct
De sitecomputer waarop het apparaat is aangesloten, of waarop de beheersoftware van het apparaat draait, heeft een publiek IP-adres met portforwarding naar het lokale netwerk. De Biometric Gateway maakt rechtstreeks via internet verbinding met het apparaat, de database of de bestanden.
Vereist: publiek IP + portforwarding op de locatie
Topologie Y
Indirect
Op de lokale sitecomputer is een Hybrid Connector-toepassing geïnstalleerd. Deze fungeert als uitgaande brug tussen de lokale machine en de Biometric Gateway, en legt de verbinding vanuit de binnenkant tot stand in plaats van dat een inkomende verbinding nodig is. Aan de klantzijde is geen publiek IP-adres nodig.
Vereist: Hybrid Connector geïnstalleerd op de lokale computer. Geen publiek IP nodig.
Aanbeveling voor topologie
Als u op de locatie geen publiek IP of portforwarding kunt configureren, kies dan de Indirect-topologie (Y) met de Hybrid Connector. Dit is het eenvoudigste implementatiepad en vermijdt volledig netwerkconfiguratie aan de klantzijde. Als een publiek IP beschikbaar en geconfigureerd is, werkt de Direct-topologie (X) ook en is er geen extra softwareinstallatie op de locatie nodig.
De beslisboom: welke modus moet u kiezen?
Doorloop deze beslisboom van boven naar beneden. Stop bij het eerste antwoord dat van toepassing is op uw situatie.
Beslisboom, begin bovenaan
1. Is uw apparaat een Cams Biometrics-apparaat, of vermeld als geverifieerd op developer.camsbiometrics.com?
Ja Gebruik Native Push. Volledige API-toegang. Geen verdere beslissingen nodig.
Nee Ga verder naar vraag 2.
2. Ondersteunt de Cams Gateway de SDK voor de fabrikant van uw apparaat?
Ja Gebruik Hybrid Push, Device SDK (a). Volledige Callback- en RESTful API-toegang binnen de grenzen van de SDK. Ga verder naar vraag 3 voor de topologie.
Nee Ga verder naar vraag 2b.
2b. Schrijft uw beheersoftware voor het apparaat aanwezigheidsregistraties naar een lokale database?
Ja Gebruik Hybrid Push, DB Pull (b). Alleen aanwezigheids-Callback. Ga verder naar vraag 3 voor de topologie.
3. Heeft de sitecomputer een publiek IP-adres met beschikbare portforwarding?
Ja Gebruik Direct-topologie (X). Geen extra software nodig op de locatie.
Nee Gebruik Indirect-topologie (Y). Installeer de Hybrid Connector op de lokale sitecomputer.
Matrix met functiebeschikbaarheid voor Hybrid Push
De onderstaande tabel toont elke combinatie van communicatiemethode en implementatietopologie, en welke API-functies in elk geval beschikbaar zijn. Gebruik deze naast de beslisboom om te bevestigen wat uw gekozen configuratie ondersteunt.
| Modus |
Communicatie |
Topologie |
Callback API |
RESTful API |
| Direct Device |
(a) Device SDK |
(X) Publiek IP |
Volledig |
Volledig (SDK-beperkingen van toepassing) |
| Indirect Device |
(a) Device SDK |
(Y) Hybrid Connector |
Volledig |
Volledig (SDK-beperkingen van toepassing) |
| Direct DB |
(b) DB Pull |
(X) Publiek IP |
Alleen aanwezigheid |
Niet ondersteund |
| Indirect DB |
(b) DB Pull |
(Y) Hybrid Connector |
Alleen aanwezigheid |
Niet ondersteund |
| Direct File |
(c) Bestandsverwerking |
(X) Publiek IP |
Alleen aanwezigheid |
Niet ondersteund |
| Indirect File |
(c) Bestandsverwerking |
(Y) Hybrid Connector |
Alleen aanwezigheid |
Niet ondersteund |
Belangrijke waarschuwing over hardware
Hardwarebeperkingen kunnen API-functies verder beperken, zelfs binnen de Device SDK-modus. Specifieke API's werken mogelijk niet, afhankelijk van de firmwareversie van het apparaatmodel of de mogelijkheden die de SDK van de fabrikant beschikbaar stelt. De bovenstaande matrix beschrijft wat de Gateway-architectuur ondersteunt, niet wat elk afzonderlijk apparaatmodel gegarandeerd ondersteunt. Test altijd met uw specifieke hardware en verifieer randgevallen met het Cams-supportteam voordat u in productie gaat.
Wat de topologiebeslissing wel en niet beïnvloedt
Een veelvoorkomende bron van verwarring is de relatie tussen topologie en API-beschikbaarheid. De topologiekeuze, Direct of Indirect, beïnvloedt niet welke API-functies beschikbaar zijn. De set API-functies wordt volledig bepaald door de communicatiemethode.
Wat de topologie wel beïnvloedt, is hoe de netwerkverbinding tussen de Gateway en uw lokale omgeving tot stand komt. De Direct-topologie vereist een publiek IP en portforwarding op de locatie. De Indirect-topologie vereist dat de Hybrid Connector op de lokale machine is geïnstalleerd. De API-functies die beschikbaar zijn, zijn identiek voor Direct Device SDK en Indirect Device SDK, en identiek voor Direct DB Pull en Indirect DB Pull.
“Kies uw communicatiemethode op basis van de API-functies die uw integratie nodig heeft. Kies uw topologie op basis van wat uw netwerkomgeving ondersteunt. Dit zijn onafhankelijke beslissingen.”
Veelgestelde vragen
Kan ik DB Pull of Bestandsverwerking gebruiken naast RESTful API-opdrachten?
Nee. DB Pull en Bestandsverwerking zijn integratiemethoden die alleen lezen. Ze stellen de Gateway in staat om aanwezigheidsgegevens te observeren die door de eigen software van het apparaat worden gegenereerd, maar ze vormen geen kanaal waarlangs opdrachten terug naar het apparaat kunnen worden gestuurd. RESTful API-bewerkingen zoals gebruikers toevoegen, registraties verwijderen of logs laden vereisen de Device SDK-modus, die een bidirectioneel communicatiekanaal tot stand brengt.
Moet de Hybrid Connector op dezelfde machine worden geïnstalleerd als de apparaatsoftware?
Ja. De Hybrid Connector moet worden geïnstalleerd op dezelfde lokale computer waarop het apparaat is aangesloten of waarop de beheersoftware van het apparaat draait. Dit komt doordat de Connector lokale toegang nodig heeft tot het apparaat, de lokale database of het aanwezigheidsbestand, afhankelijk van uw communicatiemethode. De Connector legt vervolgens een uitgaande tunnel naar de Gateway aan, waardoor op die locatie geen publiek IP-adres nodig is.
Wat is het verschil in latentie tussen Native Push en Hybrid Push?
Bij Native Push worden Callback API-gebeurtenissen zonder vertraging afgeleverd en worden RESTful API-opdrachten in ongeveer 30 seconden uitgevoerd. Bij Hybrid Push met Device SDK hangt de latentie af van de eigen communicatiecyclus van de SDK en verschilt deze per fabrikant van het apparaat. De latentie van DB Pull en Bestandsverwerking hangt af van hoe vaak de lokale software nieuwe registraties schrijft en hoe snel de Gateway de wijziging detecteert. Doorgaans gebeurt dit binnen enkele seconden nadat het apparaat de gebeurtenis heeft vastgelegd.
Conclusie: stem uw modus af op uw beperkingen
De keuze van de verbindingsmodus voor de Cams Biometric Gateway is geen kwestie van voorkeur. Het is een kwestie van beperkingen. Native Push is het juiste antwoord als uw apparaat in aanmerking komt, omdat het de meeste mogelijkheden biedt met de minste configuratie. Hybrid Push is het antwoord voor al het andere, en binnen Hybrid Push biedt de Device SDK-modus de meest vergelijkbare ervaring met Native Push op het gebied van API-toegang.
Wanneer volledige SDK-toegang niet beschikbaar is, zijn DB Pull en Bestandsverwerking praktische opties die nog steeds aanwezigheidsgegevens in realtime aan uw systemen leveren. De topologiebeslissing is dan een afzonderlijke keuze op infrastructuurniveau, die niet verandert wat de API kan doen.
Begin met de beslisboom, controleer uw keuze aan de hand van de functiematrix, test met uw hardware en verifieer eventuele randgevallen met het Cams-supportteam voordat u in productie gaat.