Tag AccessKey - Constellation https://developer.myconstellation.io/tag/accesskey/ Votre plateforme d'interconnexion Thu, 19 Apr 2018 08:16:29 +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 AccessKey - Constellation https://developer.myconstellation.io/tag/accesskey/ 32 32 Le fichier de configuration https://developer.myconstellation.io/constellation-platform/constellation-server/fichier-de-configuration/ https://developer.myconstellation.io/constellation-platform/constellation-server/fichier-de-configuration/#respond Tue, 09 Aug 2016 12:52:30 +0000 https://developer.myconstellation.io/?p=2149 Une Constellation est décrite en un seul fichier : le fichier de configuration Constellation. Ce fichier se nomme “Constellation.Server.exe.config” et se trouve dans le répertoire d’installation du serveur (par défaut dans “Program Files\Constellation Plateform\Server« ). Vous pouvez le modifier de différente

The post Le fichier de configuration appeared first on Constellation.

]]> Une Constellation est décrite en un seul fichier : le fichier de configuration Constellation.

Ce fichier se nomme “Constellation.Server.exe.config” et se trouve dans le répertoire d’installation du serveur (par défaut dans “Program Files\Constellation Plateform\Server« ).

Vous pouvez le modifier de différente manière :

  • En éditant ce fichier directement sur le serveur (avec un éditeur de texte type Notepad)
  • Via la Console Constellation (sur la page Configuration Editor)
  • Via Visual Studio
  • Via l’API de Management Constellation

Edition de la configuration

Le fichier contient une balise globale “configuration” dans laquelle vous trouverez 4 sections :

  • configSections : réservé au moteur .NET
  • constellation : la section de configuration Constellation (anciennement nommée ‘constellationSection’)
  • startup : réservé au moteur .NET
  • runtime : réservé au moteur .NET

Vous ne devez en aucun cas modifier les sections réservées au moteur .NET sans savoir exactement ce que vous faites.

La section de “constellation” se décompose de la façon suivante :

  • listenUris : définit la configuration des URI d’écoute du serveur Constellation
  • fileServer : définit la configuration du serveur Web statique utilisé pour l’hébergement de la Console Constellation
  • recoveryOptions : définit les options de récupération des packages
  • sentinels : définit la configuration des sentinelles (et des packages) de votre Constellation
  • settingsGroups : définit la configuration des groupes de “settings”
  • credentials : définit la configuration des credentials pour l’accès à votre Constellation

A chaque modification vous devez recharger la configuration soit via le hub de contrôle ou la Console Constellation (bouton “Reload Configuration”) ou soit en redémarrant le service Constellation Server.

Schéma de configuration

Section “listenUris”

Cette section permet de définir les URI sur lesquels le serveur Constellation doit écouter.

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

Ici le serveur répondra sur le port HTTP 8088 quelque soit le host (nom DNS ou adresse IP) car nous utilisons le wildcard “+” (pour plus d’information, lisez ceci).

Vous pouvez configurer autant de “listenUri” que vous souhaitez. Par exemple :

<listenUris>
  <uri listenUri="http://+:8088/" />
  <uri listenUri="http://constellation.mydomain.net:8888/" />
  <uri listenUri="http://+:8080/constellation/" />
  <uri listenUri="https://+:8089/" />
</listenUris>

