Otimizando API REST PLCnext: Configurando Reverse Proxy

A Interface REST PLCnext é ferramenta fantástica tanto para apresentar quanto receber dados de sistema back-end. REST, ou REpresentational State Transfer, é estilo de arquitetura de software com guidelines e best practices para criar web services escaláveis. Há muita informação no PLCnext infoportal, confira! As URIs fornecidas pelo firmware PLCnext são perfeitas se você constrói sistema do zero. Mas não são ideais se quer adaptar interface REST existente no PLCnext. Este blog mostra como configurar suas próprias URIs e conectá-las às variáveis com reverse proxy. Começamos com exemplo simples e evoluímos!

Pré-requisitos

Uso controlador AXC F 2152 com FW2020.6 e PLCnext Engineer 2020.6. Mesmo procedimento possível com versões anteriores posteriores a 2020.0. Uso PuTTY para SSH e Postman para requisições HTTP. Desativei autenticação para desenvolvimento, não faça o mesmo em produção! Instruções PLCnext Engineer em alto nível; se inseguro, consulte infoportal e vídeos ou compare com projeto exemplo. Meu controlador tem IP 192.168.10.10, altere para seu IP.

Exemplo

Uso UDT de bomba simples como exemplo. Baixe programa exemplo desta página GitHub ou crie o seu. Desative "user management" nas configurações eHMI e crie variável global. Use esta variável em página eHMI para usar na API.

Primeira chamada API

Primeiro, descubra o que estamos mudando! Envie GET para obter valor da primeira bomba.

Use Postman para enviar GET para:

GET https://192.168.10.10/_pxc_api/api/variables?paths=Arp.Plc.Eclr/Pump1

(Altere Pump1 para sua variável)

Resultado:

{
  "apiVersion": "1.4.0.0",
  "projectCRC": 3448945666,
  "userAuthenticationRequired": true,
  "variables": [
    {
      "path": "Arp.Plc.Eclr/Pump1",
      "value": {
        "xStatus": false,
        "iNumberOfStarts": 0,
        "sStatus": ""
      }
    }
  ]
}

Configurando endpoint personalizado

Abra sessão shell, crie senha root e logue como root.
Digite comando no terminal, vá ao "final" do terminal e cuidado para não digitar nada no meio!

nano /etc/nginx/nginx.conf

Copie e cole a próxima parte no terminal, salve com Ctrl+S e feche com Ctrl+X.

location /Pump1 {
  proxy_pass https://127.27.0.1:443/_pxc_api/api/variables?paths=Arp.Plc.Eclr/Pump1;
}

Enviando requisição ao novo endpoint

Envie novo GET com Postman para:

GET https://192.168.10.10/Pump1

Recebeu mesma resposta? Parabéns, seu proxy foi configurado com sucesso!

Configurando múltiplas bombas

Ok, mas e se tenho múltiplas bombas? Uma abordagem: array com UDT de bomba. Obtém array todo chamando variável ou só elemento especificando índice entre colchetes, ex: Pump2[1] dá elemento índice 1 no array Pump2.

Mas não é o foco. Também podemos configurar proxy para acessar múltiplas bombas.
Modifique o texto colado anteriormente para:

location /pumps {
  proxy_pass https://127.27.0.1:443/_pxc_api/api/variables?paths=Arp.Plc.Eclr;
}

Enviando GET com Postman para primeira URI dá mesmo resultado anterior. Enviando GET para segunda URI dá array do mesmo datatype.

https://192.168.10.10/pumps/Pump1

https://192.168.10.10/pumps/Pump2

Agora você tem tudo para adaptar qualquer esquema API e integrar no seu dispositivo PLCnext!

Leituras adicionais

• What is an API?
• HTTP Methods
• What is an API and why should I use one?
• REST API Design Tutorial