Tag Subscribe - Constellation https://developer.myconstellation.io/tag/subscribe/ Votre plateforme d'interconnexion Thu, 19 Apr 2018 07:49:37 +0000 fr-FR hourly 1 https://wordpress.org/?v=6.0.11 https://developer.myconstellation.io/wp-content/uploads/2016/02/256x256-e1457476015859.png Tag Subscribe - Constellation https://developer.myconstellation.io/tag/subscribe/ 32 32 Nouvelle librairie Constellation pour Arduino / ESP8266 en version 2.0 https://developer.myconstellation.io/blog/nouvelle-librairie-constellation-pour-arduino-esp8266-en-version-2-0/ https://developer.myconstellation.io/blog/nouvelle-librairie-constellation-pour-arduino-esp8266-en-version-2-0/#comments Tue, 13 Sep 2016 13:20:38 +0000 https://developer.myconstellation.io/?p=2546 J’ai le plaisir de  vous annoncer l’arrivée de la nouvelle libraire Constellation pour Arduino/ESP en version 2.0. 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

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

]]> J’ai le plaisir de  vous annoncer l’arrivée de la nouvelle libraire Constellation pour Arduino/ESP en version 2.0.

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 !

MessageCallback Explorer

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 Clignement d'œil

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.

]]> https://developer.myconstellation.io/blog/nouvelle-librairie-constellation-pour-arduino-esp8266-en-version-2-0/feed/ 2 Consommer Constellation avec Angular JS https://developer.myconstellation.io/client-api/javascript-api/consommer-constellation-angular-js/ https://developer.myconstellation.io/client-api/javascript-api/consommer-constellation-angular-js/#comments Fri, 19 Aug 2016 08:27:12 +0000 https://developer.myconstellation.io/?p=2331 Préparer la page AngularJS Vous pouvez soit utiliser le gestionnaire de package Nuget depuis Visual Studio pour installer la dernière version du package “Constellation.Angular” et ses dépendances : Ou bien utiliser (ou copier en local) les scripts des CDN en

The post Consommer Constellation avec Angular JS appeared first on Constellation.

]]> Préparer la page AngularJS

Vous pouvez soit utiliser le gestionnaire de package Nuget depuis Visual Studio pour installer la dernière version du package “Constellation.Angular” et ses dépendances :

image

Ou bien utiliser (ou copier en local) les scripts des CDN en ajoutant dans votre code HTML les balises suivantes :

<script type="text/javascript" src="https://code.jquery.com/jquery-2.2.4.min.js"></script>
<script type="text/javascript" src="https://ajax.aspnetcdn.com/ajax/signalr/jquery.signalr-2.2.2.min.js"></script>
<script type="text/javascript" src="https://cdn.myconstellation.io/js/Constellation-1.8.2.min.js"></script>
<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/angularjs/1.5.7/angular.min.js"></script>
<script type="text/javascript" src="https://cdn.myconstellation.io/js/ngConstellation-1.8.2.min.js"></script>

Dans votre code Javascript, vous devez créer un module Angular pour votre page que nous appelleront “MyDemoApp” et dans lequel nous injecterons le module “ngConstellation” :

var myDemoApp = angular.module('MyDemoApp', ['ngConstellation']);

Vous devez également ajouter l’attribut “ng-app” sur la balise <html> de votre page pour lier votre page HTML à votre module Angular :

<html xmlns="http://www.w3.org/1999/xhtml" ng-app="MyDemoApp">

Enfin vous devez créer un contrôleur AngularJS dans lequel nous injecterons la factory “constellationConsumer” que nous appellerons dans notre code “constellation” :

myDemoApp.controller('MyController', ['$scope',  'constellationConsumer', function ($scope, constellation) {

}]);

Sans oublier de lier votre corps de page (<body>) à ce contrôleur :

<body ng-controller="MyController">

Et voilà votre squelette est prêt !

Pour plus d’information sur AngularJS, je vous recommande la lecture de ce guide : https://docs.angularjs.org/misc/started