Ici, le serveur Constellation répondra :

  • Aux requêtes sur le port HTTP 8088
  • Aux requêtes sur le port HTTP 8888 où le host est “constellation.mydomain.net” (en clair une requête http://<ip>:8888  ne fonctionnera pas)
  • Aux requêtes sur le port HTTP 8080 quelque soit le host mais dont le path doit forcement démarrer par “/constellation/”
  • Aux requêtes sur le port HTTPS 8089 en utilisant un cryptage SSL (plus d’information)

Pour prendre en compte les modifications de cette section vous devez redémarrer le service Constellation.

Section “fileServer”

Cette section permet d’activer et configurer le “fileServer” de Constellation pour héberger des fichiers statiques (pages HTML, fichiers CSS, JS, images, etc..).

Cela sert principalement pour “auto-héberger”  la Console Constellation par le serveur Constellation lui-même.

En effet, la Console Constellation n’est ni plus ni moins qu’une application Web client-side, c’est à dire une série de pages HTML avec scripts JS et fichiers CSS/Image. Libre à vous de l’héberger sur vos serveurs Web mais afin de limiter les prérequis, le serveur Constellation peut lui-même héberger la console grâce au “fileServer” intégré.

La section “fileServer” ne contient que quatre attributs :

<fileServer enable="true" path="/WebConsole" localhostOnly="true" physicalPath="D:\App\Constellation\Console" />

  • “enable” : indique si le serveur de fichier statique sur le serveur Constellation doit être activé (true ou false).
  • “path” : le répertoire d’écoute (préfixé par la listenUri).
  • “localhostOnly” : indique si le fileServer répond seulement aux requêtes “locales” ou à toutes les requêtes (true ou false).
  • “physicalPath” : le répertoire physique

Dans l’exemple ci-dessus, le serveur de fichier est activé mais ne répondra qu’aux requêtes locales. Le serveur délivra les fichiers dans “D:\App\Constellation\Console” sur l’URL “<listen_URI_du_serveur_Constellation>/WebConsole” par exemple http://localhost:8088/WebConsole ou http://127.0.0.1:8088/WebConsole en partant du principe qu’il existe une listenUri “http://+:8088”.

Comme pour la section précédente (listenUris), il faut obligatoirement redémarrer le service Constellation Server pour prendre en compte ces modifications.

Section “recoveryOptions”

Les options de récupération (recoveryOptions) permettent de définir le comportement de la sentinelle en cas d’arrêt brutale de l’exécution d’un package (crash du package).

Chaque package peut avoir ses propres options de récupération mais cette section permet de définir les options “globales”, c’est à dire appliqué par défaut pour chaque package de la Constellation.

Les options de récupérations se résume en quatre propriétés :

  • “restartAfterFailure” (true par défaut) : définit si la sentinelle doit redémarrer un package en cas de crash de ce dernier
  • “numberOfRetry” (3 par défaut) : définit le nombre maximal de tentative de redémarrage d’un package
  • “restCounterAfterMinutes” (15 par défaut) : définit la période (en minute) au delà de laquelle le compteur d’erreur est réinitialisé
  • “restartPackageAfterSeconds” (30 par défaut) : définit le délai d’attente avant de redémarrer un package suite à un crash

Dans la configuration par défaut, si un package “crash” il est automatiquement redémarré 30 secondes après son crash dans la limite de 3 tentatives sachant qu’au bout de 15 minutes, le compteur de tentative est réinitialisé à 0.

Section “sentinels”

Dans cette section vous allez déclarer vos sentinelles (virtuelles ou non) dans lesquelles vous déclarerez les packages (virtuels ou non) qui eux même déclarons leurs settings et leurs groupes.

En clair, c’est cette section qui décrit votre “Constellation”.

Prenez l’exemple de la Constellation suivante :

<sentinels>
  <sentinel name="SENTINEL-NAME-DEMO" credential="Standard">
    <packages>    
      <package name="HWMonitor" enable="true"></package>          
      <package name="DemoPackage" credential="ControlHubAccess" enable="true">
        <settings>
        <import>
          <settingGroup groupName="GroupSettingsDemo" />
        </import>
        <setting key="IntSetting" value="42" />
        <setting key="StringSetting" value="sample config value 2" />
        <setting key="SettingXml">
          <content>
            <demo type="test">
              <list count="42">
              <a>123</a>
              <b>test</b>
              </list>
            </demo>
          </content>
        </setting>
        <setting key="SettingJson">
          <content>
          <![CDATA[
          {
            ListenPorts: [ 80, 443 ],
            EnableCaching : true,
            ServerProgramName: "Hypothetical WebServer 1.0",
            Websites: [
              {
                Path: "/srv/www/example/",
                Domain: "example.com",
                Contact: "admin@example.com"    
              },
              {
                Path: "/srv/www/somedomain/",
                Domain: "somedomain.com",
                Contact: "admin@somedomain.com"
              }
            ]
          }
          ]]>
          </content>
        </setting>
        </settings>
      </package>
    </packages>
  </sentinel>
  <sentinel name="ANOTHER-SENTINEL" credential="Standard">
    <!-- ..... -->
  </sentinel>
</sentinels>

Voici ce qu’elle décrit :

  • Nous avons deux sentinelles “SENTINEL-NAME-DEMO” et “ANOTHER-SENTINEL »
  • Les deux sentinelles utilisent le même credential “Standard” (déclaré dans la section credentials).
  • Sur la première sentinelle est déployée deux packages :
    • “HWMonitor” : le package utilise le même credential que sa sentinelle (car non défini explicitement donc hérite du credential de sa sentinelle)
    • “DemoPackage” : ce package utilise le credential nommé “ControlHubAccess” et déclare les settings suivants :
      • IntSetting et StringSetting associés à des valeurs (numérique et string)
      • SettingXml et SettingJson associés à des contenus (XML et JSON)
      • Importe le groupes de settings nommé “GroupSettingsDemo” défini dans la section “settingsGroups”

Les sentinelles

Pour entrer dans le détail, vous allez déclarer dans la section “sentinels”, les sentinelles de votre Constellation que ce soit des sentinelles réelles ou virtuelles.

Pour cela, vous utiliser la balise “<sentinel>” qui comporte les attributs suivants :

  • “name” : le nom de la sentinelle (obligatoire et unique)
  • “credential” : le nom du credential (déclaré dans la section credentials) à utiliser pour l’authentification (obligatoire)

La section “<sentinel>” contient une collection de “<package>” rangée dans la balise “<packages>”. Chaque package peut-être réel ou virtuel.

Les packages

L’élément “<package>” contient les attributs suivants :

  • “name”: le nom de l’instance du package (obligatoire et unique)
  • “filename” (facultatif) : le nom du fichier du package à utiliser dans le repository (plus d’info)
  • “enable” (facultatif, par defaut true) : indique si le package est activé ou désactivé
  • “credential” (facultatif, utilise par défaut du credential de sa sentinelle) : spécifie le credential que le package va utiliser pour s’authentifier sur le serveur Constellation
  • “autostart” (facultatif, par defaut true) : indique si le package doit automatiquement démarrer sur sa sentinelle ou juste être déployé (et donc démarré manuellement)

Un package peut contenir ensuite trois sous sections :

  • “recoveryOptions” : définit les options de récupération du package (par défaut, la sentinelle utilise les options globales)
  • “settings” : définit les paramètres/variables de configuration d’un package
  • “groups” : définit les groupes dans lesquels le package sera abonné
Les options de récupérations

La balise est la même que la section globale.

Par exemple si on ne souhaite pas que le package redémarre en cas de crash, on peut écrire :

<package name="MonPackage" enable="true">
  <recoveryOptions restartAfterFailure="false" />
</package>

Les paramètres de configuration

Chaque package peut définir des paramètres de configuration au niveau du serveur Constellation. Cela vous permet de changer ces paramètres directement depuis la Constellation qui se chargera de redescendre ces paramètres sur vos packages.

Il y a deux types de settings :

  • Les “Setting Value” : il s’agit d’un couple clé/value
  • Les “Setting Content”  : il s’agit d’un setting dont la valeur peut être un XML ou JSON

Dans l’exemple plus haut, le package “DemoPackage” contient à la fois des settings de type “value” et de type “content”.

Vous pouvez également regrouper des settings dans les groupes afin de les partager entre plusieurs package grâce aux settingsGroups. Toujours dans l’exemple précédent, le package “DemoPackage” inclut le groupe “GroupSettingsDemo”, un groupe de settings décrit dans la section ”settingsGroups”.

Pour plus d’information sur les settings, consultez l’article sur l’exploitation des settings avec l’API .NET.

Les groupes

Comme vous le savez, un message peut être envoyé à un groupe dans lequel des packages réels ou virtuels peuvent s’abonner.

Il y a deux manières d’abonner un package à un groupe :

  • Soit par le package lui même en invoquant la méthode “SubscribeToMessage” via les différentes API Constellation misent à disposition
  • Soit dans la configuration du package au niveau du serveur Constellation

Cela vous permet d’avoir la main sur l’appartenance des packages aux groupes que vous pouvez administrer sans devoir modifier vos packages (virtuels ou non).

La section “groups” sur un package permet de définir ces liens. Par exemple :

<package name="MonPackage" enable="true">
  <groups>
    <group name="MonGroupeA" />
    <group name="MonGroupeB" />
  </groups>
</package>

Ici le package “MonPackage” est abonné aux groupes “MonGroupeA” et “MonGroupeB”. En cas de modification des affectations aux groupes, il faudra redémarrer le package soit via vos applications en utilisant les API du hub de contrôle soit depuis la Console Constellation.

Section “settingsGroups”

Vous pouvez grouper des settings (Content ou Value) dans des groupes au niveau du serveur et importer ces groupes dans les settings de vos packages ou dans d’autres groupes.

Par exemple, créons un groupe pour “HWMonitorSettings” qui contient le setting “Interval” :

<settingsGroups>
  <group name="HWMonitorSettings">
    <settings>
      <setting key="Interval" value="500" />
    </settings>
  </group>
</settingsGroups>

Ainsi pour chaque instance du package “HWMonitor”, vous pouvez importer le groupe “HWMonitorSettings” afin de centraliser la configuration de ce package :

<package name="HWMonitor">
  <settings>
    <import>
      <settingGroup groupName="HWMonitorSettings" />
    </import>
  </settings>
</package>

Vous pouvez importer des groupes dans des groupes sans limite.

C’est toujours la valeur du setting la plus proche du package qui gagne (surcharge).

Bien entendu, vous pouvez créer autant de groupe que vous voulez et chaque groupe peut contenir des SettingValue ou des SettingContent :

<settingsGroups>
  <group name="test">
    <settings>
      <setting key="Demo1" value="Seb" />
      <setting key="Demo2" value="123" />
    </settings>
  </group>
  <group name="test2">
    <settings>
      <import>
        <settingGroup groupName="common" />
      </import>
      <setting key="Demo1" value="Sebastien" />
      <setting key="Demo2" value="2015" />
    </settings>
  </group>
  <group name="common">
    <settings>
      <setting key="MyStringSetting" value="This is a string" />
      <setting key="MyBoolSetting" value="true" />
      <setting key="MyXmlDocument">
        <content>
          <note date="09-02-2016">
            <to>Tove</to>
            <from>Jani</from>
            <heading>Reminder</heading>
            <body>Don't forget me this weekend!</body>
          </note>
        </content>
      </setting>
      <setting key="MyJsonObject">
        <content>
          <![CDATA[
        {
          "Number": 123,
          "String" : "This is a test (local)",
          "Boolean": true
        }
        ]]>
        </content>
      </setting>
    </settings>
  </group>
</settingsGroups>

Pour bien comprendre, imaginez le package suivant :

<package name="DemoPackage">
  <settings>
    <import>
      <settingGroup groupName="test" />
      <settingGroup groupName="test2" />
    </import>
    <setting key="numberTest" value="42" />
    <setting key="Demo1" value="It’me" />
  </settings>
</package>

Ici cette instance du package “DemoPackage” définie au niveau du serveur (= sans prendre en compte les settings déclarés dans le fichier local et le manifeste) 7 settings :

  • numberTest = 42 (définit dans les settings du package)
  • Demo1 = “It’s me” (définit dans les settings du package, cette valeur écrase celle des groupes importés)
  • Demo2 = 2015 (définit par le groupe “test2”. Cette valeur écrase la valeur du groupe “test”, car le groupe “test2” est importé APRES le groupe “test”)
  • MyStringSetting, MyBoolSetting, MyXmlDocument et MyJsonObject définies par le groupe “common” (groupe importé dans le groupe “test2” lui même importé sur le package “DemoPackage”).

Section “credentials”

Comme évoqué dans l’article lié à la sécurité, tous les appels (http) au serveur Constellation doivent être authentifiés en utilisant une clé d’accès que l’on nomme “AccessKey”.

Ces clé d’accès sont liés à des credentials.

Dans la section “credentials” nous allons donc définir les différents credentials ainsi que les différentes autorisations et droits sur ces credentials.

Chaque credential comporte obligatoirement deux propriétés :

  • Le nom (unique) du credential
  • L’AccessKey

Ainsi que les propriétés suivantes :

  • “enable” (true par défaut) : indique si le credential est activé ou désactivé
  • “enableControlHub” (false par défaut) : indique si le credential peut se connecter sur le hub de contrôle (pour l’administration de la Constellation)
  • “enableManagementAPI” (false par défaut) : indique si le credential peut se connecter à l’API de Management (pour l’édition de la configuration)
  • “enableDeveloperAccess” (false par défaut) : indique si le credential peut utiliser la sentinelle virtuelle “Developer” pour debugger des packages (utilisé par le SDK Visual Studio)

Par exemple :

<credentials>
  <credential name="Standard" accessKey="fb1af70a46057dbf4f2ff3f43b6ec0c544b22749" />
  <credential name="Administrator" accessKey="b363d6ccb86ef1418a72f9fea4b96975d8a1f2c7" enableControlHub="true" enableDeveloperAccess="true" enableManagementAPI="true" />
</credentials>

Vous pouvez ensuite définir des autorisations particulières sur un credential pour l’envoi de message, l’abonnement aux groupes de message ou encore l’interrogation de StateObject.

Pour cela il existe trois sous-sections :

  • “stateObjects” : autorisations spécifiques pour l’interrogation (Request ou Subscribe) des StateObjects
  • “messages” : autorisations spécifiques pour l’envoi de messages
  • “groups” : autorisations spécifiques pour l’abonnement aux groupes

Les autorisations sur l’interrogation des StateObjects

Par défaut un credential actif (enable=true) peut interroger (Request ou Subscribe) tous les StateObjects de votre Constellation sans restriction.

Pour modifier ce comportement vous pouvez utiliser les autorisation sur les StateObjects.

Par exemple :

<credential name="Standard" accessKey="fb1af70a46057dbf4f2ff3f43b6ec0c544b22749">
  <authorizations>
    <stateObjects defaultAuthorization="Deny">
      <authorization id="Paradox" authorization="Allow" packageName="Paradox" />
      <authorization id="MonPC" authorization="Allow" sentinelName="PC-SEB" />
      <authorization id="LesCPU" authorization="Allow" packageName="HWMonitor" name="/intelcpu/load/0" />
      <authorization id="ServerRAM" authorization="Allow" sentinelName="SERVER" packageName="HWMonitor" name="/ram/load" />
    </stateObjects>
  </authorizations>
</credential>

Ici le credential “Standard” ne pourra pas interroger les StateObjects de la Constellation (defaultAuthorization = Deny) sauf pour les exceptions suivantes :

  • Les StateObjects produits par le(s) instance(s) du package “Paradox”
  • Les StateObjects produits par les packages (quel qu’il soit) de la sentinelle “PC-SEB”
  • Les StateObjects nommés “/intelcpu/load/0” et produits par le package “HWMonitor” peu importe la sentinelle
  • Le StateObject nommé “/ram/load” produit par le package “HWMonitor” sur la sentinelle “SERVER”

Vous devez donc définir l’autorisation par défaut (defaultAuthorization) et optionnellement ajouter une ou plusieurs exceptions avec l’élément <authorization> dont les attributs sont les suivants :

  • “id” (obligatoire) : identifiant unique de l’autorisation
  • “authorization” (facultatif – Allow par défaut) : type de l’exception (Allow ou Deny)
  • “sentinelName” (facultatif – * par défaut) : sentinelle producteur du StateObject
  • “packageName” (facultatif – * par défaut) : package producteur du StateObject
  • “name” (facultatif – * par défaut) :  nom du StateObject

Les autorisations sur l’envoi de messages

Par défaut un credential actif (enable=true) peut envoyer un message à n’importe quel scope dans votre Constellation sans restriction.

Par exemple :

<credential name="Standard" accessKey="fb1af70a46057dbf4f2ff3f43b6ec0c544b22749">
  <authorizations>
    <messages defaultAuthorization="Deny">
      <authorization id="GroupA" authorization="Allow" scope="Group" args="A" />
      <authorization id="DemoSeb" authorization="Allow" scope="Package" args="DemoPackage" />
      <authorization id="TemperatureNest" authorization="Allow" scope="Package" args="Nest" messageKey="SetTargetTemperature"  />
    </messages>
  </authorizations>
</credential>

Ici le credential “Standard” ne pourra pas envoyer de message dans la Constellation (defaultAuthorization = Deny) sauf pour les exceptions suivantes :

  • Messages envoyés au groupe “A”
  • Messages envoyés au package “DemoPackage”
  • Message “SetTargetTemperature” envoyé au package “Nest”

Vous devez donc définir l’autorisation par défaut (defaultAuthorization) et optionnellement ajouter une ou plusieurs exceptions avec l’élément <authorization> dont les attributs sont les suivants :

  • “id” (obligatoire) : identifiant unique de l’autorisation
  • “scope” (obligatoire) : type de scope pour le message (All, Group, Package ou Sentinel)
  • “authorization” (facultatif – Allow par défaut) : type de l’exception (Allow ou Deny)
  • “args” (facultatif) : les arguments du scope
  • “messageKey” (facultatif) :  la clé du message

Les autorisation sur l’abonnement aux groupes

Par défaut un credential actif (enable=true) peut s’abonner à n’importe quel groupe sans restriction.

Par exemple :

<credential name="Standard" accessKey="fb1af70a46057dbf4f2ff3f43b6ec0c544b22749">
  <authorizations>
    <groups defaultAuthorization="Deny">
      <authorization groupName="A" />
    </groups>
  </authorizations>
</credential>

Ici le credential “Standard” ne pourra pas s’abonner à des groupes (defaultAuthorization = Deny) à l’exception du groupe “A”. Les attributs sont les suivants :

  • “groupName” (obligatoire) : le nom du groupe
  • “authorization” (facultatif – Allow par défaut) : type de l’exception (Allow ou Deny)

The post Le fichier de configuration appeared first on Constellation.

]]> https://developer.myconstellation.io/constellation-platform/constellation-server/fichier-de-configuration/feed/ 0 Gérer les connexions Constellation https://developer.myconstellation.io/constellation-platform/constellation-sdk/gerer-connexions-constellation/ https://developer.myconstellation.io/constellation-platform/constellation-sdk/gerer-connexions-constellation/#respond Tue, 09 Aug 2016 12:55:22 +0000 https://developer.myconstellation.io/?p=2159 Pour gérer les connexions Constellation dans Visual Studio, cliquez sur le bouton “Manage Constellation Servers” dans la barre d’outils Constellation : Vous pourrez alors ajouter, supprimer ou éditer des connexions vers vos serveurs Constellation : Le bouton “Test” permet de

