Le code source de ce package est en ligne sur : https://github.com/myconstellation/constellation-packages/tree/master/NetworkTools

Installation

Depuis le “Online Package Repository” de votre Console Constellation, déployez le package NetworkTools :

Une fois le package télécharger votre repository local, sélectionnez la sentinelle sur laquelle déployer le package.

Pour finir, sur la page de Settings, vous pouvez définir les ressources à monitorer :

Si vous n’avez rien à monitorer vous pouvez supprimer (bouton “Remove”) le setting ou encore effacer le JSON. La configuration du monitoring réseau est expliquée ci-dessous.

Bien entendu vos  pouvez également déployer ce package manuellement dans la configuration de votre Constellation. Par exemple sans aucun monitoring :

<package name="NetworkTools" / >

Configurer le monitoring

Ce package expose différentes fonctions (MessageCallbacks) dans votre Constellation pour tester des ressources réseau (Site Web HTTP, port TCP, Ping, résolution DNS, scanner de port, etc..). Il peut aussi monitorer à intervalle régulier des ressources réseau et publier le résultat dans les StateObjects Constellation.

Pour cela le paramètre  “Monitoring” est un tableau JSON qui contient la liste des ressources à monitoring.

Il y a trois type de monitoring :

• Ping : effectue un ping (IMCP Echo) vers une adresse IP ou DNS
• Tcp : effectue un test d’ouverture de socket que un port TCP
• Http : effectue un appel HTTP et optionnellement une vérification de la réponse

Chaque ressource à monitorer est identifiée par un nom qui sera utilisé comme nom de StateObject pour la publication du résultat.

De plus chaque ressource peut spécifier son intervalle de temps entre deux test (par défaut fixé à 60 secondes).

Par exemple pour pinger une machine toutes les minutes :

{ Name: "Ping My Machine", Type: "Ping", Hostname: "myhostname.mydomain.com" }

Pour pinger la même machine mais toutes les 10 secondes :

{ Name: "Ping My Machine", Type: "Ping", Hostname: "myhostname.mydomain.com", Interval:10 }

Pour monitorer un service TCP sur le port 80 toutes les 10 secondes :

{ Name: "My Web Server", Type: "TCP", Hostname: "myhostname.mydomain.com", Port: 80, Interval:10 }

Pour monitorer un site Web HTTP :

{ Name: "Check Sebastien.warin.fr", Type: "Http", Address: "http://sebastien.warin.fr" }

La même chopse mais en vérifiant le réponse HTTP avec une expression régulière :

{ Name: "Check Sebastien.warin.fr", Type: "Http", Address: "http://sebastien.warin.fr", Regex: "Le blog personnel et technique de Sebastien Warin", Interval: 30 }

Détails du package

Les Settings

Les StateObjects

Vous retrouverez autant de StateObjects que vous avez de ressources monitorées.

Par exemple

Les MessageCallbacks

Le package expose 6 MessageCallbacks :

Quelques exemples

• Envoyer une notification si une ressource réseau ne répond plus
• Surveiller ses ressources réseau (serveurs, services ou sites web) avec une bande de LED WS2801 et un Arduino/ESP

The post NetworkTools : surveillez et testez vos ressources réseau appeared first on Constellation.

Cette nouvelle version amène beaucoup de nouveautés que je vous propose de découvrir dans cet article. La librairie a été testé avec succès sur différentes cartes animées par un ESP8266 (ESP-01, 05, 07 et D1 Mini) ainsi qu’un Arduino/Genuino MKR1000.

Pour la mise à jour, téléchargez la libraire ci-dessous et dézippez les fichiers dans le dossier “Constellation” dans votre répertoire de libraire Arduino.

Attention : cette version 2.x de la librairie Constellation pour Arduino/ESP nécessite la version 1.8.1.16249 ou plus récente du serveur Constellation pour fonctionner correctement. Pour mettre à jour votre plateforme Constellation, lancez le Web Platform Installer.

Réception de message et StateObject “asynchrone”

Il s’agit d’une grosse évolution par rapport à la version 1.x. Pour “récupérer” du serveur Constellation les messages à destination de votre package virtuel ou les StateObjects pour lequel votre package (virtuel) s’est abonné, il faut invoquer les actions “GetMessages” et “GetStateObjects” sur l’interface REST.

Ces méthodes supportent le “long-polling” c’est à dire qu’elles mettent en attente la requête tant qu’il n’y a pas de messages ou StateObjects à retourner avec la notion de timeout (par défaut 60 secondes).

Le problème sur les versions 1.x de la libraire Arduino est que le client HTTP est “synchrone”, c’est à dire qu’il envoi la requête HTTP et attend la réponse du serveur pour traitement ce qui est incompatible avec du long-polling car cela bloquerait le code de l’Arduino. De ce fait, les anciennes versions spécifiées le “timeout” de ces requêtes à 1 seconde.

Ainsi jusqu’à maintenant, l’interrogation des messages et SO pouvaient bloquer jusqu’à 2 secondes votre Arduino (1 seconde pour le GetMessage et 1 seconde pour le GetStateObject) et engendrait donc 1 requêtes HTTP toutes les secondes entre votre ESP/Arduino et le serveur Constellation.

Dans cette nouvelle version, la librairie utilisent 3 clients HTTP différents : un pour toutes les requêtes synchrones, un pour la réception de message (GetMessage) et un pour la réception des StateObjects (GetStateObjects).

Le client synchrone est donc toujours disponible et il n’y a aucun blocage, aucune attente pour la réception de message et de SO. De plus il n’y a plus besoin de “poller” ou “flooder” le serveur d’une requête toute les secondes, en réactivant le long-polling le 2ème et 3ème client HTTP, on lance une requête toutes les minutes (60 sec par défaut) dans l’attente de message et SO.

De ce fait, il y a quelques modifications à apporter dans votre code !

Premièrement, vous ne devez plus passer la référence de votre client réseau mais plutôt spécifier le type de votre client dans le template de la classe Constellation. Par exemple, si vous utilisez un ESP8266 ou un Arduino MKR1000, vous utiliserez la classe “WifiClient “” :

/* Create the Constellation client */
Constellation<WiFiClient> constellation("constellation.monserveur.com", 8088, "MyVirtualSentine", "MyPackage", "MyAccessKey123!");

Ensuite, il n’y a plus besoin d’invoquer la méthode “poll” dans votre boucle principale avec un timer, vous devez tout simplement appeler la méthode “loop” autant de fois que vous voulez :

void loop(void) {
  // Process incoming message & StateObject updates
  constellation.loop();
}

Cette méthode vérifie en fait si il y a eu une réponse sur le client utilisé pour la réception de message et sur le client pour la réception de SO afin de les dispatcher dans votre code.

Support du PackageDescriptor

Autre nouveauté majeure pour cette version 2, le support du “Package Descriptor”.

Pour rappel le “Package Descriptor” est un objet envoyé par un package au serveur pour décrire ses StateObjects et ses MessageCallbacks exposés par le package.

Le MessageCallback Explorer de la Console Constellation s’appuie sur le “Package Descriptor” de chaque package pour lister chaque MessageCallback avec un formulaire de test. Sans cette description cela serait impossible !

Les versions 1.x ne supportaient pas “Package Descriptor”, de ce fait il n’était pas possible d’explorer/découvrir les MessageCallbacks d’un package Arduino/ESP. Vous devez nécessairement connaitre par vous même les MC exposés par le package et le type des StateObjects qu’il pouvait publier.

Avec la version 2.0, l’Arduino/ESP envoie au serveur la description des MC exposés et des types utilisés par les SO et arguments des MC.

Dans la suite de cet article, vous découvrirez comment ajouter des types dans la description de votre package, mais n’oubliez jamais d’envoyer votre “Package Descriptor” en invoquant la méthode “declarePackageDescriptor”, typiquement une fois votre code Arduino initialisé (par exemple à la fin de la méthode setup()) :

// Declare the package descriptor
constellation.declarePackageDescriptor();

Amélioration du PushStateObject

La méthode “PushStateObject” permet de publier un StateObject sur le serveur Constellation.

Tout d’abord la méthode expose des surcharges vous permettant de spécifier comme “value” de votre SO des int, uint, double, float, long et bool et supporte en paramètre optionnel le “lifetime”, c’st à dire la durée en seconde de “vie” de votre StateObject avant d’être considéré comme expiré.

// Dummy data
uint16_t lux = 123;

// Push a simple type on Constellation 
constellation.pushStateObject("DemoLux", lux);  

// Push a simple type on Constellation with lifetime of 20 seconds
constellation.pushStateObject("DemoLux", lux, 20);

Vous pouvez toujours publier des StateObjects dont la valeur (value) est un objet complexe (formaté en JSON).

Le JSON peut être formaté sous forme d’une chaine de caractère avec la méthode “stringFormat” :

// Push a complex object on Constellation with stringFormat
constellation.pushStateObject("DemoLux", stringFormat("{ 'Lux':%d, 'Broadband':%d, 'IR':%d }", lux, full, ir));

Vous pouvez également définir votre propre type pour ce StateObject, par exemple nommons cet objet “MyLuxData” :

constellation.pushStateObject("DemoLux", stringFormat("{ 'Lux':%d, 'Broadband':%d, 'IR':%d }", lux, full, ir), "MyLuxData");

Sans oublier d’ajouter ce type “personnalisé” dans le “package descriptor”. Par exemple, dans le “setup()” et avant de faire un “declarePackageDescriptor”, on aurait décrit “MyLuxData” de la façon suivante :

constellation.addStateObjectType("MyLuxData", TypeDescriptor().setDescription("MyLuxData demo").addProperty("Broadband", "System.Int32").addProperty("IR", "System.Int32").addProperty("Lux", "System.Int32"));

Pour finir, vous pouvez toujours publier un StateObject en construisant la valeur dans un objet JsonObject de façon suivante :

// Push a complex object on Constellation with JsonObject
const int BUFFER_SIZE = JSON_OBJECT_SIZE(5);
StaticJsonBuffer<BUFFER_SIZE> jsonBuffer;
JsonObject& myStateObject = jsonBuffer.createObject();
myStateObject["Lux"] = lux;
myStateObject["Broadband"] = full;
myStateObject["IR"] = ir;
constellation.pushStateObject("DemoLux", myStateObject);

Dans les surcharges de cette méthode, vous pouvez également spécifier le type de votre StateObject et/ou sa durée de vie :

constellation.pushStateObject("DemoLux", myStateObject, "MyLuxData", 20);

Pour finir, nouveauté de la librairie 2.0, vous pouvez également spécifier des “meta-données” à vos StateObjects. Par exemple :

// Ajout de metadatas au StateObject
JsonObject& metadatas = jsonBuffer.createObject();
metadatas["ChipId"] = ESP.getChipId();
metadatas["Timestamp"] = millis();
constellation.pushStateObject("DemoLux", myStateObject, "MyStateObject", 20, &metadatas);

Les StateObjectLinks

En version 1.x de la librairie Arduino, vous pouvez :

• interroger des StateObjects de la Constellation en invoquant la méthode “requestStateObjects” qui vous retourne les StateObjects à l’instant T correspondant à votre requête :

// Example : print the all SO's value named "/intelcpu/0/load/0" and produced by the "HWMonitor" package (on all sentinels)
JsonArray& cpus = constellation.requestStateObjects("*", "HWMonitor", "/intelcpu/0/load/0");
for(int i=0; i < cpus.size(); i++) { 
  constellation.writeInfo("CPU on %s is currently %d %", cpus[i]["SentinelName"].asString(), cpus[i]["Value"]["Value"].as<float>());
}

• vous abonnez aux mises à jour des StateObjects pour être notifié en temps réel des que les SO changent :