Pour résumer notre squelette page est donc :

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" ng-app="MyDemoApp">
<head>
    <title>Test API AngularJS</title>
    <script type="text/javascript" src="https://code.jquery.com/jquery-2.2.4.min.js"></script>
    <script type="text/javascript" src="https://ajax.aspnetcdn.com/ajax/signalr/jquery.signalr-2.2.2.min.js"></script>
    <script type="text/javascript" src="https://cdn.myconstellation.io/js/Constellation-1.8.2.min.js"></script>
    <script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/angularjs/1.5.7/angular.min.js"></script>
    <script type="text/javascript" src="https://cdn.myconstellation.io/js/ngConstellation-1.8.2.min.js"></script>
    
    <script>
        var myDemoApp = angular.module('MyDemoApp', ['ngConstellation']);
        myDemoApp.controller('MyController', ['$scope',  'constellationConsumer', function ($scope, constellation) {

        }]);
    </script>

</head>
<body ng-controller="MyController">

</body>
</html>

Connecter une page HTML à Constellation avec AngularJS

Dans notre contrôleur AngularJS, nous allons initialiser le client Consumer en spécifiant l’URL de votre serveur Constellation, la clé d’accès et le “Friendly name” de votre page :

constellation.initializeClient("http://localhost:8088", "123456789", "TestAPI");

Vous pouvez créer une clé d’accès depuis la Console Constellation ou en éditant le fichier de configuration du serveur.

Enfin ajoutons un handler sur le changement d’état de la connexion pour afficher le message “Je suis connecté” dans la console de votre navigateur par exemple lorsque la connexion à Constellation est établie :

constellation.onConnectionStateChanged(function (change) {
    if (change.newState === $.signalR.connectionState.connected) {
        console.log("Je suis connecté !");
    }
});

Il ne reste plus qu’à lancer la connexion en invoquant la méthode “connect” :

constellation.connect();

Et voilà, votre page AngularJS est connectée à votre Constellation.

Envoyer des messages et invoquer des MessageCallbacks

Envoyer des messages

Pour envoyer des messages et donc invoquer des MessageCallbacks vous devez utiliser la méthode “constellation.sendMessage” en spécifiant :

  • Le scope
  • La clé du message
  • Le contenu du message (= les paramètres du MessageCallback)

Par exemple, avec le package Nest déployé dans votre Constellation, on retrouvera un MessageCallback  “SetTargetTemperature” pour piloter la température de consigne d’un thermostat Nest.

image

N’hésitez pas à utiliser le MessageCallback Explorer pour découvrir l’ensemble des MessageCallbacks exposés par les packages de votre Constellation.

Pour invoquer le MessageCallback  “SetTargetTemperature” depuis votre page Web en passant en paramètre l’ID du thermostat et la température de consigne :

constellation.sendMessage({ Scope: 'Package', Args: ['Nest'] }, 'SetTargetTemperature', 'my_thermostat_id', 19);

En AngularJS, pour lier l’invocation de ce code à un bouton, vous devez simplement ajouter l’attribut “ng-click” sur votre bouton.

Par exemple, dans votre code HTML :

<body ng-controller="MyController">
    <button ng-click="SetNestTemperature()">Set Nest to 19°C</button>
</body>

Et dans votre contrôleur :

$scope.SetNestTemperature = function () {
   constellation.sendMessage({ Scope: 'Package', Args: ['Nest'] }, 'SetTargetTemperature', 'my_thermostat_id', 19);
};

Autre solution, exposer le client Consumer dans le scope AngularJS :

$scope.constellation = constellation;

Et donc s’en servir directement dans le template HTML :

<body ng-controller="MyController">
    <button ng-click="constellation.sendMessage({ Scope: 'Package', Args: ['Nest'] }, 'SetTargetTemperature', 'my_thermostat_id', 19)">Set Nest to 19°C</button>
</body>

Allons un peu plus loin en ajoutant un champ permettant à l’utilisateur de définir la température de consigne.

Dans le template HTML :

Temperature : <input type="number" ng-model="targetTemperature" />
<button ng-click="SetNestTemperature()">Set target temperature</button>