The post Gérer les connexions Constellation appeared first on Constellation.

]]> Pour gérer les connexions Constellation dans Visual Studio, cliquez sur le bouton “Manage Constellation Servers” dans la barre d’outils Constellation :

Manage Constellation Servers

Vous pourrez alors ajouter, supprimer ou éditer des connexions vers vos serveurs Constellation :

Manage Constellation Servers

Le bouton “Test” permet de tester la connectivité.

N’oubliez pas de sélectionner dans le liste déroulante en haut de la fenêtre, le serveur Constellation à utiliser pour le debug des packages.

The post Gérer les connexions Constellation appeared first on Constellation.

]]> https://developer.myconstellation.io/constellation-platform/constellation-sdk/gerer-connexions-constellation/feed/ 0 Gérer les credentials avec la Console Constellation https://developer.myconstellation.io/constellation-platform/constellation-console/gerer-credentials-avec-la-console-constellation/ https://developer.myconstellation.io/constellation-platform/constellation-console/gerer-credentials-avec-la-console-constellation/#respond Fri, 19 Aug 2016 14:56:33 +0000 https://developer.myconstellation.io/?p=2368 Dans le menu principal de gauche, sous la section “Server Management”, rendez-vous sur la page “Manage Credentials” : Vous obtiendrez sur la page la liste des credentials déclarés sur votre Constellation avec leurs clés d’accès associées, utilisées pour authentifier toutes

