L’interface REST « Consumer »

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 :

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

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

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 :

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 :

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 :

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” :

Par exemple pour invoquer ce MessageCallback depuis cURL :

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

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 :

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

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

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

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 :

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

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

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 :

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

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

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” :

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 :

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).

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.