Le champ “input” est de type “number” et est lié à la variable de scope (le modèle) que nous appellerons “targetTemperature”.

De ce  fait dans notre fonction “SetNestTemperature” nous pouvons récupérer la valeur définie par l’utilisateur :

$scope.SetNestTemperature = function () {
   constellation.sendMessage({ Scope: 'Package', Args: ['Nest'] }, 'SetTargetTemperature', 'my_thermostat_id', $scope.targetTemperature);
};

image

Comme pour l’API Javascript, vous pouvez également passer plusieurs arguments à votre MC combinant type simple et type complexe. Si il y a plusieurs paramètres vous devez les stocker dans un tableau.

Par exemple le MC “ShowNotification” du package Xbmc permettant d’afficher une notification sur une interface Kodi/XBMC prend deux paramètres : le nom d l’hôte XBMC (un type string) et le détail de la notification à afficher (un type complexe) :

image

constellation.sendMessage({ Scope: 'Package', Args: ['Xbmc'] }, 'ShowNotification', xbmcName, { "Title":"Hello", "Message":"Hello from JS" });

Bien entendu vous pouvez invoquer des MessageCallbacks de n’importe quel package, réel (programme Linux/Windows) ou virtuel (Arduino/ESP, scripts, etc..) ou même sur d’autres consommateurs (pages Web par exemple).

Ainsi vos pages Web peuvent, en envoyant des messages, invoquer des méthodes sur n’importe quel système connecté dans votre Constellation.

Par exemple dans l’article sur les ESP/Arduinos, notre ESP8266 exposait un MC “Reboot” pour redémarrer la puce. Si l’on souhaite redémarrer notre Arduino/ESP depuis une page Web, il suffirai d’envoyer un message sans paramètre au bon scope. Par exemple :

constellation.sendMessage({ Scope: 'Sentinel', Args: ['MyArduino'] }, 'Reboot');

Ici le scope est “Sentinel” avec l’argument “MyArduino”, c’est à dire que le message “Reboot” sera envoyé à tous les packages de la sentinelle “MyArduino”.

Les scopes peuvent être :

  • Sentinel
  • Package
  • Group
  • Others
  • All

La propriété “Args” de l’objet scope est un tableau contenant le nom des groupes, des sentinelles ou packages en fonction du type de scope sélectionné. Seuls les scopes “All” et “Others” n’ont pas besoin d’argument.

Envoyer des messages avec réponse : les sagas

Les Sagas permettent de lier des messages et donc de créer des couples de “requêtes / réponses”.

Avec la libraire JavaScript, il est possible d’envoyer des messages dans une saga et d’enregistrer un callback pour traiter la réponse de ce message.

Par exemple, le package “NetworkTools” expose un MC “Ping” permettant de réaliser un ping réseau. Le résultat du ping est retourné dans un message de réponse (un Int64 représentant le temps du réponse du ping) :

image_thumb2

De ce fait pour réaliser un ping depuis une page Web, on pourrait proposer à l’utilisateur un champ pour saisir l’adresse à pinger et afficher le résultat dans un paragraphe.

<body ng-controller="MyController">
   Host/IP : <input ng-model="host" />
   <button ng-click="Ping()">Ping</button>
   <p ng-show="pingResult">Result : {{pingResult}}ms</p>
</body>

Vous remarquez que le paragraphe du n’est affiché (ng-show) que si la valeur de scope “pingResult” est définie, ce qui n’est pas le cas à l’ouverture de la page.

Déclarons enfin la méthode de scope “Ping” pour envoyer un message au package “NetworkTools” afin d’invoquer dans une saga sur le MC “Ping” avec en paramètre du message variable « $scope.host » qui est liée à la zone de texte (input) de votre vue HTML.

Comme il s’agit d’une saga, nous utilisons la méthode “sendMessageWithSaga” dans laquelle nous passons la fonction callback qui sera invoquée lors de la réponse. A la réception cette réponse, nous allons tous simplement stocker le résultat de la réponse (propriété Data) dans la variable de scope “pingResult”.