The post Gérer les credentials avec la Console Constellation appeared first on Constellation.

]]> Dans le menu principal de gauche, sous la section “Server Management”, rendez-vous sur la page “Manage Credentials” :

image

Vous obtiendrez sur la page la liste des credentials déclarés sur votre Constellation avec leurs clés d’accès associées, utilisées pour authentifier toutes requêtes vers votre Constellation.

N’hésitez pas à lire ou relire la page dédiée aux concepts de Credential / AccessKey et Authorization avant de poursuivre !

Pour chaque credential vous avez la possibilité d’activer ou désactiver la clé d’accès en cliquant sur le bouton “Disable” ou “Enable” :

imageimage

Attention ces actions sont immédiates. Si vous désactivez une clé d’accès actuellement utilisée par un ou plusieurs packages, leurs accès seront immédiatement révoqués.

Vous pouvez également accéder au menu contextuel pour éditer le crédential, ses autorisation ou le supprimer.

image

Ajouter ou éditer un credential

Si vous cliquez sur le bouton “Add credential” ou “Edit” du menu contextuel d’une sentinelle, vous obtiendrez la fenêtre suivante :

image

Note : dans le cas d’une édition vous ne pourrez pas éditer le nom du credential.

Vous pouvez cependant éditer en toute circonstance la clé d’accès et même utiliser un générateur login/password comme expliqué ici.