// set a StateObject update callback and subscribe to SO
constellation.setStateObjectUpdateCallback([] (JsonObject& so) {
constellation.writeInfo("StateObject updated ! StateObject name = %s", so["Name"].asString()); 
});
// Subscribe to SO named "/intelcpu/0/load/0" and produced by the "HWMonitor" package (on all sentinels)
constellation.subscribeToStateObjects("*", "HWMonitor", "/intelcpu/0/load/0");

Vous pouvez invoquer plusieurs fois la méthode “subscribeToStateObjects” pour ajouter des abonnements à d’autre StateObjects mais il n’y a qu’un seul callback de réception des SO (défini par la méthode setStateObjectUpdateCallback). C’est à vous de “dispatcher” les SO reçus.

La nouveauté en 2.0 vient de l’ajout de la méthode “registerStateObjectLink” qui vous permet d’associer un callback à un abonnement laissant ainsi à la librairie la charge du “dispatch”.

Par exemple, on peut désormais écrire :

constellation.registerStateObjectLink("*", "HWMonitor", "/intelcpu/0/load/0", [](JsonObject& so) {
  constellation.writeInfo("CPU on %s is currently %d %", so["SentinelName"].asString(), so["Value"]["Value"].as<float>());
});

Ici on enregistre un “StateObject Link” sur tous les SO nommés « /intelcpu/0/load/0 » produits par le package “HWMonitor” de toutes les sentinelles de votre Constellation. Dès qu’un de ces StateObjects changent on exécutera le callback associé, qui ici écrit dans le log un message indiquant la nouvelle valeur du CPU.

Vous bien entendu enregistrer autant de StateObjectLink que vous souhaitez.

Enregistrement des MessageCallbacks

Le principe est le même que celui décrit ci-dessus pour les abonnements aux StateObjects.

En version 1.x, on devait définir un callback pour réception de message et invoquer la méthode “subscribeToMessage” :

// Set callback for all incoming messages
 constellation.setMessageReceiveCallback([](JsonObject& json) { 
   constellation.writeInfo("Message receive ! Message key = %s", json["Key"].asString());     
 }); 
 // Subscribe to message
 constellation.subscribeToMessage();

C’était donc à votre charge de “dispatcher” les messages reçus en fonction du “MessageKey”.

Désormais avec la version 2.0, vous pouvez enregistrer un callback pour un “MessageKey” donné. Par exemple :

constellation.registerMessageCallback("HelloWorld",
  [](JsonObject& json) {
    constellation.writeInfo("Hello Constellation !");
 });

Dans l’exemple ci-dessous, on ajoute/expose un MessageCallback “HelloWorld” qui écrit dans les logs !

Il n’y donc plus besoin de “dispatcher”, un MessageCallback est donc associé à un “MessageKey” unique et un callback. Il n’y a plus besoin non plus de faire un “subscribeToMessage” (cette méthode est invoquée implicitement par le registerMessageCallback).

De plus cette méthode ajoute implicitement les MessageCallbacks dans le Package Descriptor de sorte que chaque MC soit ainsi référencé dans la Constellation

(console)

Vous pouvez également passer un “MessageCallbackDescriptor” dans l’enregistrement de vos MC pour ajouter une description par exemple :

constellation.registerMessageCallback("HelloWorld",
  MessageCallbackDescriptor().setDescription("Say Hello to Constellation"),
  [](JsonObject& json) {
    constellation.writeInfo("Hello Constellation !");
 });

Et même définir les paramètres de vos MC :

constellation.registerMessageCallback("SayHello",
  MessageCallbackDescriptor().setDescription("Say hello !").addParameter("FirstName", "System.String").addParameter("LastName", "System.String"),
  [](JsonObject& json) {
    constellation.writeInfo("Hello %s %s", json["Data"][0].asString(), json["Data"][1].asString()); 
 });

Ici on déclare un MC nommé “SayHello” prenant deux paramètres de type String avec un texte de description. Dans la code nous verrons :

(console)

Tout comme les StateObjects, les types des arguments des MC peuvent être des types complexes.

Par exemple enregistrons un MC prenant un seul argument de type “SampleUserData” que nous allons décrire avec la méthode “addMessageCallbackType” comme un objet composé de deux propriétés de type String :

// Expose a MessageCallback with complex parameter :
constellation.registerMessageCallback("SayHello2",
  MessageCallbackDescriptor().setDescription("Say hello with complex object!").addParameter("User", "SampleUserData"),
  [](JsonObject& json) {
    constellation.writeInfo("Hello %s %s", json["Data"][0]["FirstName"].asString(), json["Data"][0]["LastName"].asString()); 
});  
// and describe the complex parameter "SampleUserData"  
constellation.addMessageCallbackType("SampleUserData", TypeDescriptor().setDescription("This is a smaple user data").addProperty("FirstName", "System.String").addProperty("LastName", "System.String"));

Enfin la méthode “registerMessageCallback” accepte également des callbacks prenant en paramètre le “MessageContext” :

constellation.registerMessageCallback("HelloWorld",
  MessageCallbackDescriptor().setDescription("Say Hello to Constellation"),
  [](JsonObject& json, MessageContext ctx) {
    constellation.writeInfo("Message received from %s", ctx.sender.friendlyName);
 });

L’objet “MessageContext” est défini de la façon suivante :

typedef struct {
    const char* sagaId;
    bool isSaga;
    const char* messageKey;
    MessageSender sender;
    ScopeType scope;
} MessageContext;

typedef struct {
    SenderType type;
    const char* friendlyName;
    const char* connectionId;
} MessageSender;

Vous pouvez donc récupérer les informations sur l’émetteur (Sender) du message, le scope et l’identifiant de Saga si c’est une saga (isSaga = true).

Support des Saga (messages avec réponse)

Une saga est un identifiant unique qu’on affecte à des messages pour les lier entre eux. Cela permet de faire des couples de message “Requête / Réponse”. Une “réponse” étant un message renvoyé à l’émetteur de la requête avec le même identifiant de saga pour que ce dernier puisse l’identifier comme la “réponse” à son message d’origine.

Vous pouvez exposer des MessageCallbacks qui “répondent”, c’est à dire des  MessageCallbacks qui retournent un message de réponse.

Par exemple, exposons un MC pour réaliser des Additions sur un Arduino. Vous enregistrerez un MC “Addition” prenant en parametre deux entiers et qui en retourne un (le résultat) :

constellation.registerMessageCallback("Addition",
  MessageCallbackDescriptor().setDescription("Do addition on this tiny device").addParameter("a", "System.Int32").addParameter("b", "System.Int32").setReturnType("System.Int32"),
  [](JsonObject& json, MessageContext ctx) {        
    int a = json["Data"][0].as<int>();      
    int b = json["Data"][1].as<int>();
    int result = a + b;
    constellation.writeInfo("Addition %d + %d = %d", a, b, result);      
    if(ctx.isSaga) {
      constellation.writeInfo("Doing additoon for %s (sagaId: %s)", ctx.sender.friendlyName, ctx.sagaId);   
    // Return the result :
      constellation.sendResponse<int>(ctx, result);
    }
    else {
      constellation.writeInfo("No saga, no response !");
    }
 });

Vous remarquerez dans le “MessageCallbackDescriptor” l’appel de la méthode “setReturnType” pour spécifier le type de retour (et que le fait qu’il s’agit d’un MC acceptant les sagas).

L’envoi de la réponse étant réalisé par la méthode sendReponse. Cette méthode a plusieurs surcharges :

template<typename T> bool sendResponse(MessageContext context, T data);
bool sendResponse(MessageContext context, const char* data, ...);
bool sendResponse(MessageContext context, JsonObject& data);

Notez aussi que vous devriez faire un “sendResponse” si et seulement le message reçu est associé à une saga, c’est à dire que le champs “isSaga” du contexte (MessageContext) est “vrai”. Sinon ca ne sert à rien de répondre

Pour finir, cette nouvelle version supporte également l’envoi de message dans une saga. C’est à dire que vous pouvez envoyer un message qui attend une réponse et donc enregistrer un callback de traitement de la réponse.

Par exemple le package “NetworkTools” expose un MC “Ping” permettant de faire un ping. Le package retourne dans la saga un message contenant le temps en milliseconde du ping. On pourrait alors invoquer cette méthode depuis notre Arduino de la façon suivante :

const char* ip = "192.168.0.10";
// Send message in a saga and attach a callback for response :
constellation.sendMessageWithSaga([](JsonObject& json) {
  constellation.writeInfo("Ping response in %s ms", json["Data"].asString()); 
}, Package, "NetworkTools", "Ping", "[ '%s' ]", ip);

Ici on envoi un message au scope “Package” pour atteindre le(x) package(s) “NetworkTools” afin d’invoquer le MessageCallback “Ping” en passant en argument l’IP à pinger. Vous remarquerez qu’on utilise le formatage implicite des arguments.

La méthode n’est pas la traditionnelle “sendMessage” mais “sendMessageWithSaga” qui prend un argument supplémentaire : le callback de traitement de la réponse.

Ainsi quand le package “NetworkTools” répondra, on executera le callback associé qui ici affichera le temps de réponse de notre ping (Data) dans les logs Constellation (writeInfo).

De ce fait, avec cette nouvelle libraire vos Arduino/ESP peuvent invoquer des MC dans sagas pour exploiter la réponse mais également exposer des MC qui retournent des résultats.

Autres nouveautés

En vrac, vous disposez maintenant une méthode “purgeStateObjects” permettant de supprimer des StateObjects de votre package.

De plus la méthode “setDebugMode” accepte en argument l’énumération “DebugMode” composée des valeurs suivantes :

• “Quiet” (mode silencieux, la libraire ne produit aucune trace dans l’interface Serial)
• “Normal” (mode par défaut, écrit quelques informations dans l’interface Serial)
• “Verbose” (écrit beaucoup d’information dans l’interface Serial comme par exemple les requêtes et réponse HTTP v ers Constellation)

Enfin les exemples fournis dans la libraire ont été complètement revus.

The post Nouvelle librairie Constellation pour Arduino / ESP8266 en version 2.0 appeared first on Constellation.

Si vous avez un serveur Windows, vous pouvez également utiliser IIS pour configurer un reverse proxy vers Constellation.

Dans cet article nous allons découvrir comment exposer le serveur Constellation derrière un serveur Nginx protégé avec un certificat SSL Let’s Encrypt.

Prérequis : avoir une Constellation exposée publiquement avec un nom DNS

Avant de démarrer vous devez avoir un serveur Constellation opérationel.

Si vous installez Constellation sur un Linux, cela se résume à lancer la commande ci-dessous et à suivre l’assistant :

wget -O install.sh https://developer.myconstellation.io/download/installers/install-linux.sh && chmod +x install.sh && ./install.sh

Pour plus d’information, veuillez suivre le guide : Installer Constellation sur Linux.

On considéra à ce stade que votre serveur Constellation est démarré et opérationnel. Vous pouvez lancer la commande suivante pour vérifier le statut des services Constellation :

sudo supervisorctl status

Vous devriez voir le “constellation-server” avec le statut “RUNNING” (et la sentinelle si déployée) :

sebastien@ubuntu:~$ sudo supervisorctl status
constellation-sentinel           RUNNING   pid 1194, uptime 1 day, 17:36:48
constellation-server             RUNNING   pid 2888, uptime 1 day, 15:06:41

Vous pouvez également installer Constellation sur un système Windows (voir le guide).

En effet, le reverse proxy (ici Ngnix) qui sera installé sur un système Linux peut exposer un service tel que Constellation quelque soit le serveur sur lequel il est déployé. Le reverse proxy n’est pas nécessairement sur la même machine sur le ou les services à exposer.