L’affectation de la réponse dans la variable de scope “pingResult” est réalisée dans un “$scope.$apply”, une fonction AngularJS qui permet d’indiquer au contrôleur AngularJS que des variables de scope ont été modifiées et donc qu’il faut rafraîchir la vue.

image

image

scope.Ping = function () {
  constellation.sendMessageWithSaga(function(response) {
      $scope.$apply(function() {
        $scope.pingResult = response.Data;
      });
    }, { Scope: 'Package', Args: ['NetworkTools'] }, 'Ping', $scope.host);
};

Ainsi vos pages Web peuvent invoquer des méthodes et exploiter la réponse de tous les systèmes connectés sur Constellation exposant des MessageCallbacks.

Recevoir des messages

Une page Web connectée sur Constellation peut elle même recevoir des messages et donc exposer des MessageCallbacks que d’autres consommateurs (autres pages Web) ou packages (réels et virtuels) pourront invoquer.

Ceci dit un consommateur tel qu’une page Web n’a pas réellement d’existence. Autrement dit elle n’a pas d’identité et donc ne peut recevoir que des messages adressés à un groupe qu’elle devra joindre.

Pour joindre un groupe vous devez utiliser la méthode “subscribeMessages“ (et “unSubscribeMessages” pour en sortir). Vous pouvez joindre autant de groupe que vous souhaitez.

Par exemple, pour ajouter votre page au groupe “Demo” :

constellation.subscribeMessages("Demo");

Vous pourrez ensuite recevoir les messages envoyés dans ce groupe en ajoutant un handler sur le “onReceiveMessage” :

constellation.onReceiveMessage(function (message) {
    console.log("Message recu !", message);
});

Dans ce handler vous recevrez TOUS les messages (quelque soit la clé du message).

Vous avez aussi un moyen plus simple consistant à définir un handler pour une clé de message spécifiquement via la méthode “registerMessageCallback”.

Par exemple :

constellation.registerMessageCallback("ChangeTitle", function (msg) {
    document.title = msg.Data;
});
constellation.registerMessageCallback("HelloWorld", function (msg) {
    alert("Hello World");
});

Ici on enregistre deux MessageCallbacks.

Si votre page reçoit un MessageCallback “HelloWorld”, une alerte sera ouverte, si elle reçoit un MessageCallback “ChangeTitle”, le titre de votre page sera modifié avec l’argument passé dans le MC.

Bien entendu, comme vos pages HTML peuvent enregistrer autant de MessageCallbacks qu’elles souhaitent et que ces MessageCallbacks sont invocables depuis n’importe quel système connecté à Constellation, d’autres pages Web, des objets à base d’Arduino, ESP ou autre, des programmes Python, .NET, etc… vous pouvez imaginer tout type d’usage.

Consommer des StateObjects

Pour consommer des StateObjects produits par des packages (virtuels ou réels) de votre Constellation, vous avez deux méthodes : l’évènement “onUpdateStateObject” ou les StateObjectLinks.

La première méthode consiste à enregistre un ou plusieurs handlers sur l’évènement “onUpdateStateObject” :

constellation.onUpdateStateObject(function (stateobject) {
    console.log(stateobject);
});

Les handlers seront déclenchés à chaque mise à jour ou interrogation des StateObjects de votre page quelque soit le StateObject.

Pour interroger un ou plusieurs StateObjects à un instant T vous disposez de la méthode “requestStateObjects”.

Pour vous abonner aux mises à jour d’un ou plusieurs StateObjects, vous disposez de la méthode “subscribeStateObjects” (et “unSubscribeStateObjects” pour vous désabonner).

Enfin la méthode “requestSubscribeStateObjects” réalise un “requestStateObjects” et un “subscribeStateObjects” c’est à dire que la méthode demande la valeur actuelle du ou des StateObjects et s’abonne auprès du serveur Constellation pour être notifiée des mises à jour.