image

Pour rappel, chaque credential porte les propriétés suivantes :

  • Enable : indique si le credential est activé ou désactivé
  • EnableControlHub : indique si le credential peut se connecter sur le hub de contrôle (pour l’administration de la Constellation)
  • EnableManagementAPI : indique si le credential peut se connecter à l’API de Management (pour l’édition de la configuration)
  • EnableDeveloperAccess : indique si le credential peut utiliser la sentinelle virtuelle “Developer” pour debugger des packages (utilisé par le SDK Visual Studio)

Gérer les autorisations

En cliquant sur “Edit Authorizations” vous pourrez gérer les autorisations d’un credential pour limiter l’envoi de message, les StateObjects autorisés à consommer et les groupes.

image

The post Gérer les credentials avec la Console Constellation appeared first on Constellation.

]]> https://developer.myconstellation.io/constellation-platform/constellation-console/gerer-credentials-avec-la-console-constellation/feed/ 0 La sécurité : AccessKey, Credential et Authorization https://developer.myconstellation.io/concepts/securite-accesskey-credential-authorization/ https://developer.myconstellation.io/concepts/securite-accesskey-credential-authorization/#respond Tue, 09 Aug 2016 12:30:20 +0000 https://developer.myconstellation.io/?p=2143 Tous les appels (HTTP) au serveur Constellation doivent être authentifiés. Pour cela, nous utilisons une clé d’accès que l’on nomme “AccessKey”. L’AccessKey Chaque requête au serveur Constellation comporte soit dans les paramètres de l’URL (querystring) soit dans les entêtes (headers)

The post La sécurité : AccessKey, Credential et Authorization appeared first on Constellation.

]]> Tous les appels (HTTP) au serveur Constellation doivent être authentifiés. Pour cela, nous utilisons une clé d’accès que l’on nomme “AccessKey”.

L’AccessKey

Chaque requête au serveur Constellation comporte soit dans les paramètres de l’URL (querystring) soit dans les entêtes (headers) HTTP trois informations :

  • SentinelName : le nom de la sentinelle
  • PackageName : le nom du package
  • AccessKey : la clé d’accès

Les paramètres “SentinelName” et “PackageName” permettent d’identifier le package qui réalise la requête car un package (virtuel ou non) est toujours associé à une sentinelle (virtuelle ou non).

En fait le couple “SentinelName/PackageName” forme l’identifiant unique du package (nommé instance de package) dans la Constellation et l’AccessKey peut être comparé au “mot de passe”.

Une sentinelle (virtuelle ou non) déclarée dans la configuration de votre Constellation doit obligatoirement être associée à une clé d’accès et les packages (virtuels ou non) déclarés sur une sentinelle utilisent implicitement la même clé d’accès ou bien peuvent redéfinir une clé spécifique.

Il y a quelques cas particuliers :

  • Lorsqu’une sentinelle produit des logs, son “PackageName” est “Sentinel”
  • Pour les consommateurs ou contrôleurs, le “SentinelName” est soit “Consumer” ou soit “Controller” et le “PackageName” sert de “FriendlyName” pour les logs
  • Dans le cas de l’utilisation de la fonction de “Debug on Constellation” depuis le SDK VisualStudio, le “SentinelName” est “Developer”

Les Credentials

Dans le fichier de configuration de votre Constellation, on ne déclare pas l’AccessKey directement sur une sentinelle ou un package.

En effet une sentinelle est associée à un credential et un package utilise implicitement le même credential que sa sentinelle ou bien redéfini son propre credential.

Un credential comporte obligatoirement deux propriétés :

  • Le nom (unique) du credential
  • L’AccessKey

Pour authentifier une requête, le serveur Constellation regardera alors si l’AccessKey de la requête correspond bien à celle déclarée pour le credential utilisé par le couple Sentinel/Package.

Un credential peut définir les propriétés suivantes :

  • Enable : indique si le credential est activé ou désactivé
  • EnableControlHub : indique si le credential peut se connecter sur le hub de contrôle (pour l’administration de la Constellation)
  • EnableManagementAPI : indique si le credential peut se connecter à l’API de Management (pour l’édition de la configuration)
  • EnableDeveloperAccess : indique si le credential peut utiliser la sentinelle virtuelle “Developer” pour debugger des packages (utilisé par le SDK Visual Studio)

Vous pouvez gérer les credentials depuis la Console Constellation ou depuis le fichier de configuration.

Manage Credential

Login et AccessKey

L’AccessKey doit être une chaîne de caractère assez longue et sera utilisée un peu comme un mot de passe pour l’authentification.

Cependant il est assez compliqué de retenir un AccessKey surtout comparé à un couple “login / password” que nous utilisons au quotidien.

C’est pourquoi la Console Constellation, les installeurs Constellation ou encore le SDK Constellation propose d’utiliser un login/password pour générer un AccessKey.

La formule est très simple : AccessKey = sha1(login + password). En clair une clé d’accès peut être obtenue par le hash SHA1 de la concaténation du login avec un mot de passe.

Par exemple, si mon login est “admin” et que mon mot de passe est “P@ssw0rd” alors ma clé d’accès (AccessKey) sera a5761adf00e4060f05fab7017b32905cc9e5d540 (= le hash SHA1 de “adminP@ssw0rd”).

Les Authorizations

Par défaut un credential actif (enable=true) à le droit d’interroger (Request ou Subscribe) tous les StateObjects de votre Constellation sans restriction ou d’envoyer des messages à n’importe quel scope ou encore de s’abonner n’importe quel groupe.

Imaginez maintenant que vous réalisez une page Web en Javascript connectée à votre Constellation pour afficher les valeurs de quelques StateObjects en temps réel ou encore pour envoyer des messages pour contrôler certains dispositifs.

Dans le cas présent, si il s’agit d’une page JavaScript, le code est “client-side”, donc n’importe quelle personne ayant accès à cette page pourra visualiser le code source et récupérer l’AccessKey utilisée.

En clair si vous développez un petit morceau de Javscript pour afficher en temps réel la consommation de votre CPU (StateObject produit par le package HWMonitor par exemple) sur votre site Web, n’importe qui pourrait récupérer votre clé d’accès et suivre en temps réel le statut de votre alarme, votre courbe de poids, la température de votre chambre, le volume de votre ampli, etc… Ou pire encore, envoyer différents messages dans votre Constellation pour éteindre des machines, allumer des lumières, ouvrir la porte de garage, augmenter le chauffage, etc…

