Cada dispositivo biométrico que se conecta al Cams Biometric Gateway lo hace mediante uno de los dos modos push. El modo que utiliza su dispositivo determina qué API están disponibles, cómo se entregan los eventos y cómo debe configurarse su infraestructura. Esta guía recorre cada variable de la decisión, desde el tipo de dispositivo hasta el método de comunicación y la topología de implementación, para que pueda elegir la vía adecuada antes de empezar a desarrollar.
La primera pregunta: ¿qué tipo de dispositivo está conectando?
Antes de elegir un método de comunicación o una topología de implementación, hay una cuestión más fundamental que responder: ¿su dispositivo es un dispositivo Cams Biometrics o un dispositivo verificado en el portal para desarrolladores de Cams?
La respuesta a esta pregunta determina por completo su modo push. Si la respuesta es sí, utiliza Native Push y no se necesita ninguna otra decisión. Si la respuesta es no, se encuentra en el ámbito de Hybrid Push y debe seguir una serie de decisiones adicionales.
Modo 1
Native Push
Para todas las máquinas Cams Biometrics y cualquier dispositivo indicado como verificado en developer.camsbiometrics.com. El dispositivo se comunica directamente con el Biometric Gateway a través de Internet, sin necesidad de configuración adicional.
Las 38 operaciones
Callback API completa
RESTful API completa
Modo 2
Hybrid Push
Para todos los demás dispositivos no verificados. Usted selecciona un método de comunicación y una topología de implementación que se ajusten a su entorno. La disponibilidad de la API depende de la combinación que elija.
3 métodos de comunicación
2 opciones de topología
Acceso a la API variable
Native Push: el panorama completo
Los dispositivos Native Push tienen acceso completo a las 38 operaciones del Gateway sin más configuración que conectar el dispositivo a Internet. La Callback API entrega los eventos sin latencia. Los comandos de la RESTful API se ejecutan en aproximadamente 15 segundos. No se requiere SDK, software local ni decisión de topología.
Comprender Hybrid Push: tres métodos de comunicación
Si su dispositivo no es un dispositivo Cams ni verificado, la siguiente decisión es cómo se comunicará realmente el Gateway con su hardware. Hay tres métodos de comunicación disponibles, y cada uno tiene requisitos distintos y implicaciones diferentes sobre qué funciones de la API puede utilizar.
El método de comunicación no depende de su configuración de red. Se refiere al mecanismo técnico que utiliza el Gateway para leer datos de su dispositivo específico y enviarle comandos. Esta elección está limitada por lo que admite su hardware.
a
Device SDK
Mejor opción para acceso completo a la API
El Gateway se comunica con el hardware mediante el SDK del fabricante del dispositivo. El SDK gestiona el protocolo de bajo nivel del dispositivo, y el Gateway expone a través de su API todas las funciones que admite el SDK. Es el único método de comunicación de Hybrid Push que permite las operaciones de la RESTful API.
Callback API completa + RESTful API completa (dentro de las capacidades del SDK)
b
DB Pull
Solo datos de asistencia
El Gateway lee de una base de datos local en la que el software de gestión propio del dispositivo escribe los registros de asistencia. El Gateway supervisa esta base de datos y envía los nuevos registros a su URL de callback en tiempo real. No se produce ninguna comunicación directa con el dispositivo, por lo que no pueden enviarse comandos al mismo. Operaciones como añadir usuarios, eliminar registros o cargar logs no están disponibles.
Callback API: solo asistencia y registros de fichaje. RESTful API: no admitida.
c
File Processing
Solo datos de asistencia
Un archivo de asistencia designado en el ordenador local se somete a vigilancia continua. Cada vez que el software del dispositivo actualiza este archivo con nuevos registros de asistencia, el Gateway detecta el cambio, extrae los nuevos registros y los envía a su URL de callback en tiempo real. Al igual que DB Pull, este método es de solo lectura desde la perspectiva del dispositivo y presenta las mismas limitaciones de API.
Callback API: solo asistencia y registros de fichaje. RESTful API: no admitida.
Cómo elegir un método de comunicación
Si su dispositivo dispone de un SDK del fabricante que es compatible con Cams Gateway, elija Device SDK (a). Es el único método que habilita las operaciones de la RESTful API para los dispositivos Hybrid Push. Si el SDK no es compatible o no está disponible, DB Pull (b) o File Processing (c) seguirán entregando los datos de asistencia a su endpoint de callback en tiempo real, lo que resulta suficiente para muchos casos de uso.
Comprender Hybrid Push: dos topologías de implementación
Una vez elegido el método de comunicación, la segunda decisión es dónde se conecta el Gateway a su dispositivo, base de datos o archivo. Esta es la decisión de topología, y depende de su entorno de red en la ubicación física del dispositivo.
Topología X
Directa
El ordenador del sitio donde está conectado el dispositivo, o donde se ejecuta el software de gestión del dispositivo, tiene una dirección IP pública con redirección de puertos configurada hacia la red local. El Biometric Gateway se conecta directamente al dispositivo, a la base de datos o a los archivos a través de Internet.
Requiere: IP pública + redirección de puertos en el sitio
Topología Y
Indirecta
Se instala una aplicación Hybrid Connector en el ordenador local del sitio. Actúa como puente saliente entre la máquina local y el Biometric Gateway, estableciendo la conexión desde el interior en lugar de requerir una conexión entrante. No se necesita IP pública en el lado del cliente.
Requiere: Hybrid Connector instalado en el ordenador local. No se necesita IP pública.
Recomendación de topología
Si no puede configurar una IP pública ni la redirección de puertos en el sitio, elija la topología indirecta (Y) con Hybrid Connector. Es la vía de implementación más sencilla y evita por completo la configuración de red en el lado del cliente. Si dispone de una IP pública y está configurada, la topología directa (X) también funciona y no requiere instalar software adicional en el sitio.
El árbol de decisión: ¿qué modo debe elegir?
Recorra este árbol de decisión de arriba abajo. Deténgase en la primera respuesta que se aplique a su situación.
Árbol de decisión, empiece por la parte superior
1. ¿Su dispositivo es un dispositivo Cams Biometrics o figura como verificado en developer.camsbiometrics.com?
Sí Use Native Push. Acceso completo a la API. No se necesitan más decisiones.
No Continúe con la pregunta 2.
2. ¿Cams Gateway admite el SDK del fabricante de su dispositivo?
Sí Use Hybrid Push, Device SDK (a). Callback y RESTful API completas dentro de los límites del SDK. Continúe con la pregunta 3 para la topología.
No Continúe con la pregunta 2b.
2b. ¿Su software de gestión del dispositivo escribe los registros de asistencia en una base de datos local?
Sí Use Hybrid Push, DB Pull (b). Solo Callback de asistencia. Continúe con la pregunta 3 para la topología.
3. ¿El ordenador del sitio dispone de una dirección IP pública con redirección de puertos disponible?
Sí Use Topología directa (X). No se necesita software adicional en el sitio.
No Use Topología indirecta (Y). Instale Hybrid Connector en el ordenador local del sitio.
Matriz de disponibilidad de funciones de Hybrid Push
La tabla siguiente muestra todas las combinaciones de método de comunicación y topología de implementación, así como las funciones de API disponibles en cada caso. Utilícela junto con el árbol de decisión para confirmar qué admite la configuración elegida.
| Modo |
Comunicación |
Topología |
Callback API |
RESTful API |
| Dispositivo directo |
(a) Device SDK |
(X) IP pública |
Completa |
Completa (se aplican límites del SDK) |
| Dispositivo indirecto |
(a) Device SDK |
(Y) Hybrid Connector |
Completa |
Completa (se aplican límites del SDK) |
| BD directa |
(b) DB Pull |
(X) IP pública |
Solo asistencia |
No admitida |
| BD indirecta |
(b) DB Pull |
(Y) Hybrid Connector |
Solo asistencia |
No admitida |
| Archivo directo |
(c) File Processing |
(X) IP pública |
Solo asistencia |
No admitida |
| Archivo indirecto |
(c) File Processing |
(Y) Hybrid Connector |
Solo asistencia |
No admitida |
Advertencia importante sobre el hardware
Las limitaciones de hardware pueden restringir aún más las funciones de la API incluso dentro del modo Device SDK. Algunas API pueden no funcionar según la versión de firmware del modelo del dispositivo o las capacidades que exponga el SDK del fabricante. La matriz anterior describe lo que admite la arquitectura del Gateway, no lo que cada modelo de dispositivo garantiza. Pruebe siempre con su hardware específico y verifique los casos límite con el equipo de soporte de Cams antes de la implementación en producción.
Qué afecta y qué no afecta la decisión de topología
Una fuente habitual de confusión es la relación entre la topología y la disponibilidad de la API. La elección de topología, ya sea directa o indirecta, no afecta a las funciones de API disponibles. El conjunto de funciones de la API lo determina por completo el método de comunicación.
Lo que sí afecta la topología es la forma en que se establece la conexión de red entre el Gateway y su entorno local. La topología directa requiere una IP pública y redirección de puertos en el sitio. La topología indirecta requiere que Hybrid Connector esté instalado en la máquina local. Las funciones de API disponibles para usted son idénticas en Direct Device SDK e Indirect Device SDK, y idénticas en Direct DB Pull e Indirect DB Pull.
“Elija su método de comunicación en función de las funciones de API que necesite su integración. Elija su topología en función de lo que admita su entorno de red. Son decisiones independientes.”
Preguntas frecuentes
¿Puedo usar DB Pull o File Processing junto con comandos de la RESTful API?
No. DB Pull y File Processing son métodos de integración de solo lectura. Permiten al Gateway observar los datos de asistencia generados por el software propio del dispositivo, pero no establecen un canal a través del cual puedan enviarse comandos de vuelta al dispositivo. Las operaciones de la RESTful API, como añadir usuarios, eliminar registros o cargar logs, requieren el modo Device SDK, que crea un canal de comunicación bidireccional.
¿Hybrid Connector debe instalarse en la misma máquina que el software del dispositivo?
Sí. Hybrid Connector debe instalarse en el mismo ordenador local donde está conectado el dispositivo o donde se ejecuta el software de gestión del dispositivo. Esto se debe a que necesita acceso local al dispositivo, a la base de datos local o al archivo de asistencia, según el método de comunicación utilizado. Después, Connector crea un túnel saliente hacia el Gateway, por lo que no es necesaria una IP pública en esa ubicación.
¿Cuál es la diferencia de latencia entre Native Push y Hybrid Push?
En Native Push, los eventos de la Callback API se entregan sin latencia y los comandos de la RESTful API se ejecutan en aproximadamente 30 segundos. En Hybrid Push con Device SDK, la latencia depende del propio ciclo de comunicación del SDK y varía según el fabricante del dispositivo. La latencia de DB Pull y File Processing depende de la frecuencia con la que el software local escribe nuevos registros y de la rapidez con la que el Gateway detecta el cambio, normalmente en pocos segundos desde que el dispositivo registra el evento.
Conclusión: ajuste su modo a sus limitaciones
La decisión del modo de conexión para el Cams Biometric Gateway no es una cuestión de preferencia, sino de limitaciones. Native Push es la respuesta correcta si su dispositivo cumple los requisitos, porque ofrece la mayor capacidad con la menor configuración. Hybrid Push es la respuesta para todo lo demás, y dentro de este modo, el modo Device SDK ofrece el equivalente más cercano a Native Push en términos de acceso a la API.
Cuando no está disponible el acceso completo al SDK, DB Pull y File Processing son vías pragmáticas que siguen entregando datos de asistencia en tiempo real a sus sistemas. La decisión de topología es entonces una elección independiente, de nivel de infraestructura, que no modifica lo que puede hacer la API.
Comience con el árbol de decisión, confirme su elección con la matriz de funciones, pruebe con su hardware y verifique cualquier caso límite con el equipo de soporte de Cams antes de pasar a producción.