Todo dispositivo biométrico que se conecta ao Gateway Biométrico Cams faz isso por meio de um dos dois modos de push. O modo utilizado pelo seu dispositivo determina quais APIs estão disponíveis, como os eventos são entregues e como a sua infraestrutura precisa ser configurada. Este guia percorre cada variável da decisão, desde o tipo de dispositivo até o método de comunicação e a topologia de implantação, para que você possa escolher o caminho certo antes de começar a desenvolver.
A Primeira Pergunta: Que Tipo de Dispositivo Você Está Conectando?
Antes de escolher um método de comunicação ou uma topologia de implantação, há uma questão mais fundamental a responder: seu dispositivo é um dispositivo Cams Biometrics ou um dispositivo verificado no portal de desenvolvedores Cams?
A resposta a essa pergunta determina totalmente o seu modo de push. Se a resposta for sim, você utiliza o Push Nativo e não é necessária nenhuma outra decisão. Se a resposta for não, você está no território do Push Híbrido e uma série de decisões adicionais se seguirá.
Modo 1
Push Nativo
Para todas as máquinas Cams Biometrics e qualquer dispositivo listado como verificado em developer.camsbiometrics.com. O dispositivo se comunica diretamente com o Gateway Biométrico pela internet, sem necessidade de configuração adicional.
Todas as 38 operações
Callback API completa
RESTful API completa
Modo 2
Push Híbrido
Para todos os demais dispositivos não verificados. Você seleciona um método de comunicação e uma topologia de implantação que se adequem ao seu ambiente. A disponibilidade das APIs depende da combinação escolhida.
3 métodos de comunicação
2 opções de topologia
Acesso variável às APIs
Push Nativo: o quadro completo
Dispositivos com Push Nativo têm acesso completo a todas as 38 operações do Gateway, sem configuração além de conectar o dispositivo à internet. A Callback API entrega eventos com latência zero. Os comandos da RESTful API são executados em aproximadamente 15 segundos. Não há SDK, nem software local, nem decisão de topologia.
Entendendo o Push Híbrido: Três Métodos de Comunicação
Se o seu dispositivo não for um dispositivo Cams ou verificado, a próxima decisão é como o Gateway irá efetivamente se comunicar com o seu hardware. Há três métodos de comunicação disponíveis, e cada um tem requisitos diferentes e implicações distintas sobre quais recursos da API você pode usar.
O método de comunicação não diz respeito à sua configuração de rede. Ele diz respeito ao mecanismo técnico que o Gateway utiliza para ler dados do seu dispositivo específico e enviar comandos a ele. Essa escolha é limitada pelo que o seu hardware suporta.
a
SDK do Dispositivo
Melhor opção para acesso completo às APIs
O Gateway se comunica com o hardware usando o SDK do fabricante do dispositivo. O SDK cuida do protocolo de baixo nível do dispositivo, e o Gateway expõe, por meio de sua API, todos os recursos suportados pelo SDK. Este é o único método de comunicação no Push Híbrido que permite operações da RESTful API.
Callback API completa + RESTful API completa (dentro dos recursos do SDK)
b
Pull de BD
Apenas dados de frequência
O Gateway lê de um banco de dados local no qual o próprio software de gerenciamento do dispositivo grava os registros de frequência. O Gateway monitora esse banco de dados e envia os novos registros para a sua URL de callback em tempo real. Não ocorre comunicação direta com o dispositivo, o que significa que nenhum comando pode ser enviado a ele. Operações como adicionar usuários, excluir registros ou carregar logs não estão disponíveis.
Callback API: apenas frequência e logs de marcação de ponto. RESTful API: não suportada.
c
Processamento de Arquivo
Apenas dados de frequência
Um arquivo de frequência designado no computador local é mantido sob monitoramento contínuo. Sempre que o software do dispositivo atualiza esse arquivo com novos registros de frequência, o Gateway detecta a alteração, extrai os novos registros e os envia para a sua URL de callback em tempo real. Assim como o Pull de BD, este método é somente leitura do ponto de vista do dispositivo e apresenta as mesmas limitações de API.
Callback API: apenas frequência e logs de marcação de ponto. RESTful API: não suportada.
Como escolher um método de comunicação
Se o seu dispositivo possuir um SDK do fabricante suportado pelo Gateway Cams, escolha o SDK do Dispositivo (a). É o único método que libera operações da RESTful API para dispositivos com Push Híbrido. Se o SDK não for suportado ou não estiver disponível, o Pull de BD (b) ou o Processamento de Arquivo (c) ainda entregarão os dados de frequência ao seu endpoint de callback em tempo real, o que é suficiente para muitos casos de uso.
Entendendo o Push Híbrido: Duas Topologias de Implantação
Depois de escolher um método de comunicação, a segunda decisão é onde o Gateway se conecta ao seu dispositivo, banco de dados ou arquivo. Esta é a decisão de topologia, e ela depende do ambiente de rede no local físico do dispositivo.
Topologia X
Direta
O computador do local onde o dispositivo está conectado, ou onde o software de gerenciamento do dispositivo é executado, possui um endereço IP público com redirecionamento de portas configurado para a rede local. O Gateway Biométrico se conecta diretamente ao dispositivo, ao banco de dados ou aos arquivos pela internet.
Requer: IP público + redirecionamento de portas no local
Topologia Y
Indireta
Um aplicativo Hybrid Connector é instalado no computador local. Ele atua como uma ponte de saída entre a máquina local e o Gateway Biométrico, estabelecendo a conexão a partir do lado interno, em vez de exigir uma conexão de entrada. Não é necessário IP público do lado do cliente.
Requer: Hybrid Connector instalado no computador local. IP público não necessário.
Recomendação de topologia
Se você não puder configurar um IP público ou redirecionamento de portas no local, escolha a topologia Indireta (Y) com o Hybrid Connector. É o caminho de implantação mais simples e evita totalmente a configuração de rede do lado do cliente. Se houver um IP público disponível e configurado, a topologia Direta (X) também funciona e não exige instalação de software adicional no local.
A Árvore de Decisão: Qual Modo Você Deve Escolher?
Percorra esta árvore de decisão de cima para baixo. Pare na primeira resposta que se aplicar à sua situação.
Árvore de decisão, comece pelo topo
1. Seu dispositivo é um dispositivo Cams Biometrics ou está listado como verificado em developer.camsbiometrics.com?
Sim Use Push Nativo. Acesso completo às APIs. Não são necessárias outras decisões.
Não Continue para a pergunta 2.
2. O Gateway Cams suporta o SDK do fabricante do seu dispositivo?
Sim Use Push Híbrido, SDK do Dispositivo (a). Callback e RESTful API completas dentro dos limites do SDK. Continue para a pergunta 3 para a topologia.
Não Continue para a pergunta 2b.
2b. O software de gerenciamento do dispositivo grava registros de frequência em um banco de dados local?
Sim Use Push Híbrido, Pull de BD (b). Apenas Callback de frequência. Continue para a pergunta 3 para a topologia.
3. O computador do local possui um endereço IP público com redirecionamento de portas disponível?
Sim Use Topologia Direta (X). Nenhum software adicional necessário no local.
Não Use Topologia Indireta (Y). Instale o Hybrid Connector no computador local do site.
Matriz de Disponibilidade de Recursos do Push Híbrido
A tabela abaixo mostra todas as combinações de método de comunicação e topologia de implantação, e quais recursos de API estão disponíveis em cada caso. Use-a junto com a árvore de decisão para confirmar o que a configuração escolhida suporta.
| Modo |
Comunicação |
Topologia |
Callback API |
RESTful API |
| Dispositivo Direto |
(a) SDK do Dispositivo |
(X) IP Público |
Completa |
Completa (limites do SDK se aplicam) |
| Dispositivo Indireto |
(a) SDK do Dispositivo |
(Y) Hybrid Connector |
Completa |
Completa (limites do SDK se aplicam) |
| BD Direto |
(b) Pull de BD |
(X) IP Público |
Apenas frequência |
Não suportada |
| BD Indireto |
(b) Pull de BD |
(Y) Hybrid Connector |
Apenas frequência |
Não suportada |
| Arquivo Direto |
(c) Processamento de Arquivo |
(X) IP Público |
Apenas frequência |
Não suportada |
| Arquivo Indireto |
(c) Processamento de Arquivo |
(Y) Hybrid Connector |
Apenas frequência |
Não suportada |
Importante: ressalva sobre o hardware
Limitações de hardware podem restringir ainda mais os recursos da API, mesmo no modo Device SDK. APIs específicas podem não funcionar dependendo da versão de firmware do modelo do dispositivo ou dos recursos expostos pelo SDK do fabricante. A matriz acima descreve o que a arquitetura do Gateway suporta, e não o que cada modelo de dispositivo individual tem garantia de suportar. Sempre teste com o seu hardware específico e verifique casos extremos com a equipe de suporte Cams antes da implantação em produção.
O Que a Decisão de Topologia Afeta e o Que Não Afeta
Uma fonte comum de confusão é a relação entre topologia e disponibilidade de APIs. A escolha da topologia, seja Direta ou Indireta, não afeta quais recursos de API estão disponíveis. O conjunto de recursos da API é determinado inteiramente pelo método de comunicação.
O que a topologia afeta é a forma como a conexão de rede entre o Gateway e o seu ambiente local é estabelecida. A topologia Direta exige um IP público e redirecionamento de portas no local. A topologia Indireta exige que o Hybrid Connector seja instalado na máquina local. Os recursos de API disponíveis para você são idênticos para o SDK do Dispositivo Direto e o SDK do Dispositivo Indireto, e idênticos para o Pull de BD Direto e o Pull de BD Indireto.
“Escolha o seu método de comunicação com base nos recursos de API que a sua integração precisa. Escolha a sua topologia com base no que o seu ambiente de rede suporta. São decisões independentes.”
Perguntas Frequentes
Posso usar o Pull de BD ou o Processamento de Arquivo junto com comandos da RESTful API?
Não. O Pull de BD e o Processamento de Arquivo são métodos de integração somente leitura. Eles permitem que o Gateway observe os dados de frequência gerados pelo próprio software do dispositivo, mas não estabelecem um canal pelo qual comandos possam ser enviados de volta ao dispositivo. Operações da RESTful API, como adicionar usuários, excluir registros ou carregar logs, exigem o modo SDK do Dispositivo, que cria um canal de comunicação bidirecional.
O Hybrid Connector precisa ser instalado na mesma máquina do software do dispositivo?
Sim. O Hybrid Connector deve ser instalado no mesmo computador local onde o dispositivo está conectado ou onde o software de gerenciamento do dispositivo é executado. Isso ocorre porque ele precisa de acesso local ao dispositivo, ao banco de dados local ou ao arquivo de frequência, dependendo do seu método de comunicação. Em seguida, o Connector cria um túnel de saída para o Gateway, eliminando a necessidade de um IP público nesse local.
Qual é a diferença de latência entre o Push Nativo e o Push Híbrido?
No Push Nativo, os eventos da Callback API são entregues com latência zero, e os comandos da RESTful API são executados em aproximadamente 30 segundos. No Push Híbrido com SDK do Dispositivo, a latência depende do próprio ciclo de comunicação do SDK e varia conforme o fabricante do dispositivo. A latência do Pull de BD e do Processamento de Arquivo depende da frequência com que o software local grava novos registros e da rapidez com que o Gateway detecta a alteração, normalmente em poucos segundos após o dispositivo registrar o evento.
Conclusão: Alinhe o Seu Modo às Suas Restrições
A decisão do modo de conexão para o Gateway Biométrico Cams não é uma questão de preferência. É uma questão de restrições. O Push Nativo é a resposta certa se o seu dispositivo se qualificar, pois oferece a maior capacidade com a menor configuração. O Push Híbrido é a resposta para todos os demais casos e, dentro dele, o modo SDK do Dispositivo oferece o equivalente mais próximo ao Push Nativo em termos de acesso às APIs.
Quando o acesso completo ao SDK não estiver disponível, o Pull de BD e o Processamento de Arquivo são caminhos pragmáticos que ainda entregam dados de frequência em tempo real aos seus sistemas. A decisão de topologia é, então, uma escolha separada, de nível de infraestrutura, que não altera o que a API pode fazer.
Comece pela árvore de decisão, confirme a sua escolha na matriz de recursos, teste com o seu hardware e verifique quaisquer casos extremos com a equipe de suporte Cams antes de passar para a produção.