Il est donc possible d’installer un serveur Linux avec Nginx pour exposer en SSL un serveur Constellation sur un système Windows de la même manière que nous pouvons installer un serveur Windows avec IIS pour exposer en SSL un serveur Constellation sur un système Linux !

Dans ce guide nous avons installer le serveur Constellation et le reverse proxy Nginx sur le même serveur, sous Linux Ubuntu 16.

Si vous souhaitez activer le HTTPS et donc ajouter un certificat SSL, vous devez nécessairement avoir un nom DNS qui pointe vers l’adresse IP (public) de votre serveur de reverse proxy.

Plusieurs options s’offre à vous :

• Si vous avez un nom de domaine, modifiez votre zone DNS pour ajouter un “host” (enregistrement A ou AAAA) vers l’adresse IP (public) de votre Constellation.
• SI vous n’avez pas de nom de domaine :
  • Achetez-en un ! Comptez environ 15€/an pour les extensions standards (.fr, .net, .com), 2,99€ HT par an pour  un .ovh
  • Utilisez un service de “Dynamic DNS” comme dyndns.fr, dyn.com ou autre
  • Certains FAI comme Free proposent d’attacher un nom DNS type xxxx.hd.free.fr à votre IP de connexion
  • Certains NAS comme Synology permettent aussi de créer un DDNS type xxx.synology.me vers votre IP de connexion

Dans le cas présent, j’ai crée l’entrée DNS “demo.internal.myconstellation.io” qui pointe vers l’adresse IP public du serveur Constellation installé sur un Ubuntu (le DNS doit pointer votre le serveur où sera installé le reverse proxy dans la mesure où tout passera par lui. Etant donné que le reverse proxy sera sur le même serveur que le service Constellation on peut dire que le DNS pointe vers le serveur Constellation).

Bien évidement, si votre serveur est installé dernière un routeur avec du NAT (typiquement sur un réseau local derrière une box Internet) vous devez configurer la redirection de port sur votre routeur/box internet.

Encore une fois, on part du principe que le serveur de R.P et Constellation sont sur le même serveur, donc la même IP interne.

Dans un premier temps redirigez seulement le port 8088 en tcp sur l’IP interne de votre serveur Constellation. A noter que nous supprimerons cette redirection une fois le reverse proxy installé.

Donc pour résumer et avant de démarrer, vous devez avoir votre serveur Constellation démarré répondant sur l’URL : http://<mon_nom_dns>:8088

Dans mon cas : http://demo.internal.myconstellation.io:8088 :

Voilà vous êtes prêt, votre Constellation est démarrée et elle répond bien sur un nom DNS public depuis l’internet.

Exposer Constellation derrière Nginx

Avant de démarrer il est recommandé de mettre à jour le référentiel du gestionnaire de package par la commande suivante :

sudo apt-get update

Ensuite installez le serveur Web Nginx avec la commande :

sudo apt-get install nginx

Les fichiers de configuration sont situés dans le répertoire “/etc/nginx/sites-available/” et pour les activer on crée un lien symbolique vers ces fichiers dans le répertoire “/etc/nginx/sites-enabled”.

Pour commencer désactivez la configuration par défaut par la commande ci-dessous :

sudo rm /etc/nginx/sites-enabled/default

Comme vous l’aurez compris le contenu de cette configuration par défaut est toujours présente dans le répertoire “/etc/nginx/sites-available/” mais non activée car on a supprimé le lien symbolique vers ce fichier dans le répertoire “site-enabled”.

Maintenant nous allons créer une configuration pour notre reverse proxy avec la commande :

sudo nano /etc/nginx/sites-available/constellation

Dans ce fichier, copiez le contenu suivant :

server {
    listen 80; listen [::]:80;
    server_name demo.internal.myconstellation.io;

    location / {
        proxy_pass http://localhost:8088;

        set $content_length_safe $http_content_length;
        if ($content_length_safe = "") {
            set $content_length_safe 0;
        }
        proxy_set_header Content-Length $content_length_safe;

        proxy_set_header Host $host;
        proxy_set_header Connection "";
        proxy_http_version 1.1;

        proxy_buffering off;
        proxy_cache off;
        proxy_connect_timeout 30;
        proxy_send_timeout 30;
        proxy_read_timeout 150;
    }
}

Vous devez modifier le paramètre “server_name” avec le nom DNS de votre serveur Constellation, dans le cas présent “demo.internal.myconstellation.io”.

Il est important de bien reprendre les mêmes options, notamment le “proxy_buffering” pour permettre les “server-Sent events” vers le serveur Constellation.

Dans le cas présent Nginx va « proxifer » les requêtes vers http://localhost:8088, c’est à dire au service Constellation (port 8088) installé sur le même serveur (localhost).

Tapez ensuite sur la combinaison de touches “Ctrl+X” pour quitter en prenant suivant d’enregistrer le fichier. Puis, pour activer cette configuration, créez le lien symbolique suivant :

sudo ln -s /etc/nginx/sites-available/constellation  /etc/nginx/sites-enabled/constellation

Avant de redémarrer Nginx, éditez le fichier de configuration global pour augmenter la taille maximale des requêtes entrantes afin de pouvoir uploader des packages Constellation sur le serveur (par défaut cette taille est fixée à 1Mo, autrement dit vous obtiendrez une erreur 413 « Request Entity Too Large » si vous tentez d’uploader un package de plus de 1Mo).

sudo nano /etc/nginx/nginx.conf

Sous la section « http », ajoutez l’option « client_max_body_size » (ou si l’option existe déjà, modifiez sa valeur) que nous fixerons à 100 Méga :

client_max_body_size 100M;

Pour finir, rechargez Nginx afin prendre en compte notre nouvelle configuration :

sudo systemctl reload nginx

Votre Constellation est maintenant accessible derrière Nginx sur le port 80.

Rendez-vous donc sur l’adresse http://<votre_nom_dns> (sans spécifier le port, car 80 par défaut) pour vérifier que le reverse proxy est opérationnel. Dans le cas présent http://demo.internal.myconstellation.io

Ce n’est donc plus Constellation qui répond mais notre serveur Nginx qui lui même communique avec le serveur Constellation local.

Donc pour résumer, sur le port 80 c’est le serveur Nginx qui répond en transférant au serveur Constellation sur le port 8088.

Note : si vous êtes dernière un routeur avec du NAT, n’oubliez pas d’ajouter la redirection du port 80 vers votre serveur Constellation interne. Par la même occasion vous pouvez supprimer la redirection du port 8088, ainsi tout passera nécessairement par Nginx.

Activer le HTTPS avec des certificats SSL Let’s Encrypt

Maintenant que votre service Constellation est exposé dernière le serveur Nginx vous allez pouvoir configurer différentes choses sur Nginx comme par exemple des restrictions d’accès , l’authentification, des limites (throttling) et bien d’autre chose. Dans le cas présent on va s’intéresser au support du SSL.

Pour activer le HTTPS, il vous faut un certificat SSL. Pour simplifier la démarche, Let’s Encrypt est une autorité de certification lancée en 2015 qui permet d’automatiser la génération de certificat. De plus le service est gratuit ! Les certificats sont valides trois mois, il faudra donc régulièrement les renouveler mais vous allez voir que cette action est entièrement automatisable.

Ici nous allons utiliser Certbot, un agent installé sur le serveur qui permet de générer et renouveler automatiquement les certificats SSL Let’s Encrypt.

Commencez par ajouter le repository suivant :

sudo add-apt-repository ppa:certbot/certbot
sudo apt-get update

Ensuite installez Certbot pour Nginx :

sudo apt-get install python-certbot-nginx

Une fois installé, lancez la commande “certbot –nginx” en spécifiant le nom DNS vers votre serveur. Dans le cas présent :

sudo certbot --nginx -d demo.internal.myconstellation.io

L’assistant vous demandera tout d’abord votre adresse mail :

Après avoir accepté les conditions du service, l’assistant va automatiquement valider un challenge en interrogeant votre site Web (d’où la nécessité d’avoir exposé correctement votre serveur sur Internet avec le nom DNS spécifié), créer le certificat SSL et l’ajouter dans votre configuration Nginx.

Pour finir l’assistant vous proposera de modifier automatiquement la configuration de votre Nginx pour rediriger tous les appels HTTP (port 80) vers HTTPS (port 443).

Choisissiez l’option 2 pour activer cette redirection.

Et voilà, votre serveur Nginx est configuré avec le certificat SSL généré par Let’s Encrypt et toutes les requêtes seront redirigés en HTTPS et donc chiffrés !

Votre Constellation est maintenant protégée !

Rechargez la page dans votre navigateur (F5) sur l’URL http://<mon_nom_dns> vous constaterez la redirection automatique en https:// et le cadenas vert vous informant du chiffrement SSL :

(Note : pour les personnes derrières un NAT, n’oubliez pas non plus d’ajouter la redirection du port 443 vers votre serveur Nginx interne)

Pour vérifier le bon renouvellement du certificat vous pouvez utiliser la commande suivante :

sudo certbot renew --dry-run

Certbot a automatiquement installé un trigger dans systemd (ou crontab selon le système) pour réaliser le renouvellement et déploiement automatique de vos certificats avant leurs expirations.

Pour les plus curieux, vous pouvez jeter un œil dans le fichier “/etc/nginx/sites-available/constellation” pour voir les modifications apportées par Certbot.

Pour aller plus loin

Sécuriser le serveur avec un firewall UFW et fail2ban

Installer fail2ban

Fail2ban est un script tournant en tâche de fond qui va vérifier si les tentatives d’authentification SSH et Nginx; et en cas d’attaque, bannir l’IP grâce à iptables.

sudo apt-get install fail2ban

Pour plus d’info:  https://www.digitalocean.com/community/tutorials/how-to-protect-an-nginx-server-with-fail2ban-on-ubuntu-14-04

Installer UFW

UFW est un firewall applicatif. Pour l’installer :

sudo apt-get install ufw

Autorisez ensuite les services HTTP (nécessaire pour le challenge Let’s Encrypt), HTTPS (notre reverse proxy Nginx vers Constellation) et SSH :

sudo ufw allow http
sudo ufw allow https
sudo ufw allow ssh

Pour l’activer :

sudo ufw enable

Votre serveur Linux ne répondra plus que sur les ports 22 (ssh), 80 (http), 443 (https) en IPv4 et IPv6.

sebastien@ubuntu:~$ sudo ufw status
Status: active

To                         Action      From
--                         ------      ----
80                         ALLOW       Anywhere
443                        ALLOW       Anywhere
22                         ALLOW       Anywhere
80 (v6)                    ALLOW       Anywhere (v6)
443 (v6)                   ALLOW       Anywhere (v6)
22 (v6)                    ALLOW       Anywhere (v6)

Vous noterez que le port 8088 n’est maintenant plus accessible car bloqué par le firewall UFW. Il faudra forcement se connecter à Constellation via Nginx en HTTPS. N’oubliez pas alors de modifier l’URI de votre Constellation sur vos sentinelles existantes pour prendre en compte ce changement.

Ajouter d’autre application Web dernière votre reverse proxy SSL

Jusqu’au présent vous avez configuré un nom DNS type “demo.internal.myconstellation.io” qui pointe vers votre serveur Linux sur lequel le service Nginx répond en HTTP (80) et HTTPS (443) avec un certificat Let’s Encrypt pour “proxifier” les requêtes vers le service Constellation accessible localement sur le port 8088.

Vos utilisateurs se connectent donc forcement en HTTPS sur le reverse proxy pour accéder à Constellation !

La règle configurée dans Ngnix “proxifie” toutes les requêtes à partir de la racine « / » vers Constellation :

location / {
        proxy_pass http://localhost:8088;
....
}