Un concept « d’autorisation” a été introduite dans la version 1.8 de Constellation pour restreindre les droits sur une clé d’accès (AccessKey) sur les éléments suivants :

  • L’interrogation des StateObjects
  • L’envoi de message (invocation des MessageCallback)
  • L’abonnement à des groupes de message

De ce fait, si vous souhaitez afficher par exemple la consommation de votre CPU de telle machine, vous allez créer un credential qui n’aura que le droit (autorisation) de visualiser ce StateObject ni plus ni moins.

Plus d’information, consultez l’article dédié à la configuration des autorisations.

The post La sécurité : AccessKey, Credential et Authorization appeared first on Constellation.

]]> https://developer.myconstellation.io/concepts/securite-accesskey-credential-authorization/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 Migrer Constellation 1.7 vers Constellation 1.8 https://developer.myconstellation.io/constellation-platform/constellation-server/migrer-constellation-1-7-vers-constellation-1-8/ https://developer.myconstellation.io/constellation-platform/constellation-server/migrer-constellation-1-7-vers-constellation-1-8/#respond Mon, 14 Mar 2016 09:37:21 +0000 https://developer.myconstellation.io/?p=1082 Si vous avez une Constellation 1.7 déployée vous avez deux manière de migrer vers la 1.8 : Tout désinstaller et ré-installer la nouvelle installation Migrer l’existant Pour la première solution, il suffit simplement de tout désinstaller depuis l’ajout et suppression

The post Migrer Constellation 1.7 vers Constellation 1.8 appeared first on Constellation.

]]> Si vous avez une Constellation 1.7 déployée vous avez deux manière de migrer vers la 1.8 :

  1. Tout désinstaller et ré-installer la nouvelle installation
  2. Migrer l’existant

Pour la première solution, il suffit simplement de tout désinstaller depuis l’ajout et suppression de programmes Windows  sans oublier de supprimer le répertoire du serveur. Puis en suivant le guide de démarrage, réinstaller la nouvelle version 1.8 en partant de zéro.

Bien entendu cette solution n’est valable que si votre Constellation n’est pas ou peu utilisée. Autrement si souhaitez migrer l’existant vers la nouvelle version 1.8 suivez ce guide.

Plan de migration

Pour mettre à jour une Constellation 1.7 vers la 1.8, voici le plan des étapes à réaliser :

  1. Mise à jour du serveur
  2. Mise à jour de la Console
  3. Mise à jour des pages Web (ou assimilés) exploitants l’API JavaScript
  4. Mise à jour du SDK
  5. Mise à jour des sentinelles
  6. Mise à jour des packages

Mise à jour du serveur

La première étape consiste à mettre à jour le serveur de façon à migrer votre Constellation 1.7 en 1.8.

L’installeur tout-en-un “Platform” ou l’installeur propre au serveur réalise la migration automatiquement (en tenant compte de votre configuration actuelle).

Prenons l’exemple d’une installation avec le serveur Constellation 1.7.6 déployé, la Console (nommée “Control Center” dans la version 1.7) et une sentinelle 1.7 sur laquelle est déployé le package HWMonitor également en version 1.7 :

imageimage

Pour mettre à jour le serveur, la console et la sentinelle en une seule fois, je vous recommande de lancer l’installeur tout-en-un “Platform”.

L’installeur vous informera alors que ces trois composants seront mis à jour vers la version 1.8 :

image image

A la fin de l’installation, dans les services Windows vous pourrez constater que les services du serveur et de la sentinelle ont bien été mis à jour :

image

Vous pouvez également vous rendre sur l’URI de votre Constellation pour vérifier que le serveur Constellation 1.8 est bien démarré.

image

Notez que toute votre configuration est restée échangé (clé d’accès, sentinelle, configuration des  packages, etc…).

Mise à jour de la Console

Avec l’installeur “Platform” ci-dessus, la nouvelle Console (anciennement “Control Center”) est bien déployée.

Il vous suffit de réactualiser la page et vous retrouverez votre sentinelle (elle aussi migrée en 1.8 via l’installeur Plateform) et votre package HWMonitor (toujours fonctionnel dans votre nouvelle Constellation) :

imageimage

Activer la page de login et l’accès à l’API de Management

Comme pour le serveur, l’installeur garde votre configuration actuelle lors de la mise à jour vers Constellation 1.8.

De ce fait, la configuration de la Console se trouve toujours dans le fichier “config.js” à la racine du répertoire d’installation de la Console.

Jusqu’à la version 1.7, ce fichier devait contenir une clé d’accès avec l’autorisation d’accès au hub de contrôle. Depuis la version 1.8, vous n’êtes plus obligé de définir en dur la clé d’accès dans ce fichier. Si la variable est vide, la console proposera alors une page de login.

L’idée est donc d’utiliser un couple login/password qu’on “hashera” pour l’utiliser en tant que clé d’accès (il est plus simple de mémoriser un login/password qu’une longue clé d’accès). Nous allons donc changer la clé d’accès (ou en créer une nouvelle) en utilisant ce procédé.

De plus dans Constellation 1.8, une nouvelle API est apparue pour l’administration du serveur : l’API de Management. Il vous faudra ajouter l’autorisation d’y accéder sur votre Access Key :

image

Etape 1 : créez une Access Key à partir d’un login/password

Rendez-vous sur un outil de création de hash SHA1 tel que http://www.sha1.fr/ et créez un hash SHA1 du login concaténé avec votre mot de page.

Par exemple, si mon login est “seb” et mon mot de passe “Password”, je crée le hash de “sebPassword” ce qui me retourne “567841343531a170817ac02941d644df12d7d3ae”.

Etape 2 : déclarez votre nouveau credential

Editez le fichier de configuration du serveur (“Constellation.Server.exe.config” dans le répertoire d’installation du serveur) et ajoutez dans la section <credentials>:

<credential name="MyAdminAccess" accessKey="567841343531a170817ac02941d644df12d7d3ae" enableControlHub="true" enableManagementAPI="true" enableDeveloperAccess="true"/>

Le nom du credential n’a peu d’importance (il ne sert que pour votre organisation), l’AccessKey est le hash SHA1 généré à partir de notre login & password, et n’oubliez pas d’autoriser l’accès au Control Hub (enableControlHub) et également à l’API de management (enableManagementAPI).

