Configuração do Driver REST API Client do E3 para a API da Alertus.

2. Como o driver REST API Client funciona

O Driver Elipse REST API Client é um driver de comunicação (I/O) que atua como cliente HTTP/HTTPS. A configuração é feita na caixa de diálogo do driver, dividida em abas:

• API URL: a raiz comum a todos os endpoints (protocolo, domínio e, quando necessário, porta), como https://api.exemplo.com ou https://api.exemplo.com:8080.
• Auth: o tipo de autenticação usado nas rotas que a exigem.
• Routes: cada endpoint (rota) da API, com seu método e um apelido (Route Alias).
• Templates: os modelos JSON de requisição e de resposta.

Depois de configuradas as abas, a comunicação acontece por meio de Tags: um Tag Bloco de Recebimento lê respostas por varredura, e um Tag PLC (ou Tag Bloco de Envio) dispara requisições de comando.

3. Autenticação (aba Auth)

A documentação da Alertus (Swagger) indica securityDefinitions: BasicAuth, ou seja, a API usa autenticação básica. Na aba Auth do driver:

• Em Auth Type, selecione Basic Auth (as opções são No Auth, Basic Auth e Bearer Token).
• Preencha Username e Password com as credenciais fornecidas pela Alertus.

Nas rotas que exigem autenticação, marque a opção Auth Required (na aba Routes) para que o driver aplique a esse endpoint o tipo configurado em Auth Type. Os parâmetros Content-Type e Authorization são inseridos automaticamente como cabeçalhos e não precisam ser configurados manualmente.

4. API URL e rotas (aba Routes)

Defina a API URL com a parte comum a todos os endpoints. No exemplo da Alertus:

https:///alertusmw/services/rest

Na aba Routes, cadastre uma rota para cada endpoint, informando o Endpoint, o método HTTP e um Route Alias (o apelido usado depois para vincular as Tags; atenção: o alias diferencia maiúsculas de minúsculas). Para os dois endpoints usados na integração:

Segmentos dinâmicos do caminho são indicados por dois-pontos: em /activation/preset/:id, o :id é substituído em tempo de execução pelo valor informado via Tag. Clique duas vezes na rota (ou botão direito, opção Edit) para abrir a janela Params Config, onde se declara o parâmetro de rota :id, além de parâmetros de query e de header, cada um com Default Value, Regex Validator e Is Mandatory opcionais.

5. Templates JSON: E3VAL e Repeat_E3VAL

Os templates (aba Templates) descrevem o formato da mensagem e marcam, com palavras-chave, os trechos que viram dados. As principais são:

• E3VAL: marca um valor a ser extraído (ou escrito).
• Repeat_E3VAL: colocada imediatamente após o [ que abre um array, faz o driver disparar o evento OnRead uma vez para cada conjunto de dados do array.

O endpoint /alertDevices/details devolve um array de objetos (um por dispositivo). Para tratar cada dispositivo separadamente, use Repeat_E3VAL logo após o [ do array:

{
  "TagData": [
    Repeat_E3VAL {
      "name": "E3VAL",
      "id": "E3VAL",
      "deviceTypeId": "E3VAL",
      "notes": "E3VAL",
      "latitude": "E3VAL",
      "longitude": "E3VAL",
      "lastVerifiedCheckinDate": "E3VAL"
    }
  ]
}

Com esse template, ao receber a resposta o driver dispara o evento OnRead do Tag Bloco de Recebimento uma vez por dispositivo. Isso permite tratar cada registro por script, inclusive diferenciar o tipo de equipamento pelo campo deviceTypeId: sirene (9), CCU (12) e Alertus Desktop (2).

' Evento OnRead do Tag Bloco de Recebimento (uma execucao por dispositivo)
Sub AlertDevices_OnRead()
  Dim tipo, nome
  tipo = Item("deviceTypeId").Value   ' 9 = sirene, 12 = CCU, 2 = Alertus Desktop
  nome = Item("name").Value
  ' ... encaminhe os valores para as Tags internas da aplicacao ...
  Application.Trace nome & " (tipo " & tipo & ")"
End Sub

O tratamento por script desse tipo de resposta JSON está detalhado no artigo relacionado ao final desta página.

Para o /activation/preset/:id, o corpo da requisição é vazio. Nesse caso não é necessário template: basta o parâmetro de rota :id.

6. Mapeamento de Tags (recebimento e comando)

A integração usa dois tipos de Tag, cada um com o parâmetro Item no formato < Route Alias >;< Template Name >:

Leitura de status/telemetria: um Tag Bloco de Recebimento (somente leitura) apontando para a rota e o template do dispositivo, lido por varredura (ScanTime):

Item = "AlertDevicesDetails;TemplateAlertDevices"

Comando de acionamento: um Tag PLC (somente escrita) para disparar o preset. Qualquer escrita nesse Tag executa a requisição. Como o corpo é vazio, o template pode ser omitido:

Item = "ActivationPreset;"      ' ou "ActivationPreset;" se houver corpo
N1  = 1
N2  = 1                          ' metodo HTTP: 1 = POST

O parâmetro N2 do Tag PLC mapeia o método HTTP: 0 = GET, 1 = POST, 2 = PUT, 3 = DELETE. Como o acionamento do preset é um POST, use N2 = 1.

7. Boas práticas de periodicidade e organização

• Separe as rotas em Tags Bloco distintos. Não misture a leitura de status com o comando de ativação no mesmo bloco; um bloco por rota mantém a leitura e a escrita independentes.
• Ajuste o ScanTime ao tempo de resposta da API. Por se tratar de uma aplicação de segurança, use um tempo de varredura compatível com o que a própria Alertus recomenda, para não sobrecarregar o servidor.
• Confirme o método por endpoint. Cada rota tem seu método (GET para leitura, POST para acionamento); parametrize o N2 de acordo.

Artigos relacionados

• Consumindo e enviando dados de um webservice que utiliza o formato JSON