Mais il est également possible d’adapter cette règle pour que votre reverse proxy ne soit plus exclusivement un passe-plat pour Constellation mais aussi pour vos autres services internes (une box domotique, un serveur Web, un objet connecté, une camera IP, etc…).

Vous aurez ainsi la possibilité d’exposer différents services Web internes dernière votre reverse proxy profitant d’un même port TCP (le 443) et donc d’un même canal de communication sécurisé (par le cryptage SSL).

Parmi les différentes options pour ce type de configuration :

1. Reverse proxy en fonction du “server_name”
2. Reverse proxy en fonction de la “location”

Reverse Proxy en fonction du server_name

Le principe est de rejouer ce tutoriel depuis le début pour chacune de vos applications à exposer.

Vous devrez ainsi créer une adresse DNS vers votre IP public pour chaque site, créer une configuration Nginx en changeant le « server_name » et « proxy_pass » vers la ressource interne à exposer et créer un certificat SSL avec Certbot pour tous vos sites créés.

Vous aurez ainsi une multitude de nom DNS qui pointerons tous vers votre serveur Nginx qui lui redirigera vers les ressources internes en fonction du « server_name ». Par exemple “constellation.mondomaine.fr”, “macamera.mondomaine.fr”, “jeedom.mondomaine.fr”, etc.. etc..

La configuration est simple car il s’agit de répéter ce tutoriel pour chaque service, par contre l’administration est un peu lourde et vous aurez autant de sous domaine et donc de certificat que de service à exposer.

Reverse Proxy en fonction de la “location”

Dans ce mode, nous gardons un seul site Nginx (celui configuré dans le fichier /etc/nginx/sites-available/constellation) et donc un seul nom de domaine (ici demo.internal.myconstellation.io) avec son certificat associé.

Cependant au lieu de “rediriger” les requêtes depuis la racine « / » vers Constellation nous allons créer plusieurs “location”.

Prenons un exemple pour bien comprendre. Ici le serveur Ngnix est installé sur la même que le serveur Constellation, donc localhost. Imaginons que dans ce même réseau LAN, j’ai par exemple un serveur ZoneMinder qui répond sur 192.168.0.10 et une box Jeedom sur 192.168.0.11.

Je pourrais éditer la configuration Nginx de cette façon :

location /constellation/ {
        proxy_pass http://localhost:8088/constellation/;

        proxy_set_header Host $host;
        proxy_set_header Connection "";
        proxy_http_version 1.1;

        proxy_buffering off;
        proxy_cache off;
        proxy_connect_timeout 30;
        proxy_send_timeout 30;
    }
    
    
location /zm/ {
        proxy_pass http://192.168.0.10/zm/;

        proxy_set_header Host $host;
        proxy_set_header Connection "";
        proxy_http_version 1.1;
    }
    
location /jeedom/ {
        proxy_pass http://192.168.0.11;

        proxy_set_header Host $host;
        proxy_set_header Connection "";
        proxy_http_version 1.1;
    }

Ainsi, en fonction du “path” demandé, un service différent me répondra :

• https://<mon_nom_DNS>/constellation : réponse du serveur Constellation
• https://<mon_nom_DNS>/zm  : réponse du serveur ZoneMinder
• https://<mon_nom_DNS>/jeedom : réponse du serveur Jeedom

Attention : si le serveur Constellation répond sur un “sous path”, comme ici “/constellation” il faut également modifier la configuration du serveur Constellation pour l’informer.

Pour cela modifiez le ficher “/opt/constellation-server/Constellation.Server.exe.config” :

sudo nano /opt/constellation-server/Constellation.Server.exe.config

Et modifier le listenUri pour reprendre la même structure d’URI, ici en ajoutant “/constellation” :

<listenUris>
    <uri listenUri="http://+:8088/constellation" />
</listenUris>

Pour finir, il faudra relancer le service Constellation pour prendre en compte ce changement :

sudo supervisorctl restart constellation-server

Voilà votre Constellation répond maintenant sur le /constellation, dans notre cas https://demo.internal.myconstellation.io/constellation :

Si maintenant on change le path pour “/zm” soit ici https://demo.internal.myconstellation.io/zm, c’est notre serveur ZoneMinder qui répondra :

On a donc un seul serveur en frontal, Ngnix qui écoute en HTTPS avec le certificat Let’s Encrypt pour sécuriser TOUS les échanges et qui, selon le “path” demandé, transféra les requêtes vers les différents services internes de votre réseau.

A noter que vous pouvez également utiliser des expressions régulières (regex) pour définir vos “locations”. Pour plus d’information : https://www.scalescale.com/tips/nginx/nginx-location-directive/

The post Exposer Constellation en HTTPS derrière un reverse proxy avec Nginx et Let’s Encrypt appeared first on Constellation.

Il héberge des hubs et des interfaces HTTP/REST. De plus il peut également héberger des fichiers statiques en configurant le “fileServer” ce qui permet par exemple l’auto-hébergement de la console Constellation (plus d’info ici).

Les hubs Constellation sont basés sur la technologie SignalR permettant d’exposer des canaux de communication bi-directionnels et temps réel en HTTP long-polling, server-event ou WebSocket en fonction des capacités du client.

Les interfaces HTTP/REST sont en fait des contrôleurs WebAPI exposant des méthodes en HTTP/REST. Les interfaces HTTP/REST permettent d’exposer des fonctionnalités de Constellation de manière très simple pour les devices ou frameworks ne pouvant supporter SignalR.

Il existe 4 hubs :

• Constellation
• Consumer
• Controller
• Sentinel

Ainsi que 3 interfaces HTTP/REST :

• Constellation
• Consumer
• Management

Le hub et l’interface HTTP “Constellation” sont utilisés par les packages Constellation (réels ou virtuels). Ils exposent des méthodes pour écrire des logs, pour récupérer les settings, pour publier ou interroger des StateObjects, envoyer ou recevoir des messages, etc…

Le hub et l’interface HTTP “Consumer” sont utilisés par les “consommateurs”. Par exemple une page Web est un consommateur, c’est à dire qu’elle se connecte à Constellation pour interroger des StateObjects ou envoyer/recevoir des messages mais elle n’est pas un package (son cycle de vie est lié au navigateur du client). Un “consommateur” ne peut pas produire des logs, avoir de settings ou encore publier des StateObjects.

Le hub “Controller” expose des méthodes pour contrôler la Constellation comme arrêter/démarrer des packages, s’abonner et récupérer en temps réel les logs des packages de la Constellation, propager les changements de configuration dans la Constellation, suivre les états et consommation des ressources des packages, etc… Ce hub est notamment utilisé par la Console Constellation pour vous fournir une interface de pilotage de votre Constellation. Pour pouvez également vous connecter et exploiter les fonctionnalités de contrôle de vos pages Web ou packages .NET.

Le hub “Sentinel” est un hub privé réservé aux sentinelles de la Constellation. C’est sur ce hub que les sentinelles s’enregistrent, remontent les états des packages qu’elles supervisent, etc…

Enfin l’interface HTTP “Management” aussi nommée “Management API” est une API HTTP/REST de management du serveur permettant la gestion des sentinelles, des packages, des settings, des credentials, etc… Cette API est notamment utilisée par la Console Constellation pour vous fournir une interface d’administration de votre Constellation.

The post Les différents hubs et interfaces REST du serveur Constellation appeared first on Constellation.

Avec cette interface vous pourrez via des requêtes HTTP :

• Publier, consommer ou purger des StateObjects
• Envoyer et recevoir des messages
• Récupérer les settings du package « virtuel »
• Produire des logs
• Déclarer le “Package Descriptor” (MessageCallbacks exposés ou les types utilisés par les MC ou SO)

De ce fait un script Bash ou Powershell, une page PHP, un Arduino, ESP ou NetDuino, bref n’importe quel système, objet ou langage pouvant effectuer des appels HTTP peut être considéré comme un package (dit virtuel) de votre Constellation et produire ou consommer des StateObjects, envoyer ou recevoir des messages, écrire des logs, etc…

Généralités

Construction de l’URL

L’URL est :  <Root URI>/rest/constellation/<action>?<paramètres>

Partons du principe que votre Constellation est exposée en HTTP sur le port 8088 (sans path). On retrouvera dans le fichier de configuration la section suivante :

<listenUris>
  <uri listenUri="http://+:8088/" />
</listenUris>

La “Root URI “ est donc “http://<ip ou dns>:8088/”.

Par exemple si nous sommes en local, nous pourrions écrire :

http://localhost:8088/rest/constellation/xxxxx

Authentification

Comme pour toutes les requêtes vers Constellation vous devez impérativement spécifier dans les headers HTTP ou dans les paramètres de l’URL (querystring), les paramètres “SentinelName”, “PackageName” et “AccessKey” pour l’authentification.

Ici votre “package virtuel” doit être déclaré dans la configuration de votre Constellation comme un véritable package, c’est à dire avec une sentinelle (dite virtuelle) et un package qui peut contenir des settings, etc…

Par exemple :

<sentinels>
  <sentinel name="MyVirtualSentinel" credential="Standard">
    <packages>        
      <package name="MyVirtualPackage" enable="true">
        <settings>
          <setting key="IntSetting" value="42" />
          <setting key="StringSetting" value="sample config value" />
        </settings>
      </package>
    </packages>
  </sentinel>
</sentinels>

On a ici déclaré une sentinelle virtuelle “MyVirtualSentinel” qui contient le package virtuelle “MonPackageVirtuel”. Ce package utilise implicitement l’AccessKey du credential “Standard” déclaré au niveau de la sentinelle.

De ce fait, pour chaque appel on passera les paramètres suivants (dans l’URL ou dans les headers) :

• SentinelName = MyVirtualSentinel
• PackageName = MyVirtualPackage
• AccessKey = MyAccessKey (en partant du principe que l’AccessKey déclaré pour le credential “Standard” est “MyAccessKey”)

Pour la suite de cet article nous passerons tous les paramètres dans l’URL, ainsi chaque appel sera sous la forme :

http://localhost:8088/rest/constellation/<action>?SentinelName=MyVirtualSentinel&PackageName=MyVirtualPackage&AccessKey=MyAccessKey&<paramètres>

Check Access

Toutes les API REST de Constellation exposent une méthode en GET “CheckAccess” qui retourne un code HTTP 200 (OK). Cela permet de tester la connexion et l’authentification au serveur Constellation.

• Action : “CheckAccess” (GET)
• Paramètres : aucun

Exemple :

http://localhost:8088/rest/constellation/CheckAccess?SentinelName=MyVirtualSentinel&PackageName=MyVirtualPackage&AccessKey=MyAccessKey

Publier des StateObjects

• Action : “PushStateObject” (GET ou POST)
• En GET, voici les paramètres de l’URL :
  • name : le nom du StateObject
  • value : la valeur du StateObject
  • type (optionnel) : le type du StateObject
  • lifetime (optionnel – par défaut 0) : la durée de vie (en seconde) du StateObject avant d’être marqué “expiré”. (0 = durée de vie infinie)

Pour publier un StateObject vous devez obligatoirement spécifier son nom (name) et sa valeur (value). La valeur peut être un type simple (un Int, String, bool, etc..) ou un objet complexe formaté en JSON. Optionnellement vous pouvez spécifier le type et la durée de vie de votre SO (en seconde).

Par exemple publions un StateObject nommé “Temperature” dont la valeur est le nombre “21” :

http://localhost:8088/rest/constellation/PushStateObject?SentinelName=MyVirtualSentinel&PackageName=MyVirtualPackage&AccessKey=MyAccessKey&name=Temperature&value=21

Autre exemple avec un objet complexe contenant deux propriété (Temperature et Humidity) dont la durée de vie est de 60 secondes et le type nommé “TemperatureHumidity” :