SI vous souhaitez également utiliser cette clé d’accès pour débugger vos packages depuis le SDK Visual Studio, activez l’accès développeur (enableDeveloperAccess).

Depuis la Console, cliquez sur le bouton “Reload Config” pour recharger la configuration avec votre nouveau credential :

image

Etape 3 : mettez à jour le fichier de configuration de la Console

Editez maintenant le fichier de configuration de la Console (fichier “config.js” dans le répertoire d’installation de la config).

Commencez par supprimer l’ajout de l’ancien menu en retirant les lignes :

$(document).one('pagebeforecreate', function() {
    $.get("menu.html", function(data) {
        $.mobile.pageContainer.prepend(data);
        $("#nav-panel").panel();
        $("#menu-list").listview();
    });
});

Puis effacer le contenu de la variable “constellationAccessKey” pour forcer l’affichage de la page de login.

Au final, le contenu de votre fichier “config.js” doit être (en reprenant soin de spécifier l’URI de votre serveur Constellation en fonction de votre installation) :

// Constellation Server URI
var constellationUri = "http://localhost:8088";
// Constellation AccessKey (w/ enableControlHub)
var constellationAccessKey = ""; // leave empty to enable the login page

Vous pouvez ensuite rafraichir votre page (Ctrl+F5 de préférence), la page de login s’affichera car aucune clé d’accès n’est définie dans le fichier “config.js”.

image

Pour vous connecter, utilisez votre login/password afin d’accéder à la console.

SI vous avez activé l’accès à l’API de Management (enableManagementAPI), vous aurez un nouveau menu “Server Management” ajoutant des fonctionnalités pour la gestion du serveur, comme l’édition du fichier de configuration de serveur directement depuis la Console :

image

Optionnel : auto-hébergement de la Console par le serveur Constellation

Depuis la version 1.8, le serveur Constellation est capable d’héberger des pages Web ce qui permet d’héberger la Console Constellation sans avoir besoin d’installer un serveur Web type IIS, Apache ou autre.

Pour cela, vous devez simplement éditer la configuration du serveur pour activer le “File Server” :

<fileServer enable="true" physicalPath="..\Console\" localhostOnly="true" path="/WebConsole"/>

Passez l’attribut “enable” à true, indiquez le chemin physique du répertoire d’installation de la Console (par exemple : c:\inetpub\wwwroot), si vous voulez limiter ou non la console en local et l’URL relatif de la console (par default /webconsole/).

Pour prendre en compte ces modifications vous devez redémarrer le serveur Constellation (dans la MMC des Services Windows).

Aussi dans le fichier “config.js” de la Console, la variable “constellationUri” doit être vide pour indiquer que l’URI du serveur et la même que la console.

Mise à jour des pages Web (ou assimilés) exploitants l’API JavaScript

Depuis la version 1.8, plusieurs modifications ont été apporté au hub de contrôle et la 1.8 se voit doter d’un nouveau hub : le hub de consommation (Consumer Hub).

Historiquement le hub de contrôle (Control Hub) permettait à la fois de contrôler la Constellation mais également d’interroger les StateObjects, envoyer et recevoir des messages, etc… car c’était le seul hub disponible pour le Web (Javascript).

Avec Constellation 1.8, le hub de contrôle est exclusivement dédié au contrôle de la Constellation (gestion des packages, récupération des statuts, des logs, reload de la configuration, etc…). Toutes les méthodes liées aux messages et aux StateObjects ont été déplacé dans un nouveau hub : le hub de consommation.

Une fois votre serveur migré en 1.8, toutes les pages Web (ou assimilés type applications Tizen ou Cordova qui utilisent l’API Javascript) ne fonctionneront plus tant que vous n’aurez pas migrés les API Javascript 1.8

Etape 1 : supprimez les anciennes librairies

Tout d’abord, commencez par désinstaller les packages Nuget “Constellation.CommonJS” (API Constellation JS) et “Constellation.CommonNG” (API Constellation AngularJS) car il s’agit des anciens packages pour Constellation 1.7.

image

Si vous n’avez pas utilisé Nuget pour installer ces librairies, supprimez manuellement les fichier “Constellation.js” et “ngConstellation.js”.

Etape 2 :  installez les nouvelles librairies

Depuis Nuget, installez le ou les nouveaux packages :

  • “Constellation.Javascript” pour la libraire Constellation pour Javascript
  • “Constellation.Angular” pour la librairie Constellation pour AngularJS (sur couche)

image

Dans vos pages HTML, changez les liens vers les nouveaux fichiers Javascript portant désormais le numéro de version de l’API.

Remplacez :

<script type="text/javascript" src="/constellation/Scripts/Constellation.js"></script>
<script type="text/javascript" src="/constellation/Scripts/ngConstellation.js"></script>

par :

<script type="text/javascript" src="/constellation/Scripts/Constellation-1.8.0.js"></script>
<script type="text/javascript" src="/constellation/Scripts/ngConstellation-1.8.0.js"></script>

Etape 3 : modification dans l’API

Pour l’API Javascript (Constellaiton.Javascript), la méthode “createConstellationClient” est remplacée par “createConstellationConsumer” pour l’accès au hub de consommation ou “createConstellationController” pour l’accès au hub de contrôle.

Pour l’API AngularJS (Constellation.Angular), le module “constellation” à injecter dans votre contrôleur est remplacé par “constellationConsumer” et “constellationController” pour les deux hubs. La méthode “intializeClient” reste inchangée et est disponible sur les deux modules.

Mise à jour du SDK

Lancez tout simplement l’installeur tout en un “Platform” ou l’installeur du SDK.

Il procèdera à l’installation du VSIX pour Visual Studio 2012, 2013 et 2015.

image

Mise à jour des sentinelles

Les sentinelles 1.7 peuvent fonctionner sans aucun soucis dans une Constellation 1.8 (à l’inverse, une sentinelle 1.8 ne peut pas se connecter à une Constellation 1.7).

image

Cependant, afin de bénéficier des nouveautés de la 1.8, il est conseillé de mettre à jour ses sentinelles.

Pour cela, vous devez soit lancer l’installeur “Plateform” si vous être sur la même machine que votre serveur Constellation, ou lancer l’installeur dédié à la sentinelle Service ou UI :

image

Mise à jour des packages

Comme nous l’avons vu avec les API Javascript, les requêtes (Request) et abonnements (Subscribe) sur les StateObjects et l’envoi et la réception de messages ne sont plus disponibles sur le hub de contrôle.

