Simplifier l'API REST PLCnext : configurer un reverse proxy

L'interface REST PLCnext est un outil fantastique pour présenter et recevoir des données d'un système back-end. REST (REpresentational State Transfer) est un style d'architecture logicielle avec directives et bonnes pratiques pour créer des services web scalables. Beaucoup d'infos sur le PLCnext infoportal. Les URI fournies par le firmware PLCnext sont parfaites si vous construisez votre système from scratch. Mais elles ne sont pas idéales pour rétrofiter une interface REST existante sur PLCnext. Ce blog montre comment configurer vos propres URI et les connecter à vos variables via un reverse proxy. Partons d'un petit exemple !

Prérequis

J'utilise un AXC F 2152 avec FW2020.6 et PLCnext Engineer 2020.6. Possible avec versions antérieures postérieures à 2020.0. J'utilise PuTTY pour SSH et Postman pour les requêtes HTTP. J'ai désactivé l'authentification pour le développement, ne faites pas ça en production ! Les instructions PLCnext Engineer sont données à haut niveau. Le contrôleur a l'IP 192.168.10.10, adaptez à votre adresse.

Exemple

J'utilise un UDT pompe simple. Téléchargez le programme exemple sur cette page GitHub ou créez le vôtre. Désactivez « user management » dans les paramètres eHMI et créez une variable globale. Utilisez-la sur une page eHMI pour l'utiliser dans l'API.

Premier appel API

Découvrons d'abord ce qu'on va modifier ! Envoyez une requête GET pour obtenir la valeur de la première pompe.

Avec Postman, envoyez GET vers :

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

(Remplacez Pump1 par votre variable)

Résultat :

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

Configurer un endpoint personnalisé

Ouvrez une session shell, créez un mot de passe root et connectez-vous en root.
Tapez la commande suivante dans votre terminal, allez au « bas » du terminal et attention à ne rien taper entre-temps !

nano /etc/nginx/nginx.conf

Copiez-collez la partie suivante dans le terminal, sauvegardez avec Ctrl+S et fermez avec Ctrl+X.

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

Envoyer une requête vers le nouvel endpoint

Envoyez un nouveau GET avec Postman vers :

GET https://192.168.10.10/Pump1

Même réponse ? Félicitations, votre proxy est configuré avec succès !

Configurer plusieurs pompes

Et si j'ai plusieurs pompes ? Une approche : faire un tableau contenant les UDT pompe. On peut récupérer tout le tableau en appelant la variable, ou juste l'élément souhaité en spécifiant l'index entre crochets, ex: Pump2[1] donne l'élément d'index 1 du tableau Pump2.

Mais ce n'est pas le sujet. On peut aussi configurer le proxy pour accéder à plusieurs pompes.
Modifiez le texte collé précédemment pour correspondre au schéma suivant :

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

Un GET vers le premier URI donne le même résultat qu'avant. Un GET vers le second donne un tableau du même type de données.

https://192.168.10.10/pumps/Pump1
https://192.168.10.10/pumps/Pump2

Vous avez maintenant tout pour adapter n'importe quel schéma API et l'intégrer dans votre périphérique PLCnext !

Lectures complémentaires

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