Toutes ces méthodes prennent en paramètre : le nom de la sentinelle, le nom du package, le nom du StateObject et le type du StateObject. Vous pouvez utiliser le wildcard “*” pour ne pas appliquer de filtre (plus d’information ici).

Par exemple, pour récupérer tous les StateObjects du package “Demo” quelque soit la sentinelle et pour s’abonner aux mises à jour de ces StateObjects :

constellation.requestSubscribeStateObjects("*", "Demo", "*", "*");

L’autre méthode consiste à enregistrer un (ou plusieurs) StateObjectLink. Cela permet de lier une fonction à un abonnement.

Par exemple :

constellation.registerStateObjectLink("*", "HWMonitor", "/intelcpu/0/load/0", "*", function (so) {
    // Code A
});

constellation.registerStateObjectLink("*", "Demo", "*", "*", function (so) {
    // Code B
});

Ci-dessus le code A sera invoqué dès qu’un SO nommé « /intelcpu/0/load/0” et produit par le package “HWMonitor” est modifié alors que le code B sera déclenché dès qu’un StateObject du package “Demo” est modifié.

Prenons un cas pratique, nous voulons afficher en temps réel la consommation de notre CPU. Comme expliqué ci-dessus, la consommation peut être connue avec le StateObject nommé « /intelcpu/0/load/0” et produit par le package “HWMonitor”.

Nous allons donc ajouter un StateObjectLink et affecter la variable de scope “cpu” à chaque mise à jour de ce SO. Comme pour la réception de message, nous devons utiliser la fonction Angular “$scope.$apply” pour informer le contrôleur Angular que nous avons changé une variable de scope :

Aussi vous devez enregistrer vos SOLink une fois connecté :

constellation.onConnectionStateChanged(function (change) {
  if (change.newState === $.signalR.connectionState.connected) {
    constellation.registerStateObjectLink("*", "HWMonitor", "/intelcpu/0/load/0", "*", function (so) {
      $scope.$apply(function() {
        $scope.cpu = so.Value.Value;
      });
    });
  }
});

Et dans notre template :

<body ng-controller="MyController">
    <p>CPU : {{cpu}}</p>
</body>

image

Plutôt que stocker dans notre variable de scope la propriété “Value” de la valeur de notre StateObject, nous pouvons aussi stocker le StateObject lui même :

$scope.cpu = so;

De ce fait dans le template nous pouvons afficher différentes informations contenu dans notre StateObject  :

<body ng-controller="MyController">
    <p>CPU on {{cpu.SentinelName }} at {{cpu.LastUpdate}} is <strong>{{cpu.Value.Value}} {{cpu.Value.Unit}}</strong></p>
</body>

image

Alors bien sûr le format de la date ou encore la précision de la valeur mesurée par le package HWMonitor ne sont très lisibles. Nous pouvons ajouter des filtres AngularJS directement dans notre template pour rendre notre page plus “user-friendly”.

Utilisons le filtre “date” pour formater la date et “number” pour limiter le nombre de chiffre après la virgule :

<p>CPU on {{cpu.SentinelName }} at {{cpu.LastUpdate | date : 'dd//MM/yyyy @ hh:mm:ss' }} is <strong>{{cpu.Value.Value | number:2}} {{cpu.Value.Unit}}</strong></p>

image

C’est toute la magie d’AngularJS Clignement d'œil

Allons encore un peu plus loin !

Ici nous avons lié notre variable de scope “cpu” au StateObject nommé « /intelcpu/0/load/0” et produit par le package “HWMonitor”. Mais n’oubliez pas que l’unicité d’un StateObject est obtenu avec le triplet : Sentinelle + Package + Nom.

Autrement dit il peut y avoir plusieurs SO qui correspondent à ce filtre dans le cas où vous avez déployé le package HWMonitor sur plusieurs sentinelles.

Dans ce cas, la valeur du SO est sans cesse écrasée et notre page devient illisible :

cpus

Nous allons gérer ce cas en créant une variable de scope qui contiendra les différents StateObjects de nos CPUs.

Dans votre scope, commençons par déclarer une variable de scope nommée “cpus” en l’initialisant avec un objet vide :