http://localhost:8088/rest/constellation/PushStateObject?SentinelName=MyVirtualSentinel&PackageName=MyVirtualPackage&AccessKey=MyAccessKey&name=Temperature&value={ Temperature: 21, Humidity: 72 }&type=TemperatureHumidity&lifetime=60

Si la valeur du StateObject est trop grande pour être passée dans l’URL ou si vous souhaitez ajouter des métadonnées (metadatas) à votre StateObject vous pouvez “poster” le StateObject dans le corps de la requête HTTP en utilisant le verbe “POST” (sans oublier de définir le Content-Type à “application/json”).

Pour publier par un POST le même StateObject en lui ajoutant deux métadonnées :

POST http://localhost:8088/rest/constellation/PushStateObject?SentinelName=MyVirtualSentinel&PackageName=MyVirtualPackage&AccessKey=MyAccessKey
Host: localhost:8088
Content-Length: 189
Content-Type: application/json

{
  "Name" : "Temperature",
  "Value" : { Temperature: 21, Humidity: 72 },
  "Type" : "TemperatureHumidity",
  "Lifetime" : 60,
  "Metadatas": { "ChipId":"ABC123", "Room":"Garden" }
}

Purger ses StateObjects

Un package peut supprimer ses StateObjects qu’il produit avec la méthode “PurgeStateObjects”.

• Action : “PurgeStateObjects” (GET)
• Paramètres:
  • name (optionnel – par défaut “*”) : le nom du StateObject
  • type (optionnel – par défaut “*”) : le type du StateObject

Vous pouvez spécifier le nom du StateObject à supprimer et/ou son type. Par défaut ces deux paramètres sont définis à “*”. C’est à dire que si vous ne précisez rien, tous les StateObjects du package seront purgés.

Par exemple pour purger tous les StateObjects de notre package virtuel (instance MyVirtualSentinel/MyVirtualPackage):

http://localhost:8088/rest/constellation/PurgeStateObjects?SentinelName=MyVirtualSentinel&PackageName=MyVirtualPackage&AccessKey=MyAccessKey

Pour purger tous les StateObjects de type “Temperature” de cette même instance :

http://localhost:8088/rest/constellation/PurgeStateObjects?SentinelName=MyVirtualSentinel&PackageName=MyVirtualPackage&AccessKey=MyAccessKey&type=Temperature

Ou pour supprimer le StateObject nommé “Demo” :

http://localhost:8088/rest/constellation/PurgeStateObjects?SentinelName=MyVirtualSentinel&PackageName=MyVirtualPackage&AccessKey=MyAccessKey&name=Demo

Ecrire des logs

Les packages peuvent écrire des logs qui seront remontés dans le hub Constellation.

• Action : “WriteLog” (GET)
• Paramètres:
  • message : texte du log
  • level (optionnel – par défaut “Info”) : le niveau du log (Info, Warn ou Error)

Exemple d’un message “Info” :

http://localhost:8088/rest/constellation/WriteLog?SentinelName=MyVirtualSentinel&PackageName=MyVirtualPackage&AccessKey=MyAccessKey&message=Hello World

Exemple pour produire un message d’erreur (Error) :

http://localhost:8088/rest/constellation/WriteLog?SentinelName=MyVirtualSentinel&PackageName=MyVirtualPackage&AccessKey=MyAccessKey&message=Il y  a une erreur ici&level=Error

Récupérer ses settings

Les settings sont récupérés en invoquant la méthode “GetSettings”.

• Action : “GetSettings” (GET)
• Paramètres:  aucun

Par exemple pour récupérer les settings (dictionnaire de clé / valeur) définis pour notre package virtuel :

http://localhost:8088/rest/constellation/GetSettings?SentinelName=MyVirtualSentinel&PackageName=MyVirtualPackage&AccessKey=MyAccessKey

Envoyer des messages

• Action : “SendMessage” (GET ou POST)
• En GET, voici les paramètres de l’URL :
  • scope : le type de scope (All, Other, Group, Sentinel ou Package)
  • args : les arguments du scope (par exemple le nom du groupe, de la sentinelle, du package ou de l’instance du package – plusieurs valeurs possibles séparées par des virgules)
  • key : la clé du message (= la méthode à invoquer)
  • data : le contenu du message (= les arguments de la méthode)
  • sagaId (optionnel) : l’identification de la saga si le message est envoyé dans une saga

Vous pouvez également invoquer cette action en POST. Le corps de votre requête contiendra l’objet JSON suivant :

{
  "Scope" : { "Type" : "<type>", Args: [ "<arg1>", "<args2>", .... ], "SagaId":"Identifiant de la Saga" },
  "Key" : "<Key>",
  "Data" : "<Data>"
}

La propriété “SagaId” dans le JSON ci-dessus est optionnelle.

Par exemple pour envoyer un message au package Nest en invoquant la méthode (key) “SetTargetTemperature” avec en paramètre le nombre “21” :

http://localhost:8088/rest/constellation/SendMessage?SentinelName=Consumer&PackageName=Demo&AccessKey=MaCleDeTest123&scope=Package&args=Nest&key=SetTargetTemperature&data=21

Ce même MessageCallback “SetTargetTemperature” du package Nest peut être invoqué dans une saga afin de recevoir un accusé de réception :

http://localhost:8088/rest/constellation/SendMessage?SentinelName=Consumer&PackageName=Demo&AccessKey=MaCleDeTest123&scope=Package&args=Nest&key=SetTargetTemperature&data=21&sagaId=123456789

Il faudra ensuite “récupérer” les messages reçus (voir dessous) pour lire la réponse à votre saga que nous avons ici identifié par la clé “123456789”.

Recevoir des messages

Créer un abonnement de réception

Tout d’abord pour recevoir des messages il faut s’abonner aux messages.

• Action : “SubscribeToMessage” (GET)
• Paramètres :
  • subscriptionId (optionnel) : identifiant de l’abonnement si déjà connu

http://localhost:8088/rest/constellation/SubscribeToMessage?SentinelName=Consumer&PackageName=Demo&AccessKey=MaCleDeTest123

Vous obtiendrez en réponse l’ID de votre abonnement, le “Subscription Id”.

Relever les messages

• Action : “GetMessages” (GET)
• Paramètres :
  • subscriptionId : identifiant de l’abonnement
  • timeout (optionnel – par défaut 60000) : temps maximal en milliseconde de la mise en attente de la requête (entre 1000ms et 120000ms)
  • limit (optionnel – par défaut 0) : nombre maximum de message à retourner pour l’appel

Il s’agit d’une requête en “long-polling” c’est à dire que la requête sera “bloquée” sur le serveur tant qu’il n’y a pas de message reçu évitant ainsi de “flooder” en continue le serveur pour savoir si de nouveaux messages sont disponibles ou non. Par défaut la requête est bloquée 60 secondes maximum mais vous pouvez personnaliser cette valeur avec le paramètre “timeout”. Si il y a des messages disponibles, le serveur vous renvoi un tableau JSON avec les messages reçus. Si il n’y a pas de réponse dans le délai spécifié par le paramètre “timeout” (60 secondes par défaut), le tableau retourné sera vide.

A chaque réponse vous devez donc relancer une requête “GetMessages” pour “écouter” les prochains messages qui vont sont destinés.

Il est également possible de limiter le nombre de message dans la réponse avec le paramètre “limit” ce qui peut être utile sur de petits “devices” ne disposant pas de beaucoup de mémoire RAM pour désérialiser de gros tableaux JSON.

Exemple simple :

http://localhost:8088/rest/constellation/GetMessages?SentinelName=Consumer&PackageName=Demo&AccessKey=MaCleDeTest123&subscriptionId=xxxxx

Autre exemple en limitant le nombre de message à 2 par appel et en bloquant la requête pendant 10 secondes au maximum :

http://localhost:8088/rest/constellation/GetMessages?SentinelName=Consumer&PackageName=Demo&AccessKey=MaCleDeTest123&subscriptionId=xxxxx&timeout=10000&limit=2

S’abonner à un groupe

Vous pouvez vous abonner à des groupes pour recevoir les messages envoyés dans ces groupes par l’action “SubscribeToMessageGroup” en précisant le nom du groupe et votre ID d’abonnement.

• Action : “SubscribeToMessageGroup” (GET)
• Paramètres :
  • group : le nom du groupe à joindre
  • subscriptionId (optionnel) : identifiant de l’abonnement si déjà connu

http://localhost:8088/rest/constellation/SubscribeToMessageGroup?SentinelName=Consumer&PackageName=Demo&AccessKey=MaCleDeTest123&subscriptionId=xxxxx&group=A

Comme l’action “SubscribeToMessage”, cette action vous retourne l’ID d’abonnement à utiliser pour l’action “GetMessages”.

Consommation de StateObjects

Request

Cette méthode permet de récupérer la valeur actuelle d’un ou de plusieurs StateObjects.

• Action : “RequestStateObjects” (GET)
• Paramètres :
  • sentinel (optionnel – par défaut “*”): nom de la sentinelle
  • package (optionnel – par défaut “*”) : nom du package
  • name (optionnel – par défaut “*”) : nom du StateObject
  • type (optionnel – par défaut “*”) : type du StateObject

Par exemple pour récupérer tous les StateObject de votre Constellation :

http://localhost:8088/rest/constellation/RequestStateObjects?SentinelName=Consumer&PackageName=Demo&AccessKey=MaCleDeTest123

Ou seulement ceux produits par le package “HWMonitor” (quelque soit la sentinelle) :

http://localhost:8088/rest/constellation/RequestStateObjects?SentinelName=Consumer&PackageName=Demo&AccessKey=MaCleDeTest123&package=HWMonitor

Ou encore tous les StateObjects nommés “/intelcpu/load/0” et produits le package “HWMonitor” (quelque soit la sentinelle) :

http://localhost:8088/rest/constellation/RequestStateObjects?SentinelName=Consumer&PackageName=Demo&AccessKey=MaCleDeTest123&package=HWMonitor&name=/intelcpu/load/0

Subscribe

Vous pouvez également vous abonner aux mises à jour des StateObjects.

Le principe est le même qu’avec les messages : il faut récupérer un ID d’abonnement et invoquer une méthode en long-polling pour recevoir les mises à jour.

S’abonner à des StateObjects

• Action : “SubscribeToStateObjects” (GET)
• Paramètres :
  • subscriptionId (optionnel) : identifiant de l’abonnement si déjà connu
  • sentinel (optionnel – par défaut “*”): nom de la sentinelle
  • package (optionnel – par défaut “*”) : nom du package
  • name (optionnel – par défaut “*”) : nom du StateObject
  • type (optionnel – par défaut “*”) : type du StateObject

En retour vous obtiendrez l’ID d’abonnement (un GUID).

Par exemple pour s’abonner au SO “/intelcpu/load/0”, produit le package “HWMonitor” sur la sentinelle “MON-PC” :

http://localhost:8088/rest/constellation/SubscribeToStateObjects?SentinelName=Consumer&PackageName=Demo&AccessKey=MaCleDeTest123&sentinel=MON-PC&package=HWMonitor&name=/intelcpu/load/0

ATTENTION : si vous souhaitez “ajouter” des SO à votre abonnement vous devez impérativement préciser votre ID d’abonnement récupéré lors du 1er appel autrement vous allez créer un nouvel abonnement.

Par exemple pour “ajouter” le SO correspondant à la consommation RAM :

http://localhost:8088/rest/constellation/SubscribeToStateObjects?SentinelName=Consumer&PackageName=Demo&AccessKey=MaCleDeTest123&sentinel=MON-PC&package=HWMonitor&name=/ram/load&subscriptionId=<subId>

Relever les StateObjects mis à jour