Ainsi les packages .NET ou Python qui utilisaient ces fonctionnalités comme les [StateObjectLink] ne pourront plus fonctionner une fois votre serveur Constellation migré en 1.8. Vous devez donc impérativement mettre à jour la librairie Constellation 1.8 pour ces packages.

Autrement, pour tous les packages Constellation 1.7.x qui n’exploitent pas les StateObjects (hormis le Push) et n’utilisent pas les fonctionnalités du hub de contrôle, pourront fonctionner sans problème sur une Constellation 1.8.

image

Au démarrage vous aurez simplement un warning (et seulement si la sentinelle est en version 1.8.x) :

image

Pensez toutefois à mettre à jour la libraire cliente Constellation pour bénéficier des nouveautés de la 1.8.

Mise à jour du package Constellation 1.8

Comme pour les API Javascript, le package NuGet de l’API .NET a changé d’identifiant. Vous devez donc commencer par désinstaller le package Constellation 1.7 nommé “Constellation.Common” :

image

Puis, toujours depuis NuGet, installez le package “Constellation” 1.8 :

image

Les breaking changes

Une fois vos projets migrés sur la nouvelle librairie 1.8, il y a plusieurs “breaking changes” que vous devrez corriger pour pouvoir compiler votre package. Retrouvez ci-dessous la liste des changements bloquants (et non la liste des nouveautés de l’API 1.8).

Le Namespace

Premièrement l’espace de nom “Constellation.Host” devient “Constellation.Package”. Vous devez donc changer les différents “using” de votre code.

using Constellation.Package;

Le PackageManifest

L’attribut « RestoreStateObjects » est renommé en « RequestLastStateObjectsOnStart » dans le manifest (PackageInfo.xml) de votre package. Il permet d’indiquer au serveur Constellation de vous envoyer les derniers StateObjects du package quand il démarre (avant la purge).

De même, l’évènement « RestoreStateObjects » est lui renommé en « LastStateObjectsReceived » sur la classe statique “PackageHost” :

PackageHost.LastStateObjectsReceived += (s, e) =>
{
     PackageHost.WriteInfo("Recu {0} StateObject(s)", e.StateObjects.Count);
};

Les Settings

La version 1.7 de Constellation a introduit les “SettingContents” permettant de mettre du XML dans la déclaration d’un setting. Il fallait alors utiliser la méthode « GetSettingContent<TConfigurationSection> » où TConfigurationSection devait être une ConfigurationSection.

En 1.8, cette méthode a été renommé en « GetSettingAsConfigurationSection<TConfigurationSection>« .

De plus de nouvelles méthodes sont apparues :

MaSection section = PackageHost.GetSettingAsConfigurationSection<MaSection>("MaSection");
dynamic configJson = PackageHost.GetSettingAsJsonObject("MonObjectJson");
MonObject objetJson = PackageHost.GetSettingAsJsonObject<MonObject>("MonObjectJson");
XmlDocument xml = PackageHost.GetSettingAsXmlDocument("MonXml");

Lorsque le package est démarré en mode “debug”, depuis Visual Studio, les SettingValues sont lues depuis les <appSettings> de votre App.config. Avec la 1.8, les <appSettings> sont abandonnés. Vous devez définir une section “constellationSettings” qui prend la même structure que les settings sur le serveur avec le support des <content>.

Pour plus d’information, consultez la page dédiée à la configuration des packages.

Les StateObjects
  • Désormais la propriété “Metadatas” d’un StateObject est dictionnaire de String (clé) / Object (valeur) (et non plus String/String).
  • La classe  StateObject est maintenant dans le namespace racine “Constellation”
  • Les classes StateObjectNotifier et StateObjectCollectionNotifier ainsi que l’attribut StateObjectLink et les EventsArgs associés appartiennent au namespace “Constellation.Package”
  • Les notions  des StateObjectsLink & Notifier (méthodes et events) sont déplacés dans le PackageHost et non plus dans le ControlManager.

Il n’y a donc plus besoin de définir l’attribut “EnableControlHub” à true pour ajouter des StateObjectsLinks dans vos packages.

Les messages

La méthode PackageHost.AttachMessageCallbacks est renommée en PackageHost.RegisterMessageCallback. A noter qu’elle est (toujours) implicitement appelée au démarrage du package sur votre package “PackageBase”.

Les méthodes PackageHost.CreateScope & PackageHost.CreateSaga ont été supprimées. Pour créer un scope vous devez directement utiliser la classe MessageScope.

Par exemple :

MessageScope scope = MessageScope.Create("MonPackageCible");
MessageScope scope2 = MessageScope.Create(MessageScope.ScopeType.Group, "GroupA", "GroupB");

Breaking change : ScopeType.Groups est devenu ScopeType.Group (au singulier)

Pour récupérer le proxy dynamic, vous devez utiliser la méthode d’extension “GetProxy” et non plus la propriété “Proxy” :

dynamic proxy = scope.GetProxy();

Par exemple, pour envoyer le message “Demo” au package “DemoPackage” :

MessageScope.Create("DemoPackage").GetProxy().Demo("Un argument ici !");

Pour envoyer ce message dans une saga, vous devez attacher à un callback de retour avec la méthode d’extension “OnSagaResponse” :

MessageScope.Create("DemoPackage").OnSagaResponse(reponse =>
{
     PackageHost.WriteInfo("Recu reponse de {0}", MessageContext.Current.Sender.FriendlyName);
}).GetProxy().Demo("Un argument ici !");

Par défaut, la variable de retour est un dynamic, mais vous pouvez aussi spécifier le type de retour :

MessageScope.Create("DemoPackage").OnSagaResponse<MonObject>(reponse =>
{
     // Reponse est de type MonObject
     PackageHost.WriteInfo("Recu reponse de {0}", MessageContext.Current.Sender.FriendlyName);
}).GetProxy().Demo("Un argument ici !");

Pour finir, il ne s’agit pas d’un breaking change mais d’une nouveauté : vous pouvez également envoyer un message dans une saga de façon “awaitable” :

Task<dynamic> reponse = MessageScope.Create("DemoPackage").GetProxy().Demo<MonObject>("Un argument ici !");

Retrouvez plus d’information sur l’envoi de message et les sagas sur cette page.

The post Migrer Constellation 1.7 vers Constellation 1.8 appeared first on Constellation.

]]> https://developer.myconstellation.io/constellation-platform/constellation-server/migrer-constellation-1-7-vers-constellation-1-8/feed/ 0