$scope.cpus = {}

Modifions notre StateObjectLink pour stocker le StateObject dans notre objet “cpus” sous la propriété du nom de la sentinelle de notre StateObject.

constellation.registerStateObjectLink("*", "HWMonitor", "/intelcpu/0/load/0", "*", function (so) {
  $scope.$apply(function() {
    $scope.cpus[so.SentinelName.replace("-", "")] = so;
  });
});

C’est à dire que notre variable de scope “cpus” est un objet avec des propriétés du nom de la sentinelle et qui contient le StateObject de son CPU associé.

Attention le nom de la sentinelle est utilisée comme nom de propriété de notre objet JavaScript et vous n’êtes pas sans savoir que les “-“ (entre autre) ne sont pas autorisés en JS ce qui explique que nous les effaçons avec le “replace”.

Ainsi si je veux afficher dans mon template le CPU de ma machine nommée ”PC-SEB_UI” (= propriété “PCSEB_UI”), je devrais écrire :

<p>CPU on {{cpus.PCSEB_UI.SentinelName }} at {{cpus.PCSEB_UI.LastUpdate | date : 'dd//MM/yyyy @ hh:mm:ss' }} is <strong>{{cpus.PCSEB_UI.Value.Value | number:2}} {{cpus.PCSEB_UI.Value.Unit}}</strong></p>

Il ni a plus d’effet indésirable de voir les StateObjects chevaucher constamment.

Mais on peut aller encore plus loin car notre variable “cpus” contient tous les SO de la consommation de CPU produits par l’ensemble des packages HWMonitor de notre Constellation.

Il suffit d’itérer sur cette variable pour afficher le SO de chaque propriété de notre objet. Avec AngularJS vous pouvez utiliser la directive “ng-repeat” :

<p ng-repeat="cpu in cpus">CPU on {{cpu.SentinelName }} at {{cpu.LastUpdate | date : 'dd//MM/yyyy @ hh:mm:ss' }} is <strong>{{cpu.Value.Value | number:2}} {{cpu.Value.Unit}}</strong></p>

Nous obtenons une page capable d’afficher en temps réel la consommation de toutes nos machines Windows dans une simple page HTML :

cpus2

The post Consommer Constellation avec Angular JS appeared first on Constellation.

]]> https://developer.myconstellation.io/client-api/javascript-api/consommer-constellation-angular-js/feed/ 1 Consommer des StateObjects depuis un Arduino/ESP https://developer.myconstellation.io/client-api/arduino-esp-api/consommer-des-stateobjects-depuis-arduino-esp/ https://developer.myconstellation.io/client-api/arduino-esp-api/consommer-des-stateobjects-depuis-arduino-esp/#respond Tue, 23 Aug 2016 13:20:32 +0000 https://developer.myconstellation.io/?p=2463 Interroger des StateObjects à un instant T Pour récupérer un ou plusieurs StateObject (à un instant T), vous pouvez utiliser la méthode “requestStateObjects” : [crayon-6971152ced605985489295/] Utilisez le wildcard “” pour ne pas appliquer de filtre. Le symbole “” est aussi

The post Consommer des StateObjects depuis un Arduino/ESP appeared first on Constellation.

]]> Interroger des StateObjects à un instant T

Pour récupérer un ou plusieurs StateObject (à un instant T), vous pouvez utiliser la méthode “requestStateObjects” :

JsonArray& myStateObject = constellation.requestStateObjects(sentinel, package, name, type);

Utilisez le wildcard “” pour ne pas appliquer de filtre. Le symbole “” est aussi accessible via la constante “WILDCARD”.

Par exemple :

// All StateObjects for MyPackage on MySentinel
JsonArray& so = constellation.requestStateObjects("MySentinel", "MyPackage", "*", "*");
// All StateObjects named "Demo" in your Constellation
JsonArray& so = constellation.requestStateObjects(WILDCARD, WILDCARD, "Demo", WILDCARD);