Pour récupérer les SO de votre abonnement qui ont changés entre deux appels vous devez invoquer l’action “GetStateObjects” en spécifiant l’ID de votre abonnement :

• Action : “GetStateObjects” (GET)
• Paramètres :
  • subscriptionId : identifiant de l’abonnement
  • timeout (optionnel – par défaut 60000) : temps maximal en milliseconde de la mise en attente de la requête (entre 1000ms et 120000ms)
  • limit (optionnel – par défaut 0) : nombre maximum de message à retourner pour l’appel

Comme pour les messages, vous pouvez limiter le nombre de SO (limit) et le timeout de la requête (timeout).

http://localhost:8088/rest/constellation/GetStateObjects?SentinelName=Consumer&PackageName=Demo&AccessKey=MaCleDeTest123&subscriptionId=<subId>

Notez que si un StateObject pour lequel vous êtes abonné change plusieurs fois entre deux appels “GetStateObjects”, vous obtiendrez la dernière valeur et non l’historique de tous les changements.

Déclarer le “Package Descriptor”

Action : “DeclarePackageDescriptor” (POST)

Le “Package Descriptor” permet décrire les MessagesCallbacks d’un package ainsi que les types utilisés par ses MC ou StateObjects.

Ainsi en publiant le PackageDescriptor, la Constellation aura connaissance des MessageCallbacks qu’expose un package ainsi que le type des StateObject qu’il publie. C’est grâce au Package Descriiptor que fonctionne le “MessageCallback Explorer” de la Console Constellation.

Le Package Descriptor est un objet JSON contenant :

• Le nom du package
• La liste des MessageCallbacks du package
• La liste des types utilisés par les MessageCallbacks du package
• La liste des types utilisés par les StateObjects publiés par le package

La structure de base est donc :

{
  "PackageName": "MyVirtualPackage",
  "MessageCallbacks": [],
  "MessageCallbackTypes": [],
  "StateObjectTypes": [],
}

Chaque “MessageCallback” est un objet contenant :

• MessageKey : la clé du message (le nom/clé du MessageCallback)
• Description (optionnel) : description du MessageCallback
• ResponseType (optionnel) : le type du message de retour dans le cas où le MC répond au Saga
• Parameters (optionnel) : la liste des paramètres du MC

Un paramètre est décrit par un objet contenant :

• Name : le nom du paramètre
• TypeName : le type du paramètre
• Description (optionnel) : la description du paramètre
• Type : le type de paramètre (doit être obligatoirement défini à 2 pour un paramètre d’un MC)
• IsOptional (optionnel) : booléen (true ou false) qui indique si le paramètre est optionnel ou non
• DefaultValue (optionnel) : la valeur par défaut du paramètre si optionnel

Le type d’un paramètre peut être un type simple décrit par les types .NET (System.Int16, System.Int32, System.Int64, System.Double, System.Decimal, System.Float, System.Boolean, System.String) ou un type personnalisé.

Les types personnalisés utilisés dans les paramètres des MC seront décrits dans la propriété “MessageCallbackTypes” du Package Descriptor et les types personnalisés utilisés pour les StateObjects seront décrits dans la propriété “StateObjectTypes” du Package Descriptor.

Dans les deux cas il s’agit de la même structure de donnée.

La description d’un type est un objet contenant :

• TypeName : le nom du type (l’identifiant)
• TypeFullname : le nom complet du type (utilisé pour identifier le nom complet d’un type .NET par exemple)
• Description (optionnel) : la description du type
• IsGeneric (optionnel) : booléen (true ou false) qui indique si le type est un type générique
• IsArray (optionnel) : booléen (true ou false) qui indique si le type est un tableau
• GenericParameters (optionnel) : la liste des types génériques si il s’agit d’un type générique ou d’un tableau
• IsEnum (optionnel) : booléen (true ou false) qui indique si le type est une énumération
• EnumValues (optionnel) : la liste des valeurs de l’énumérations si le type est une énumération
• Properties (optionnel) : la liste des propriétés du type

Les propriétés d’un type tout comme les valeurs d’une énumération sont décrits de la même manière qu’un paramètre d’un MessageCallback déjà détaillé ci-dessus.

Seule la propriété “Type” change :

• Type = 0 : pour décrire une propriété
• Type = 1 : pour décrire une valeur d’une énumération
• Type = 2 : pour décrire une paramètre d’un MessageCallback comme expliqué précédemment

Exemple 1 – Package “NetworkTools”

Voici le Package Descriptor du package “NetworkTools” :

{
   "PackageName":"NetworkTools",
   "MessageCallbacks":[  
      {  
         "MessageKey":"Ping",
         "Description":"Pings the specified host and return the response time.",
         "ResponseType":"System.Int64",
         "Parameters":[  
            {  
               "Name":"host",
               "TypeName":"System.String",
               "Description":"The host.",
               "Type":2,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"timeout",
               "TypeName":"System.Int32",
               "Description":"The timeout (5000ms by defaut).",
               "Type":2,
               "IsOptional":false,
               "DefaultValue":null
            }
         ]
      },
      {  
         "MessageKey":"CheckPort",
         "Description":"Check a port's status by entering an address and port number above and return the response time.",
         "ResponseType":"System.Int64",
         "Parameters":[  
            {  
               "Name":"host",
               "TypeName":"System.String",
               "Description":"The host.",
               "Type":2,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"port",
               "TypeName":"System.Int32",
               "Description":"The port.",
               "Type":2,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"timeout",
               "TypeName":"System.Int32",
               "Description":"The timeout (5000ms by defaut).",
               "Type":2,
               "IsOptional":false,
               "DefaultValue":null
            }
         ]
      },
      {  
         "MessageKey":"CheckHttp",
         "Description":"Checks the HTTP address and return the response time.",
         "ResponseType":"System.Int64",
         "Parameters":[  
            {  
               "Name":"address",
               "TypeName":"System.String",
               "Description":"The address.",
               "Type":2,
               "IsOptional":false,
               "DefaultValue":null
            }
         ]
      },
      {  
         "MessageKey":"ScanPort",
         "Description":"Scans TCP port range to discover which TCP ports are open on your target host.",
         "ResponseType":"System.Collections.Generic.Dictionary`2[[System.Int32, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089],[System.Boolean, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089]]",
         "Parameters":[  
            {  
               "Name":"host",
               "TypeName":"System.String",
               "Description":"The host.",
               "Type":2,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"startPort",
               "TypeName":"System.Int32",
               "Description":"The start port.",
               "Type":2,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"endPort",
               "TypeName":"System.Int32",
               "Description":"The end port.",
               "Type":2,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"timeout",
               "TypeName":"System.Int32",
               "Description":"The timeout (5000ms by defaut).",
               "Type":2,
               "IsOptional":false,
               "DefaultValue":null
            }
         ]
      },
      {  
         "MessageKey":"WakeUp",
         "Description":"Wakes up the specified host.",
         "ResponseType":"System.Boolean",
         "Parameters":[  
            {  
               "Name":"host",
               "TypeName":"System.String",
               "Description":"The host.",
               "Type":2,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"macAddress",
               "TypeName":"System.String",
               "Description":"The mac address.",
               "Type":2,
               "IsOptional":false,
               "DefaultValue":null
            }
         ]
      },
      {  
         "MessageKey":"DnsLookup",
         "Description":"Resolves a host name or IP address.",
         "ResponseType":"System.String[]",
         "Parameters":[  
            {  
               "Name":"host",
               "TypeName":"System.String",
               "Description":"The host.",
               "Type":2,
               "IsOptional":false,
               "DefaultValue":null
            }
         ]
      }
   ],
   "MessageCallbackTypes":[  
      {  
         "Description":null,
         "IsGeneric":true,
         "IsArray":false,
         "GenericParameters":[  
            "System.Int32",
            "System.Boolean"
         ],
         "IsEnum":false,
         "EnumValues":null,
         "TypeName":"Dictionary`2",
         "TypeFullname":"System.Collections.Generic.Dictionary`2[[System.Int32, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089],[System.Boolean, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089]]",
         "Properties":null
      },
      {  
         "Description":null,
         "IsGeneric":false,
         "IsArray":true,
         "GenericParameters":[  
            "System.String"
         ],
         "IsEnum":false,
         "EnumValues":null,
         "TypeName":"String[]",
         "TypeFullname":"System.String[]",
         "Properties":null
      }
   ],
   "StateObjectTypes":[  
      {  
         "Description":"Monitoring type",
         "IsGeneric":false,
         "IsArray":false,
         "GenericParameters":null,
         "IsEnum":false,
         "EnumValues":null,
         "TypeName":"MonitoringResult",
         "TypeFullname":"NetworkTools.MonitoringResult",
         "Properties":[  
            {  
               "Name":"ResponseTime",
               "TypeName":"System.Int64",
               "Description":"Gets or sets the response time in millisecond.",
               "Type":1,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"State",
               "TypeName":"System.Boolean",
               "Description":"Gets or sets the state.",
               "Type":1,
               "IsOptional":false,
               "DefaultValue":null
            }
         ]
      }
   ]
}

Exemple 2 – Package “Paradox”

Autre exemple plus complet, le Package Descriptor du package “Paradox” :