Autre exemple, vous souhaitez afficher dans les logs Constellation, la consommation CPU de toutes vos machines Windows (vous avez au préalable déployé le package “HWMonitor” sur toutes vos sentinelles Windows) depuis votre Arduino :

// 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"].as<char *>(), cpus[i]["Value"]["Value"].as<float>());
}

S’abonner aux mises à jours des StateObjects en temps réel

Vous pouvez également vous abonnez aux mises à jour des StateObjects pour être notifié en temps réel de la modification des StateObjects.

En utilisant un callback global

Vous pouvez déclarer une fonction callback qui sera appelée à chaque mise à jour de StateObjects pour lesquels vous vous êtes abonné en invoquant la méthode setStateObjectUpdateCallback. Notez qu’il ne peut y avoir qu’une seule méthode callback enregistrée.

Ensuite vous abonnez aux différents StateObjects que vous souhaitez “suivre” avec la méthode “subscribeToStateObjects”.

Par exemple, pour être notifié en temps réel de la consommation CPU des différentes sentinelles Windows, on écrira :

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

Nous avons ici défini notre fonction callback dans une expression lambda mais vous pouvez aussi bien “extraire” cette fonction callback dans une fonction distincte.

Enfin dans la boucle principale (loop), vous devez invoquer la méthode “constellation.loop()” aussi souvent que possible afin que la libraire puisse dispatcher les SO dans votre méthode callback :

constellation.loop();

En utilisant des StateObjectLinks

Avec la méthode “subscribeToStateObjects” présentée ci-dessous vous avez une fonction callback qui recevra tous les StateObjects pour lesquels vous êtes abonné. Vous devez donc “dispatcher” vous même les différents StateObjects que vous recevrez.

Pour simplifier les choses, la libraire Arduino propose comme en .NET ou en Python, la notion de StateObjectLink : il s’agit de “lier” un abonnement à des StateObjects à une fonction de votre code.

Pour reprendre l’exemple du suivi des CPU en temps réel, nous pourrions écrire :

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

Vous pouvez enregistrer autant de StateObjectLink que vous le désirez. Là encore nous utilisé une expression lambda mais vous pouvez aussi bien “extraire” cette fonction callback dans une fonction distincte.

N’oubliez pas non plus d’appeler la méthode constellation.loop()” aussi souvent que possible dans la boucle principale de votre programme.

The post Consommer des StateObjects depuis un Arduino/ESP appeared first on Constellation.

]]> https://developer.myconstellation.io/client-api/arduino-esp-api/consommer-des-stateobjects-depuis-arduino-esp/feed/ 0 L’interface REST « Constellation » https://developer.myconstellation.io/client-api/rest-api/interface-rest-constellation/ https://developer.myconstellation.io/client-api/rest-api/interface-rest-constellation/#comments Tue, 16 Aug 2016 08:51:20 +0000 https://developer.myconstellation.io/?p=2296 L’interface REST “Constellation” est une API HTTP permettant d’exposer les fonctionnalités de base pour les packages “virtuels”. 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

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

]]> L’interface REST “Constellation” est une API HTTP permettant d’exposer les fonctionnalités de base pour les packages “virtuels”.

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.

]]> https://developer.myconstellation.io/client-api/rest-api/interface-rest-constellation/feed/ 1 L’interface REST « Consumer » https://developer.myconstellation.io/client-api/rest-api/interface-rest-consumer/ https://developer.myconstellation.io/client-api/rest-api/interface-rest-consumer/#comments Fri, 12 Aug 2016 14:44:31 +0000 https://developer.myconstellation.io/?p=2284 L’interface REST “Consumer” permet à tout système, script, objet ou programme de “consommer” des éléments dans une Constellation sans devoir être déclaré comme un package. Un consommateur peut : Consommer des StateObjects (Request ou Subscribe) Envoyer ou recevoir des messages Généralités

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

]]> L’interface REST “Consumer” permet à tout système, script, objet ou programme de “consommer” des éléments dans une Constellation sans devoir être déclaré comme un package.

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.

]]> https://developer.myconstellation.io/client-api/rest-api/interface-rest-consumer/feed/ 2