{  
   "PackageName":"Paradox",
   "MessageCallbacks":[  
      {  
         "MessageKey":"AreaArm",
         "Description":"Arm the area.",
         "ResponseType":"System.Boolean",
         "Parameters":[  
            {  
               "Name":"request",
               "TypeName":"ParadoxOnConstellation.ArmingRequestData",
               "Description":"The request.",
               "Type":2,
               "IsOptional":false,
               "DefaultValue":null
            }
         ]
      },
      {  
         "MessageKey":"AreaDisarm",
         "Description":"Disarm the area.",
         "ResponseType":"System.Boolean",
         "Parameters":[  
            {  
               "Name":"request",
               "TypeName":"ParadoxOnConstellation.ArmingRequestData",
               "Description":"The request.",
               "Type":2,
               "IsOptional":false,
               "DefaultValue":null
            }
         ]
      },
      {  
         "MessageKey":"RefreshArea",
         "Description":"Refreshes the area.",
         "ResponseType":null,
         "Parameters":[  
            {  
               "Name":"area",
               "TypeName":"Paradox.Core.Area",
               "Description":"The area.",
               "Type":2,
               "IsOptional":false,
               "DefaultValue":null
            }
         ]
      },
      {  
         "MessageKey":"RefreshAll",
         "Description":"Refreshes all.",
         "ResponseType":null,
         "Parameters":[  

         ]
      }
   ],
   "MessageCallbackTypes":[  
      {  
         "Description":"Arming or disarming request",
         "IsGeneric":false,
         "IsArray":false,
         "GenericParameters":null,
         "IsEnum":false,
         "EnumValues":null,
         "TypeName":"ArmingRequestData",
         "TypeFullname":"ParadoxOnConstellation.ArmingRequestData",
         "Properties":[  
            {  
               "Name":"Area",
               "TypeName":"Paradox.Core.Area",
               "Description":"The number of area.",
               "Type":1,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"Mode",
               "TypeName":"Paradox.Core.ArmingMode",
               "Description":"The mode number.",
               "Type":1,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"PinCode",
               "TypeName":"System.String",
               "Description":"The pin code.",
               "Type":1,
               "IsOptional":false,
               "DefaultValue":null
            }
         ]
      },
      {  
         "Description":null,
         "IsGeneric":false,
         "IsArray":false,
         "GenericParameters":null,
         "IsEnum":true,
         "EnumValues":[  
            {  
               "Name":"All",
               "TypeName":"Paradox.Core.Area",
               "Description":null,
               "Type":0,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"Area1",
               "TypeName":"Paradox.Core.Area",
               "Description":null,
               "Type":0,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"Area2",
               "TypeName":"Paradox.Core.Area",
               "Description":null,
               "Type":0,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"Area3",
               "TypeName":"Paradox.Core.Area",
               "Description":null,
               "Type":0,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"Area4",
               "TypeName":"Paradox.Core.Area",
               "Description":null,
               "Type":0,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"Area5",
               "TypeName":"Paradox.Core.Area",
               "Description":null,
               "Type":0,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"Area6",
               "TypeName":"Paradox.Core.Area",
               "Description":null,
               "Type":0,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"Area7",
               "TypeName":"Paradox.Core.Area",
               "Description":null,
               "Type":0,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"Area8",
               "TypeName":"Paradox.Core.Area",
               "Description":null,
               "Type":0,
               "IsOptional":false,
               "DefaultValue":null
            }
         ],
         "TypeName":"Area",
         "TypeFullname":"Paradox.Core.Area",
         "Properties":null
      },
      {  
         "Description":null,
         "IsGeneric":false,
         "IsArray":false,
         "GenericParameters":null,
         "IsEnum":true,
         "EnumValues":[  
            {  
               "Name":"RegularArm",
               "TypeName":"Paradox.Core.ArmingMode",
               "Description":null,
               "Type":0,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"ForceArm",
               "TypeName":"Paradox.Core.ArmingMode",
               "Description":null,
               "Type":0,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"StayArm",
               "TypeName":"Paradox.Core.ArmingMode",
               "Description":null,
               "Type":0,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"InstantArm",
               "TypeName":"Paradox.Core.ArmingMode",
               "Description":null,
               "Type":0,
               "IsOptional":false,
               "DefaultValue":null
            }
         ],
         "TypeName":"ArmingMode",
         "TypeFullname":"Paradox.Core.ArmingMode",
         "Properties":null
      }
   ],
   "StateObjectTypes":[  
      {  
         "Description":null,
         "IsGeneric":false,
         "IsArray":false,
         "GenericParameters":null,
         "IsEnum":false,
         "EnumValues":null,
         "TypeName":"UserInfo",
         "TypeFullname":"ParadoxOnConstellation.UserInfo",
         "Properties":[  
            {  
               "Name":"Id",
               "TypeName":"System.Int32",
               "Description":"The identifier.",
               "Type":1,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"Type",
               "TypeName":"System.String",
               "Description":"The object type.",
               "Type":1,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"Name",
               "TypeName":"System.String",
               "Description":"The name.",
               "Type":1,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"LastActivity",
               "TypeName":"System.DateTime",
               "Description":"The last activity.",
               "Type":1,
               "IsOptional":false,
               "DefaultValue":null
            }
         ]
      },
      {  
         "Description":null,
         "IsGeneric":false,
         "IsArray":false,
         "GenericParameters":null,
         "IsEnum":false,
         "EnumValues":null,
         "TypeName":"DateTime",
         "TypeFullname":"System.DateTime",
         "Properties":[  
            {  
               "Name":"Date",
               "TypeName":"System.DateTime",
               "Description":null,
               "Type":1,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"Day",
               "TypeName":"System.Int32",
               "Description":null,
               "Type":1,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"DayOfWeek",
               "TypeName":"System.DayOfWeek",
               "Description":null,
               "Type":1,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"DayOfYear",
               "TypeName":"System.Int32",
               "Description":null,
               "Type":1,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"Hour",
               "TypeName":"System.Int32",
               "Description":null,
               "Type":1,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"Kind",
               "TypeName":"System.DateTimeKind",
               "Description":null,
               "Type":1,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"Millisecond",
               "TypeName":"System.Int32",
               "Description":null,
               "Type":1,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"Minute",
               "TypeName":"System.Int32",
               "Description":null,
               "Type":1,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"Month",
               "TypeName":"System.Int32",
               "Description":null,
               "Type":1,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"Now",
               "TypeName":"System.DateTime",
               "Description":null,
               "Type":1,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"UtcNow",
               "TypeName":"System.DateTime",
               "Description":null,
               "Type":1,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"Second",
               "TypeName":"System.Int32",
               "Description":null,
               "Type":1,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"Ticks",
               "TypeName":"System.Int64",
               "Description":null,
               "Type":1,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"TimeOfDay",
               "TypeName":"System.TimeSpan",
               "Description":null,
               "Type":1,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"Today",
               "TypeName":"System.DateTime",
               "Description":null,
               "Type":1,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"Year",
               "TypeName":"System.Int32",
               "Description":null,
               "Type":1,
               "IsOptional":false,
               "DefaultValue":null
            }
         ]
      },
      {  
         "Description":null,
         "IsGeneric":false,
         "IsArray":false,
         "GenericParameters":null,
         "IsEnum":true,
         "EnumValues":[  
            {  
               "Name":"Sunday",
               "TypeName":"System.DayOfWeek",
               "Description":null,
               "Type":0,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"Monday",
               "TypeName":"System.DayOfWeek",
               "Description":null,
               "Type":0,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"Tuesday",
               "TypeName":"System.DayOfWeek",
               "Description":null,
               "Type":0,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"Wednesday",
               "TypeName":"System.DayOfWeek",
               "Description":null,
               "Type":0,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"Thursday",
               "TypeName":"System.DayOfWeek",
               "Description":null,
               "Type":0,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"Friday",
               "TypeName":"System.DayOfWeek",
               "Description":null,
               "Type":0,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"Saturday",
               "TypeName":"System.DayOfWeek",
               "Description":null,
               "Type":0,
               "IsOptional":false,
               "DefaultValue":null
            }
         ],
         "TypeName":"DayOfWeek",
         "TypeFullname":"System.DayOfWeek",
         "Properties":null
      },
      {  
         "Description":null,
         "IsGeneric":false,
         "IsArray":false,
         "GenericParameters":null,
         "IsEnum":true,
         "EnumValues":[  
            {  
               "Name":"Unspecified",
               "TypeName":"System.DateTimeKind",
               "Description":null,
               "Type":0,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"Utc",
               "TypeName":"System.DateTimeKind",
               "Description":null,
               "Type":0,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"Local",
               "TypeName":"System.DateTimeKind",
               "Description":null,
               "Type":0,
               "IsOptional":false,
               "DefaultValue":null
            }
         ],
         "TypeName":"DateTimeKind",
         "TypeFullname":"System.DateTimeKind",
         "Properties":null
      },
      {  
         "Description":null,
         "IsGeneric":false,
         "IsArray":false,
         "GenericParameters":null,
         "IsEnum":false,
         "EnumValues":null,
         "TypeName":"TimeSpan",
         "TypeFullname":"System.TimeSpan",
         "Properties":[  
            {  
               "Name":"Ticks",
               "TypeName":"System.Int64",
               "Description":null,
               "Type":1,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"Days",
               "TypeName":"System.Int32",
               "Description":null,
               "Type":1,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"Hours",
               "TypeName":"System.Int32",
               "Description":null,
               "Type":1,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"Milliseconds",
               "TypeName":"System.Int32",
               "Description":null,
               "Type":1,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"Minutes",
               "TypeName":"System.Int32",
               "Description":null,
               "Type":1,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"Seconds",
               "TypeName":"System.Int32",
               "Description":null,
               "Type":1,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"TotalDays",
               "TypeName":"System.Double",
               "Description":null,
               "Type":1,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"TotalHours",
               "TypeName":"System.Double",
               "Description":null,
               "Type":1,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"TotalMilliseconds",
               "TypeName":"System.Double",
               "Description":null,
               "Type":1,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"TotalMinutes",
               "TypeName":"System.Double",
               "Description":null,
               "Type":1,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"TotalSeconds",
               "TypeName":"System.Double",
               "Description":null,
               "Type":1,
               "IsOptional":false,
               "DefaultValue":null
            }
         ]
      },
      {  
         "Description":"Represent Zone information",
         "IsGeneric":false,
         "IsArray":false,
         "GenericParameters":null,
         "IsEnum":false,
         "EnumValues":null,
         "TypeName":"ZoneInfo",
         "TypeFullname":"ParadoxOnConstellation.ZoneInfo",
         "Properties":[  
            {  
               "Name":"IsOpen",
               "TypeName":"System.Boolean",
               "Description":"A value indicating whether this zone is open.",
               "Type":1,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"IsTamper",
               "TypeName":"System.Boolean",
               "Description":"A value indicating whether this zone is tamper.",
               "Type":1,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"InAlarm",
               "TypeName":"System.Boolean",
               "Description":"A value indicating whether this zone is in alarm.",
               "Type":1,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"InFireAlarm",
               "TypeName":"System.Boolean",
               "Description":"A value indicating whether this zone is in fire alarm].",
               "Type":1,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"SupervisionLost",
               "TypeName":"System.Boolean",
               "Description":"A value indicating whether this zone has supervision lost.",
               "Type":1,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"LowBattery",
               "TypeName":"System.Boolean",
               "Description":"A value indicating whether this zone has low battery.",
               "Type":1,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"Id",
               "TypeName":"System.Int32",
               "Description":"The identifier.",
               "Type":1,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"Type",
               "TypeName":"System.String",
               "Description":"The object type.",
               "Type":1,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"Name",
               "TypeName":"System.String",
               "Description":"The name.",
               "Type":1,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"LastActivity",
               "TypeName":"System.DateTime",
               "Description":"The last activity.",
               "Type":1,
               "IsOptional":false,
               "DefaultValue":null
            }
         ]
      },
      {  
         "Description":null,
         "IsGeneric":false,
         "IsArray":false,
         "GenericParameters":null,
         "IsEnum":false,
         "EnumValues":null,
         "TypeName":"AreaInfo",
         "TypeFullname":"ParadoxOnConstellation.AreaInfo",
         "Properties":[  
            {  
               "Name":"IsFullArmed",
               "TypeName":"System.Boolean",
               "Description":null,
               "Type":1,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"IsStayArmed",
               "TypeName":"System.Boolean",
               "Description":null,
               "Type":1,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"ZoneInMemory",
               "TypeName":"System.Boolean",
               "Description":null,
               "Type":1,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"HasTrouble",
               "TypeName":"System.Boolean",
               "Description":null,
               "Type":1,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"IsReady",
               "TypeName":"System.Boolean",
               "Description":null,
               "Type":1,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"IsInProgramming",
               "TypeName":"System.Boolean",
               "Description":null,
               "Type":1,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"InAlarm",
               "TypeName":"System.Boolean",
               "Description":null,
               "Type":1,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"Strobe",
               "TypeName":"System.Boolean",
               "Description":null,
               "Type":1,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"Id",
               "TypeName":"System.Int32",
               "Description":"The identifier.",
               "Type":1,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"Type",
               "TypeName":"System.String",
               "Description":"The object type.",
               "Type":1,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"Name",
               "TypeName":"System.String",
               "Description":"The name.",
               "Type":1,
               "IsOptional":false,
               "DefaultValue":null
            },
            {  
               "Name":"LastActivity",
               "TypeName":"System.DateTime",
               "Description":"The last activity.",
               "Type":1,
               "IsOptional":false,
               "DefaultValue":null
            }
         ]
      }
   ]
}

The post L’interface REST « Constellation » appeared first on Constellation.

Un consommateur peut :

• Consommer des StateObjects (Request ou Subscribe)
• Envoyer ou recevoir des messages

Généralités

Construction de l’URL

L’URL est :  <Root URI>/rest/consumer/<action>?<paramètres>

Partons du principe que votre Constellation est exposée en HTTP sur le port 8088 (sans path). On retrouvera dans le fichier de configuration la section suivante :

<listenUris>
  <uri listenUri="http://+:8088/" />
</listenUris>

La “Root URI “ est donc “http://<ip ou dns>:8088/”.

Par exemple si nous sommes en local, nous pourrions écrire :

http://localhost:8088/rest/consumer/xxxxx

Authentification

Comme pour toutes les requêtes vers Constellation vous devez impérativement spécifier dans les headers HTTP ou dans les paramètres de l’URL (querystring), les paramètres “SentinelName”, “PackageName” et “AccessKey” pour l’authentification.

Dans le cas de l’API “Consumer”, la “SentinelName” est “Consumer” et le “PackageName” est le nom de votre choix que l’on considère comme un “FriendlyName”. Typiquement le “FriendlyName” est par exemple le nom de l’application/page qui se connecte.

L’AccessKey doit bien sur être déclarée et activée sur le serveur.

Ainsi chaque appel sera sous la forme :

http://localhost:8088/rest/consumer/<action>?SentinelName=Consumer&PackageName=<Friendly name>&AccessKey=<access key>&<paramètres>

Check Access

Toutes les API REST de Constellation exposent une méthode en GET “CheckAccess” qui retourne un code HTTP 200 (OK). Cela permet de tester la connexion et l’authentification au serveur Constellation.

• Action : “CheckAccess” (GET)
• Paramètres : aucun

Exemple :

http://localhost:8088/rest/consumer/CheckAccess?SentinelName=Consumer&PackageName=Demo&AccessKey=MaCleDeTest123

Envoyer des messages

• Action : “SendMessage” (GET ou POST)
• En GET, voici les paramètres de l’URL :
  • scope : le type de scope (All, Other, Group, Sentinel ou Package)
  • args : les arguments du scope (par exemple le nom du groupe, de la sentinelle, du package ou de l’instance du package – plusieurs valeurs possibles séparées par des virgules)
  • key : la clé du message (= la méthode à invoquer)
  • data : le contenu du message (= les arguments de la méthode)
  • sagaId (optionnel) : l’identification de la saga si le message est envoyé dans une saga

Vous pouvez également invoquer cette action en POST. Le corps de votre requête contiendra l’objet JSON suivant :

{
  "Scope" : { "Scope" : "<type>", Args: [ "<arg1>", "<args2>", .... ], "SagaId":"Identifiant de la Saga" },
  "Key" : "<Key>",
  "Data" : "<Data>"
}

La propriété “SagaId” dans le JSON ci-dessus est optionnelle.

Par exemple pour envoyer un message au package Nest en invoquant la méthode (key) “SetTargetTemperature” avec en paramètre le nombre “21” :

http://localhost:8088/rest/consumer/SendMessage?SentinelName=Consumer&PackageName=Demo&AccessKey=MaCleDeTest123&scope=Package&args=Nest&key=SetTargetTemperature&data=21

Par exemple pour invoquer ce MessageCallback depuis cURL :

curl "http://localhost:8088/rest/consumer/SendMessage?SentinelName=Consumer&PackageName=Demo&AccessKey=MaCleDeTest123&scope=Package&args=Nest&key=SetTargetTemperature&data=21"

Ce même MessageCallback “SetTargetTemperature” du package Nest peut être invoqué dans une saga afin de recevoir un un accusé de réception :

http://localhost:8088/rest/consumer/SendMessage?SentinelName=Consumer&PackageName=Demo&AccessKey=MaCleDeTest123&scope=Package&args=Nest&key=SetTargetTemperature&data=21&sagaId=123456789

Il faudra ensuite “récupérer” les messages reçus (voir dessous) pour lire la réponse à votre saga que nous avons ici identifié par la clé “123456789”.

Autre exemple avec un MessageCallback avec plusieurs paramètres :

http://localhost:8088/rest/consumer/SendMessage?SentinelName=Consumer&PackageName=Demo&AccessKey=MaCleDeTest123&scope=Package&args=MyPackage&key=MethodeAvec3Params&data=[ 'param 1', 123, true ]

Attention le contenu du paramètre « args » doit être encodé. De ce fait, avec cURL :

curl "http://localhost:8088/rest/consumer/SendMessage?SentinelName=Consumer&PackageName=Demo&AccessKey=MaCleDeTest123&scope=Package&args=MyPackage&key=MethodeAvec3Params&data=%5B+%27param+1%27%2C+123%2C+true+%5D"

Pour invoquer ce même MC avec un « POST » depuis cURL :

curl -H "Content-Type: application/json" -X POST -i -d '{ "Scope" : { "Scope" : "Package", Args: [ "MyPackage"] }, "Key" : "MethodeAvec3Params", "Data" : [ "param 1", 123, true ] }' "http://localhost:8088/rest/consumer/SendMessage?SentinelName=Consumer&PackageName=Demo&AccessKey=MaCleDeTest123"

Recevoir des messages

Créer un abonnement de réception

Tout d’abord pour recevoir des messages il faut s’abonner aux messages.

• Action : “SubscribeToMessage” (GET)
• Paramètres :
  • subscriptionId (optionnel) : identifiant de l’abonnement si déjà connu

http://localhost:8088/rest/consumer/SubscribeToMessage?SentinelName=Consumer&PackageName=Demo&AccessKey=MaCleDeTest123

Vous obtiendrez en réponse l’ID de votre abonnement, le “Subscription Id”.

Relever les messages

• Action : “GetMessages” (GET)
• Paramètres :
  • subscriptionId : identifiant de l’abonnement
  • timeout (optionnel – par défaut 60000) : temps maximal en milliseconde de la mise en attente de la requête (entre 1000ms et 120000ms)
  • limit (optionnel – par défaut 0) : nombre maximum de message à retourner pour l’appel

Il s’agit d’une requête en “long-polling” c’est à dire que la requête sera “bloquée” sur le serveur tant qu’il n’y a pas de message reçu évitant ainsi de “flooder” en continue le serveur pour savoir si de nouveaux messages sont disponibles ou non. Par défaut la requête est bloquée 60 secondes maximum mais vous pouvez personnaliser cette valeur avec le paramètre “timeout”. Si il y a des messages disponibles, le serveur vous renvoi un tableau JSON avec les messages reçus. Si il n’y a pas de réponse dans le délai spécifié par le paramètre “timeout” (60 secondes par défaut), le tableau retourné sera vide.

A chaque réponse vous devez donc relancer une requête “GetMessages” pour “écouter” les prochains messages qui vont sont destinés.

Il est également possible de limiter le nombre de message dans la réponse avec le paramètre “limit” ce qui peut être utile sur de petits “devices” ne disposant pas de beaucoup de mémoire RAM pour désérialiser de gros tableaux JSON.

Exemple simple :

http://localhost:8088/rest/consumer/GetMessages?SentinelName=Consumer&PackageName=Demo&AccessKey=MaCleDeTest123&subscriptionId=xxxxx

Autre exemple en limitant le nombre de message à 2 par appel et en bloquant la requête pendant 10 secondes au maximum :

http://localhost:8088/rest/consumer/GetMessages?SentinelName=Consumer&PackageName=Demo&AccessKey=MaCleDeTest123&subscriptionId=xxxxx&timeout=10000&limit=2

S’abonner à un groupe

Vous pouvez vous abonner à des groupes pour recevoir les messages envoyés dans ces groupes par l’action “SubscribeToMessageGroup” en précisant le nom du groupe et votre ID d’abonnement.

• Action : “SubscribeToMessageGroup” (GET)
• Paramètres :
  • group : le nom du groupe à joindre
  • subscriptionId (optionnel) : identifiant de l’abonnement si déjà connu

http://localhost:8088/rest/consumer/SubscribeToMessageGroup?SentinelName=Consumer&PackageName=Demo&AccessKey=MaCleDeTest123&subscriptionId=xxxxx&group=A

Comme l’action “SubscribeToMessage”, cette action vous retourne l’ID d’abonnement à utiliser pour l’action “GetMessages”.

Consommation de StateObjects

Request

Cette méthode permet de récupérer la valeur actuelle d’un ou de plusieurs StateObjects.

• Action : “RequestStateObjects” (GET)
• Paramètres :
  • sentinel (optionnel – par défaut “*”): nom de la sentinelle
  • package (optionnel – par défaut “*”) : nom du package
  • name (optionnel – par défaut “*”) : nom du StateObject
  • type (optionnel – par défaut “*”) : type du StateObject

Par exemple pour récupérer tous les StateObject de votre Constellation :

http://localhost:8088/rest/consumer/RequestStateObjects?SentinelName=Consumer&PackageName=Demo&AccessKey=MaCleDeTest123

Ou seulement ceux produits par le package “HWMonitor” (quelque soit la sentinelle) :

http://localhost:8088/rest/consumer/RequestStateObjects?SentinelName=Consumer&PackageName=Demo&AccessKey=MaCleDeTest123&package=HWMonitor

Ou encore tous les StateObjects nommés “/intelcpu/load/0” et produits le package “HWMonitor” (quelque soit la sentinelle) :

http://localhost:8088/rest/consumer/RequestStateObjects?SentinelName=Consumer&PackageName=Demo&AccessKey=MaCleDeTest123&package=HWMonitor&name=/intelcpu/load/0

Subscribe

Vous pouvez également vous abonner aux mises à jour des StateObjects.

Le principe est le même qu’avec les messages : il faut récupérer un ID d’abonnement et invoquer une méthode en long-polling pour recevoir les mises à jour.

S’abonner à des StateObjects

• Action : “SubscribeToStateObjects” (GET)
• Paramètres :
  • subscriptionId (optionnel) : identifiant de l’abonnement si déjà connu
  • sentinel (optionnel – par défaut “*”): nom de la sentinelle
  • package (optionnel – par défaut “*”) : nom du package
  • name (optionnel – par défaut “*”) : nom du StateObject
  • type (optionnel – par défaut “*”) : type du StateObject

En retour vous obtiendrez l’ID d’abonnement (un GUID).

Par exemple pour s’abonner au SO “/intelcpu/load/0”, produit le package “HWMonitor” sur la sentinelle “MON-PC” :

http://localhost:8088/rest/consumer/SubscribeToStateObjects?SentinelName=Consumer&PackageName=Demo&AccessKey=MaCleDeTest123&sentinel=MON-PC&package=HWMonitor&name=/intelcpu/load/0

ATTENTION : si vous souhaitez “ajouter” des SO à votre abonnement vous devez impérativement préciser votre ID d’abonnement récupéré lors du 1er appel autrement vous allez créer un nouvel abonnement.

Par exemple pour “ajouter” le SO correspondant à la consommation RAM :

http://localhost:8088/rest/consumer/SubscribeToStateObjects?SentinelName=Consumer&PackageName=Demo&AccessKey=MaCleDeTest123&sentinel=MON-PC&package=HWMonitor&name=/ram/load&subscriptionId=<subId>

Relever les StateObjects mis à jour

Pour récupérer les SO de votre abonnement qui ont changés entre deux appels vous devez invoquer l’action “GetStateObjects” en spécifiant l’ID de votre abonnement :

• Action : “GetStateObjects” (GET)
• Paramètres :
  • subscriptionId : identifiant de l’abonnement
  • timeout (optionnel – par défaut 60000) : temps maximal en milliseconde de la mise en attente de la requête (entre 1000ms et 120000ms)
  • limit (optionnel – par défaut 0) : nombre maximum de message à retourner pour l’appel

Comme pour les message, vous pouvez limiter le nombre de SO (limit) et le timeout de la requête (timeout).

http://localhost:8088/rest/consumer/GetStateObjects?SentinelName=Consumer&PackageName=Demo&AccessKey=MaCleDeTest123&subscriptionId=<subId>

Notez que si un StateObject pour lequel vous êtes abonné change plusieurs fois entre deux appels “GetStateObjects”, vous obtiendrez la dernière valeur et non l’historique de tous les changements.

The post L’interface REST « Consumer » appeared first on Constellation.