Développer un connecteur Testo Smart Connect
- Tipo non definito
Formation
Objectif
Ce guide explique comment développer un connecteur pour Immersive Hub à partir d'un exemple complet : l'accès aux données de capteurs Testo Smart Connect.

Il s'adresse aux intégrateurs et aux développeurs qui souhaitent raccorder leur propre API, protocole ou équipement au Hub.
Nous GraphicStream, avons essayé de mettre dans ce document nos pérégrinations mentales, nos études, et la manière dont nous avonsq travaillé pour réaliser ce connecteur. Le document est volontairement très verbeux : de nombreux rappels du fonctionnement du Hub et du modèle objet d'Immersive sont présents.
Testo fournit les capteurs et le service Smart Connect utilisés dans cet exemple.
Retrouvez le site officiel de Testo et la documentation de l'API Testo Smart Connect.
Charge au responsable métier s'occupant d'Immersive de créer les handles depuis l'Enhancer ou via les accès OData du serveur Immersive pour représenter les données et les moyens d'y accéder. Il renseigne, pour chaque Handle notamment son Path. Lorsqu'un consommateur demande cette donnée dans une session du Hub, le Path permet aux connecteurs de reconnaître les handles qu'ils peuvent prendre en charge. Le connecteur concerné assure l'accès à la donnée et le suivi de ses évolutions ; le Hub prépare les mises à jour pour les sessions intéressées. Nous reviendrons plus précisément sur ce principe un peu plus loin dans ce document.
Le projet fourni cible .NET 10. Il utilise les bibliothèques standard de .NET et le contrat partagé GraphicStream.Immersive.Hub.Abstractions, référencé par son package NuGet. Une fois compilé pour une version compatible du Hub, le connecteur Testo se déploie avec sa seule DLL.
Toutes les clés, identités de capteurs, numéros de série et désignations de sites présentés dans ce guide sont fictifs. La clé sk_testo_p_EXAMPLE_NOT_A_REAL_KEY ne donne aucun accès. Les exemples doivent être adaptés à votre compte.
In questo articolo
Comprendre les rôles et le parcours d'une donnée
Qui crée le handle et qui le prend en charge ?
L'utilisateur crée et configure les handles depuis l'Enhancer ou via les accès OData du serveur Immersive. Un handle représente une route d'accès à une donnée, par exemple la température courante d'un capteur. Son Path décrit comment joindre cette donnée.
La création du handle et sa demande au Hub sont deux étapes distinctes. Un consommateur, comme Beholder, ouvre une session auprès du Hub et lui transmet les handles dont il souhaite obtenir les valeurs et suivre les évolutions. Chaque handle transmis comporte un identifiant propre à cette session et son Path.
Un même Hub peut disposer de plusieurs connecteurs, par exemple Testo, OPC UA et Excel. Pour un Path qu'il ne prend pas encore en charge, le Hub sollicite ses connecteurs. Chacun examine le Path pour déterminer si le handle relève du protocole ou de la source de données qu'il sait gérer. Le connecteur qui accepte la prise en charge accède à la donnée et informe le Hub de ses évolutions, qu'il s'agisse de sa valeur, de son statut ou de sa date.
| Acteur ou objet | Rôle |
|---|---|
| Utilisateur, via l'Enhancer ou les accès OData du serveur | Crée et configure les handles, notamment leur Path. |
| Handle | Représente une route d'accès à une donnée. Son Path permet de reconnaître les moyens d'accès et de cibler la donnée. |
| Consommateur, par exemple Beholder | Ouvre une session auprès du Hub, y enregistre les handles utiles et récupère leurs mises à jour pour les exploiter ou les afficher. |
| Session du Hub | Associe les handles demandés à leurs identifiants pour ce consommateur et permet de lui restituer les changements qui le concernent. |
| Immersive Hub | Coordonne les sessions et les connecteurs ; conserve les valeurs connues et prépare les mises à jour destinées aux sessions intéressées. |
| Connecteur Testo | L'objet de ce tutoriel, notre développement vise à créer un connecteur qui reconnaît les Paths Testo, valide les adresses et assure la lecture ainsi que le suivi des données. |
| API Testo Smart Connect | Fournit les mesures et les informations sur les capteurs. |
Dans l'exemple Testo, le connecteur récupère un inventaire des capteurs accessibles au compte : leur UUID, leur nom, leur emplacement et les grandeurs disponibles. Cet inventaire permet, par exemple, de retrouver l'UUID du capteur « Salle A » pour renseigner le Path de son handle de température. Le connecteur ne crée pas les familles, les instances ou leurs handles dans le serveur Immersive : cette configuration se fait dans l'Enhancer ou via OData.
Cette organisation est présentée dans la documentation générale du Hub.
De la demande à l'affichage
Avant de demander des valeurs au Hub, on organise les équipements à superviser. Une famille (Equipment) regroupe les équipements de même nature, par exemple « Capteurs climatiques Testo ». Une instance (EquipmentInstance) représente un équipement concret de cette famille, par exemple « Capteur d'ambiance — Salle A ».
Les données à suivre sont décrites dans le modèle par des états (EquipmentState) associés à la famille ou à l'instance : température, humidité, batterie, etc. Ces états portent les Paths utilisés par le consommateur pour demander les handles correspondants au Hub. Une instance peut donc être associée à plusieurs handles, éventuellement pris en charge par des connecteurs différents. Dans cet exemple, le Path de température contient l'UUID Testo du capteur de la salle A.
La modélisation des familles, des instances et de leurs états sera détaillée dans un article dédié. Pour ce tutoriel, retenons la chaîne famille → instance → handles → Paths des données. Le Hub reçoit les handles demandés ; le connecteur Testo travaille sur leurs Paths sans avoir à charger ces objets métier.
- Préparer la supervision. Depuis l'Enhancer ou les accès OData du serveur Immersive, l'utilisateur définit la famille, ses instances et les handles associés. Pour la température de la salle A, le Path concret est par exemple
Testo://11111111-1111-4111-8111-111111111111/Temperature. - Ouvrir une session. Le consommateur, par exemple Beholder, ouvre une session auprès du Hub. L'identifiant de session retourné sert à identifier ses échanges suivants avec le Hub.
- Enregistrer les handles dans la session. Le consommateur transmet les couples identifiant/Path des données qu'il souhaite suivre. Il peut compléter cette liste par plusieurs demandes. Cet enregistrement exprime son intérêt pour ces données ; il ne garantit pas encore leur prise en charge par un connecteur ni la disponibilité d'une valeur.
- Réutiliser ou rechercher la prise en charge. Pour un Path déjà pris en charge, le Hub associe la session au suivi existant et lui prépare l'état courant connu. Sinon, il soumet le handle aux connecteurs disponibles. Chacun examine le Path pour déterminer s'il peut le gérer ; Testo reconnaît ici le préfixe
Testo://. Ce traitement peut se faire après la réception de la demande du consommateur. - Obtenir un premier état. Le connecteur compatible valide le Path et tente d'obtenir la donnée. Testo utilise ici son cache commun, alimenté par les collectes groupées. Le Hub restitue un premier état à la session, y compris lorsqu'aucun connecteur n'a pu prendre en charge le handle ou qu'aucune mesure n'est disponible. Le statut permet d'expliquer cette situation.
- Détecter les changements. Le connecteur suit la donnée selon son protocole : événements ou lectures périodiques. Testo effectue ses collectes groupées et transmet au Hub les changements de valeur, de statut ou de date pour les Paths qu'il gère. Il ne crée pas une collecte par session cliente.
- Récupérer les mises à jour et les afficher. Le Hub conserve l'état courant de chaque Path et prépare les changements pour les sessions intéressées. Dans le fonctionnement REST décrit ici, le consommateur demande les changements de sa session, reçoit les valeurs avec leurs identifiants, statuts et dates, puis actualise son affichage. Le connecteur n'envoie pas directement les mesures à Beholder.
L'identifiant de session désigne l'accès du consommateur au Hub. L'identifiant d'un handle dans cette session est un entier choisi par le consommateur pour reconnaître la donnée dans les réponses. Il ne doit pas désigner deux Paths différents au sein de la même session. Deux sessions peuvent utiliser des identifiants différents pour le même Path ; elles partagent alors le suivi de cette donnée par le Hub.
Ces identifiants ne sont ni le sensor_uuid Testo ni, par nature, l'identifiant d'une famille ou d'une instance Immersive. Une session peut suivre les données de plusieurs instances et de plusieurs protocoles. La fermer retire ses associations aux handles ; les autres sessions continuent à recevoir les données qu'elles suivent.
Un Path sans prise en charge reste une demande à traiter : le Hub peut la réexaminer lorsque des connecteurs deviennent disponibles. Il faut distinguer cette attente, le refus d'une adresse invalide et une donnée momentanément inaccessible chez un connecteur qui la prend déjà en charge.
Concevoir le Path de ses handles
Le Path est le contrat d'adressage
Le Path est la chaîne d'adressage du handle. Son format permet au connecteur de répondre à deux questions : « Est-ce une adresse que je sais prendre en charge ? », puis « Quelle donnée précise dois-je lire ou gérer ? » Le Hub n'impose pas un format d'URL universel à tous les connecteurs : chacun définit la syntaxe adaptée à sa source. L'exemple Testo choisit le format décrit ci-dessous.
Dans cet exemple, le Path prend la forme d'une URL de connecteur. Son schéma Testo:// identifie la famille d'adresses, et les segments suivants identifient le capteur puis la donnée demandée. Ce Path est utilisé par le Hub et le connecteur ; ce n'est pas l'URL HTTPS de l'API Testo.
Le format général choisi est :
Testo://{sensor_uuid}/{grandeur}
Les accolades désignent ici des emplacements à remplacer. Elles ne font pas partie d'un Path concret.
Décomposer un exemple complet
Une salle du « Musée exemple » contient un capteur nommé « Ambiance salle A ». Pour représenter sa température, l'utilisateur configure un handle depuis l'Enhancer ou via les accès OData du serveur, avec le Path suivant :
Testo://11111111-1111-4111-8111-111111111111/Temperature
| Partie | Signification |
|---|---|
Testo:// |
Préfixe reconnu par le connecteur Testo avec sa configuration par défaut. Il permet d'identifier les handles qui le concernent. |
11111111-1111-4111-8111-111111111111 |
Exemple fictif de sensor_uuid : l'identifiant unique d'un capteur fourni par l'API Testo. Un UUID est un identifiant de 128 bits, représenté ici par 32 caractères hexadécimaux répartis en cinq groupes séparés par des tirets. |
/ |
Séparateur entre l'identifiant du capteur et la donnée demandée. |
Temperature |
Nom de la grandeur à lire : la température de ce capteur, en degrés Celsius pour les canaux pris en charge par cet exemple. C'est un mot-clé du format de Path, pas la valeur mesurée. |
Il faut remplacer l'UUID fictif par le sensor_uuid réel du capteur. Cet identifiant est disponible dans l'inventaire retourné par l'API et exposé par la propriété Inventory du connecteur. Ce n'est ni le numéro de série de l'appareil, ni son nom affiché, ni le device_uuid de l'appareil qui le porte. Il est également distinct des identifiants Equipment et EquipmentInstance du modèle Immersive et de l'identifiant utilisé pour ce handle dans une session du Hub.
Le même capteur peut être adressé avec plusieurs handles, chacun représentant une donnée différente :
Testo://11111111-1111-4111-8111-111111111111/Temperature
Testo://11111111-1111-4111-8111-111111111111/RelativeHumidity
Testo://11111111-1111-4111-8111-111111111111/Location
Ces trois handles désignent respectivement la température, l'humidité relative et l'emplacement du même capteur. Changer le dernier segment change la donnée demandée ; changer l'UUID change le capteur.
Reconnaître un handle, puis valider son adresse
Le Hub peut faire appel à plusieurs connecteurs. Pour un Path dont il recherche la prise en charge, il interroge les connecteurs avec CanHandle(handle) ; chacun utilise le Path pour déterminer quels handles il sait gérer. Dans ConnectorBase, cette méthode vérifie que le connecteur est connecté, puis appelle son point d'extension OnCanHandle(handle).
Le connecteur Testo redéfinit OnCanHandle pour reconnaître le préfixe placé au début du Path, sans appel réseau. Avec Pattern = Testo://, un Path commençant par Testo:// est candidat à sa prise en charge ; un Path bacnet://... ne l'est pas. Un autre connecteur choisit sa propre règle : le Hub ne devine pas la syntaxe de tous les protocoles.
Le Hub demande ensuite aux connecteurs candidats de prendre en charge les handles avec HandleHandles(...). Dans Testo, cette méthode vérifie la forme de l'UUID, le mot-clé de grandeur, la présence du capteur dans l'inventaire et la disponibilité de cette grandeur. Il s'agit de l'enregistrement auprès du connecteur, distinct de l'enregistrement de la demande dans une session. Reconnaître un préfixe avec CanHandle ne signifie donc pas que la validation détaillée réussira.
| Demande | Résultat dans cet exemple |
|---|---|
| Path d'un autre protocole | Le connecteur Testo ne revendique pas sa prise en charge. |
| Préfixe Testo mais UUID mal formé | Le connecteur reconnaît la famille d'adresses, puis refuse l'enregistrement avec un message explicite. |
| UUID valide mais absent de l'inventaire accessible | Enregistrement refusé : capteur inconnu pour ce compte. |
| Capteur connu mais grandeur non disponible | Enregistrement refusé avec la raison. |
| Capteur et grandeur connus, mesure absente ou trop ancienne | Handle pris en charge ; qualité Unreachable, avec un message expliquant l'état de la donnée. |
Reconnaître un Path, accepter sa prise en charge et disposer d'une mesure exploitable sont trois résultats distincts. CanHandle exprime la reconnaissance ; IsRegistrationSucceeded et SupportStatus décrivent la prise en charge par le connecteur ; HandleStatus décrit l'état technique de la donnée. Si aucun connecteur disponible ne revendique le Path, le Hub peut signaler NoConnectorFound à la session. Cela ne signifie pas que ce Path sera définitivement impossible à traiter.
Pourquoi travailler le format avant de coder ?
Les utilisateurs vont enregistrer ces paths dans leurs projets et leurs configurations. Le format devient un contrat durable : le modifier peut rendre leurs handles existants inutilisables.
- Choisir un préfixe identifiable et une règle de reconnaissance précise, pour éviter de prendre en charge les handles d'un autre connecteur.
- Utiliser des identifiants stables. Un nom de salle peut changer ; l'UUID du capteur permet de conserver le même Path après un renommage ou un déplacement.
- Séparer clairement l'identité de l'équipement et la donnée demandée. Documenter les mots-clés acceptés, comme
TemperatureetRelativeHumidity. - Définir les séparateurs, la casse, les segments obligatoires et les éventuels paramètres. Décider également comment faire évoluer le format sans casser les adresses existantes.
- Garder les secrets dans la configuration du connecteur. Le Path peut être affiché, journalisé et partagé ; il ne doit pas contenir la clé API.
- Prévoir des erreurs compréhensibles et des exemples valides, invalides et limites. Un Path mal formé doit être refusé, sans interprétation approximative.
Dans le format Testo fourni, il y a exactement deux éléments après le préfixe : un UUID au format 8-4-4-4-12, puis l'un des mots-clés documentés. Le préfixe et le mot-clé sont reconnus sans distinction de casse par Testo. Conserver néanmoins la même écriture canonique des Paths dans les configurations et les sessions pour partager le même suivi dans le Hub. Aucun paramètre après ?, fragment après # ou segment supplémentaire n'est accepté. Les caractères de structure d'une URL doivent être traités comme tels ; il ne suffit pas de les encoder pour rendre valide une syntaxe que le connecteur ne prend pas en charge.
Configuration du connecteur
Deux champs sont importants dans la configuration du connecteur :
- ConnectionString :
ConnectionStringcontient l'URL HTTPS réelle de base de l'API Testo. Pour un compte européen, renseignerhttps://data-api.eu.smartconnect.testo.com/. Le connecteur utilise cette base pour construire les URL de ses requêtes. La clé reste dans le paramètreApiKeyou la variable d'environnement prévue à cet effet. - Pattern :
Testo://est réservé aux Paths des handles et à leur préfixe de reconnaissancePattern. Il permet au connecteur de reconnaître les données qui lui sont demandées par le Hub.
| Configuration | Valeur | À quoi sert-il ? |
|---|---|---|
ConnectionString |
https://data-api.eu.smartconnect.testo.com/ |
Définir l'adresse HTTPS de base de l'API, selon la région du compte Testo. |
Pattern |
Testo:// |
Reconnaître le préfixe des Paths pris en charge par cette instance du connecteur. |
Ainsi le connecteur saura reconnaitre un path qu'il sait gérer (commençant par Testo://) et connaîtra l'adresse du serveur Testo à adresser.
| Élément | Exemple | À quoi sert-il ? |
|---|---|---|
| Path du handle | Testo://11111111-1111-4111-8111-111111111111/Temperature |
Désigner le capteur et la grandeur demandée. |
| URL d'une requête API | https://data-api.eu.smartconnect.testo.com/v2/measurements |
Adresse construite par le connecteur pour demander une extraction de mesures. |
La documentation Testo définit trois régions : eu, am et ap. Selon celle du compte, utiliser dans ConnectionString l'une des URL suivantes :
https://data-api.eu.smartconnect.testo.com/
https://data-api.am.smartconnect.testo.com/
https://data-api.ap.smartconnect.testo.com/
Renseigner uniquement la base HTTPS : aucun suffixe comme /v2/measurements, aucune clé, aucun paramètre de requête. Le connecteur refuse une adresse qui ne correspond pas à l'une de ces bases officielles et explique l'erreur de configuration.
Pour deux comptes Testo dans le même Hub, choisir des préfixes distincts dans leurs paramètres Pattern, par exemple TestoSiteA:// et TestoSiteB://, puis employer ces préfixes dans les handles correspondants. Cela évite que deux instances revendiquent la même adresse.
Préparer un projet autonome
Le package NuGet d'abstraction
Le package GraphicStream.Immersive.Hub.Abstractions fournit le vocabulaire commun au Hub et aux connecteurs : interfaces comme IConnector et IHubContext, classe de base ConnectorBase, modèles de handles et résultats d'opérations. Ce sont les contrats auxquels le connecteur doit se conformer pour être chargé et utilisé par le Hub.

Ouvrir le package GraphicStream.Immersive.Hub.Abstractions sur NuGet.
Le projet fourni cible .NET 10 et référence la version 2.0.2 du package NuGet. Utiliser une version du Hub ou de ConnectorTester compatible avec ces contrats, notamment le service de stockage utilisé par le connecteur.
Le package doit être accessible dans vos sources NuGet. Le projet fourni est autonome : les sources du Hub ne sont pas nécessaires pour le compiler.
NuGet est le gestionnaire de packages de .NET. Dans Visual Studio, ouvrir « Gérer les packages NuGet », chercher le nom exact du package et sélectionner la version 2.0.2. La même installation peut se faire en ligne de commande, depuis le dossier du projet :
dotnet add package GraphicStream.Immersive.Hub.Abstractions --version 2.0.2
La référence du projet fourni est la suivante :
<ItemGroup>
<PackageReference Include="GraphicStream.Immersive.Hub.Abstractions"
Version="2.0.2"
ExcludeAssets="runtime"
PrivateAssets="all" />
</ItemGroup>
NuGet restaure automatiquement le package et fournit sa DLL au compilateur. Aucun chemin manuel vers une DLL ni accès au dépôt Immersive n'est nécessaire.
ExcludeAssets="runtime" conserve la référence nécessaire pour compiler et exclut les fichiers d'exécution de ce package de la sortie du connecteur : le Hub fournit déjà l'abstraction. PrivateAssets="all" empêche de transmettre cette dépendance aux projets qui référencent le connecteur. Une application de test autonome référence donc elle-même le package d'abstraction, avec les fichiers d'exécution nécessaires.
Ce qui est partagé à l'exécution
Au développement, le projet utilise le package NuGet pour connaître les types et méthodes du contrat. À l'exécution, le Hub ou ConnectorTester fournit déjà la DLL d'abstraction commune. Pour cet exemple Testo, le dossier des connecteurs reçoit uniquement GraphicStream.Immersive.Hub.Connectors.Testo.dll.
L'abstraction ne contient ni les mesures Testo ni l'implémentation du connecteur. Elle permet au Hub et au connecteur de se comprendre. Vérifier la compatibilité du package référencé avec les contrats réellement disponibles dans le Hub cible.
Dans cet exemple, HttpClient, System.Text.Json et GZipStream sont disponibles dans .NET ; aucune bibliothèque HTTP ou JSON supplémentaire n'est nécessaire. Un autre connecteur peut avoir besoin de bibliothèques tierces : son déploiement devra inclure ses propres dépendances selon les règles de chargement des connecteurs du Hub.
Organisation de l'exemple fourni
| Fichier | Responsabilité |
|---|---|
TestoConnector.cs |
Contrat du Hub, propriétés de configuration, cycle de vie, enregistrement et notifications. |
TestoSettings.cs |
Lecture des paramètres, validation et calcul du budget théorique. |
TestoPath.cs |
Reconnaissance du préfixe et validation stricte des adresses. |
TestoApi.cs |
Requêtes HTTPS, suivi des extractions, téléchargement et décompression. |
TestoModels.cs |
Conversion des réponses Testo, grandeurs et hiérarchie des emplacements. |
TestoAccount.cs |
Collectes regroupées, cache, ancienneté des données et reprise après erreur. |
TestoStorage.cs |
Lecture et sauvegarde de l’état commun via le service de stockage du Hub ; arrêt de la collecte si cette sauvegarde devient impossible. |
TestoQuota.cs |
Compteur mensuel de POST et réservation persistante avant chaque envoi. |
TestoLegacyCache.cs |
Import unique de l’ancien cache local, avec son compteur, lors de la migration. |
Implémenter le contrat du Hub
Le Hub fournit au connecteur un contexte IHubContext. Ce contrat lui permet notamment de publier les changements avec Context.NotifyHandleChanged(snapshot) et de transmettre ses journaux. ConnectorTester fournit également ce contexte pour les essais du connecteur. Le connecteur Testo n'ouvre pas une session cliente pour chaque capteur : il reçoit du Hub les Paths à prendre en charge et lui renvoie leurs états.
La classe publique TestoConnector hérite de ConnectorBase, issue de l’abstraction compatible présentée au chapitre précédent. Elle est la seule classe concrète du projet qui implémente IConnector, ce qui évite plusieurs entrées pour un même connecteur lors de sa découverte.
| Point d'extension | Travail du connecteur |
|---|---|
OnConnect() |
Valider les paramètres, préparer la collecte et retourner un résultat explicite. |
OnCanHandle(IHandle) |
Reconnaître ses paths rapidement, sans accès réseau. |
HandleHandles(...) |
Valider chaque adresse et retourner une réponse individuelle, même en cas d'échec. |
GetHandle(path, date) |
Renvoyer le dernier snapshot disponible d'un handle enregistré. |
WriteValue(path, value) |
Effectuer une écriture autorisée ou renvoyer un refus explicite. |
OnDisconnect() |
Annuler la tâche périodique, attendre sa fin et libérer le collecteur. |
Dispose() |
Garantir la libération des ressources lorsque l'instance du connecteur est détruite. |
Les méthodes publiques Connect() et Disconnect() de la classe de base gèrent le statut du connecteur. Le code métier se place dans leurs méthodes d'extension OnConnect() et OnDisconnect().
Dans Testo, OnCanHandle reconnaît le préfixe. La validation détaillée a lieu à l'enregistrement : UUID incorrect, grandeur inconnue ou capteur absent produisent alors une erreur lisible. Un Path d'un autre format n'est pas revendiqué par Testo ; il ne sera traité que si un autre connecteur disponible le reconnaît.
Fournir le snapshot initial
Dans la réponse de HandleHandles, IsRegistrationSucceeded = true signifie que le connecteur prend en charge le Path. Cela ne signifie pas que la donnée est disponible ou récente. Un capteur connu sans mesure peut donc être enregistré avec la qualité Unreachable et une valeur absente.
L'extrait suivant montre les champs importants d'une réponse ; snapshot est construit à partir du cache et path contient l'adresse de la donnée demandée.
var response = new HandleRegistrationResponse
{
Path = path,
IsRegistrationSucceeded = true,
SupportStatus = SupportStatus.Known,
HandleStatus = snapshot.Status,
InitialValue = snapshot.Value,
StatusMessage = snapshot.StatusMessage,
InitialSnapshot = snapshot
};
Le snapshot initial conserve la valeur, le statut et la date source, même si la valeur manque ou que le statut est dégradé. Ne pas remplacer une date de mesure absente par l'heure de l'enregistrement. Le Hub doit pouvoir restituer un premier état au consommateur même en cas d'échec. Vérifier que sa version prend en charge InitialSnapshot, pour conserver ces métadonnées lors de l'enregistrement.
Publier les changements
Context?.NotifyHandleChanged(snapshot);
Publier lorsque la valeur, la qualité, la date source ou le message change. Une nouvelle mesure identique en valeur doit être publiée si sa date change. En revanche, la simple consultation d'une valeur ne crée pas une nouvelle mesure.
Le collecteur protège son cache contre les accès simultanés. La collecte réseau est asynchrone ; les méthodes d'enregistrement et de consultation restent locales et rapides. Le connecteur publie les changements par Path ; le Hub se charge de les associer aux sessions intéressées et à leurs identifiants. Il n'est pas nécessaire d'interroger Testo ou de publier une seconde fois pour chaque consommateur.
Déclarer et protéger la configuration
Les attributs ConnectorMetadata et ConnectorDefaults décrivent le connecteur et ses valeurs initiales. Les attributs ConnectorProperty décrivent les champs affichés dans le formulaire de modification d’un connecteur du Hub et dans ConnectorTester, sans nécessiter un écran spécifique. Le Hub reprend leur libellé, leur description, leur valeur par défaut, leur caractère obligatoire et leur règle de validation.
[ConnectorProperty("ApiKey",
DisplayName = "Clé API",
IsSecret = true,
Description = "Facultatif si la clé est fournie par une variable d'environnement.")]
La configuration active est accessible dans Definition.Properties. Le Hub ou ConnectorTester doit avoir ajouté la définition à ses paramètres et avoir attribué au connecteur le même Name : Definition est résolue par ce nom.
IsSecret=true masque la saisie dans l’interface ; il ne chiffre pas la valeur enregistrée dans appsettings.json. Protéger l’accès à ce fichier et conserver une clé fictive dans les exemples partagés.
Renseigner la clé API dans ConnectorTester
ConnectorTester construit le formulaire à partir des paramètres déclarés par le connecteur. La propriété ApiKey, déclarée avec IsSecret=true, apparaît sous le libellé Clé API, avec une saisie masquée.
- Dans l’onglet Connecteurs, sélectionner Testo, puis cliquer sur Configurer….
- Renseigner l’URL HTTPS de la région dans Chaîne de connexion, par exemple
https://data-api.eu.smartconnect.testo.com/, et conserverTesto://dans Pattern. - Dans Paramètres du connecteur, saisir la clé fournie par Testo dans Clé API. Lorsque cette valeur est renseignée, aucune variable d’environnement n’est nécessaire.
- Cliquer sur Enregistrer pour conserver la configuration dans
appsettings.json. - Revenir à la liste des connecteurs et cliquer sur Tester la connexion.

La même configuration dans appsettings.json
La clé est enregistrée dans la collection Properties du connecteur, sous la clé ApiKey. La chaîne de connexion contient uniquement l’URL HTTPS de l’API ; Pattern indique le préfixe des Paths reconnus par ce connecteur.
{
"HubSettings": {
"Connectors": [
{
"Name": "Testo",
"Type": "GraphicStream.Immersive.Hub.Connectors.Testo.TestoConnector, GraphicStream.Immersive.Hub.Connectors.Testo",
"Pattern": "Testo://",
"ConnectionString": "https://data-api.eu.smartconnect.testo.com/",
"Properties": [
{ "Key": "ApiKey", "Value": "sk_testo_p_EXAMPLE_NOT_A_REAL_KEY" }
]
}
]
}
}
Cet extrait présente uniquement les paramètres nécessaires à la connexion. Les autres paramètres peuvent conserver leurs valeurs par défaut. Remplacer la clé fictive par celle du compte à utiliser et conserver les autres connecteurs déjà présents dans le fichier. Pour modifier appsettings.json manuellement, fermer ConnectorTester, enregistrer le fichier, puis relancer le testeur.
Utiliser une variable d’environnement en alternative
La propriété ApiKey est prioritaire si elle est renseignée. Sinon, le connecteur lit la variable dont le nom est indiqué dans ApiKeyEnvironmentVariable, par défaut IMMERSIVE_TESTO_API_KEY.
$env:IMMERSIVE_TESTO_API_KEY = 'sk_testo_p_EXAMPLE_NOT_A_REAL_KEY'
Start-Process -FilePath '.\ConnectorTester.exe'
Lancer le testeur depuis ce processus lui transmet la variable. Pour un service, configurer l'environnement du service. Ne jamais placer la clé dans le path d'un handle, une URL, un journal ou un exemple partagé.
Quels réglages viennent de cet exemple ?
Les paramètres de collecte, de quota et de cache du tableau ci-dessous ont été créés pour ce connecteur Testo. Leurs noms, leurs valeurs par défaut et leurs bornes de validation sont des choix d’implémentation, pas des options de l’API Testo ni des règles du SDK du Hub. Ils sont modifiables dans le code de votre propre connecteur.
La contrainte externe à respecter est le quota Testo : 10 000 POST par mois calendaire UTC et par compte, partagé avec les autres applications du compte. Les GET de suivi ne sont pas comptés. Le plafond local de 9 000 a été choisi pour garder une marge ; il ne représente pas le solde réellement disponible chez Testo. Voir la politique de quota Testo.
| Paramètre | Défaut | Rôle et limites |
|---|---|---|
ConnectionString |
https://data-api.eu.smartconnect.testo.com/ |
URL HTTPS de base officielle de l’API ; utiliser la région eu, am ou ap du compte. |
Pattern |
Testo:// |
Préfixe que cette instance reconnaît au début des Paths ; utiliser un autre préfixe pour un autre compte. |
ApiKey |
Vide | Clé facultative dans les propriétés, prioritaire sur la variable. |
ApiKeyEnvironmentVariable |
IMMERSIVE_TESTO_API_KEY |
Nom de la variable contenant la clé. |
PollIntervalMinutes |
15 |
Toutes les 15 min, demander les nouvelles mesures de tous les capteurs en une extraction. Bornes choisies dans cet exemple : 10 à 1440 min. |
StatusIntervalMinutes |
60 |
Actualiser la batterie et la dernière communication toutes les 60 min. Bornes de cet exemple : 30 à 1440 min. |
MetadataIntervalHours |
24 |
Actualiser les appareils, les emplacements et leurs affectations toutes les 24 h. Bornes de cet exemple : 6 à 168 h. |
InitialLookbackHours |
24 |
Au premier démarrage sans données conservées, rechercher les mesures des dernières 24 h. Ce réglage ne change pas la cadence de collecte. Bornes : 1 à 744 h. |
LateArrivalDays |
30 |
Lors des collectes suivantes, accepter les mesures prises jusqu’à 30 jours plus tôt mais reçues récemment par Testo. Le filtre processed_at limite la collecte aux arrivées récentes. Bornes : 1 à 365 jours. |
MonthlyPostBudget |
9000 |
Suspendre les nouveaux POST lorsque le compteur local atteint 9 000 dans le mois UTC. Bornes : 1 à 10 000 ; la cadence configurée doit tenir dans ce budget. |
StaleAfterHours |
12 |
Considérer une donnée de mesure ou d’état comme trop ancienne après au moins 12 h ; le seuil est prolongé si deux cycles de transmission du capteur plus une collecte dépassent 12 h. Bornes : 1 à 8760 h. |
Ces cadences sont les valeurs de départ choisies pour cet exemple ; elles sont configurables et ne constituent pas des intervalles imposés par le Hub ou l'API Testo. Les adapter à la transmission réelle des capteurs et au budget du compte.
Utiliser le stockage du Hub pour le cache
Testo utilise Context.StorageService, fourni par le Hub à travers la DLL d’abstraction. Le connecteur ne choisit plus un dossier de cache local et ne possède aucune connexion Azure spécifique. Il utilise le même stockage que le Hub : Azure Blob ou le stockage de fichiers configuré dans IOSettings.
Les données sont regroupées dans un objet Connectors/Testo/{empreinte}/state.json. L’empreinte correspond aux 32 premiers caractères hexadécimaux du SHA-256 de la région, d’un saut de ligne puis de la clé, pour isoler les configurations ; la clé elle-même n’est pas enregistrée dans cet objet. Celui-ci contient :
- les appareils, les dernières mesures et les dates des collectes réussies ;
- les identifiants des extractions en cours, pour reprendre leur suivi sans refaire un POST ;
- le compteur de POST réservés pendant le mois UTC.
Le connecteur garde également ces données en mémoire pour servir les handles immédiatement. Cet objet persistant permet de retrouver son état après un redémarrage ; il ne constitue pas un historique complet des mesures.
Dans une Azure Web App
Configurer le stockage du Hub pour Azure Blob, avec sa connexion et son conteneur habituels. Testo utilise automatiquement ce conteneur. Il n’y a aucun dossier local à créer, aucun CacheDirectory à renseigner, ni aucun SDK Azure à ajouter au projet du connecteur. Le conteneur doit exister et le Hub doit pouvoir y lire, écrire et prendre un verrou sur les blobs.
Le fournisseur Azure est implémenté dans le Hub. Le connecteur conserve sa seule dépendance au package d’abstraction 2.0.2. ConnectorTester implémente le même contrat avec son stockage de fichiers automatique, afin que le code du connecteur reste identique dans les deux cas. Dans le testeur actuel, la racine est %TEMP%\ConnectorTester_Storage : les fichiers survivent au redémarrage du testeur, mais restent soumis au nettoyage du dossier temporaire de Windows. Pour une exploitation durable, le Hub utilise son stockage persistant configuré.
Comprendre le verrouillage et l’écriture atomique
Le verrouillage réserve l’objet d’état à un seul collecteur. Si deux instances de Testo utilisent la même clé, la même région et le même stockage, elles ciblent le même objet : la seconde ne peut pas ouvrir sa collecte tant que la première conserve le verrou. Ce verrou porte sur state.json pour cette configuration, pas sur tous les fichiers du Hub.
L’écriture atomique signifie que le contenu enregistré est remplacé en entier. Une lecture retrouve la version complète précédente ou la nouvelle version complète ; une écriture interrompue ne doit pas laisser un JSON partiellement écrit. Cache, compteur et suivi des extractions sont sérialisés dans un même objet pour conserver un état cohérent.
| Fournisseur du stockage | Comment le verrou est obtenu | Comment l’état est sauvegardé |
|---|---|---|
| Fichiers, y compris ConnectorTester | Un fichier .lock reste ouvert sans partage pendant la connexion. Une autre instance ne peut pas prendre le même verrou. |
Le nouveau contenu est écrit et vidé sur disque dans un fichier temporaire du même dossier, puis remplace state.json. |
| Azure Blob dans le Hub | Le Hub prend un bail de 60 secondes sur le blob et le renouvelle toutes les 20 secondes. | Le Hub envoie le contenu complet avec l’identifiant du bail ; une écriture provenant d’un collecteur ayant perdu ce bail est rejetée. |
Le bail Azure est le mécanisme de réservation fourni par Azure Storage ; il ne demande aucune configuration Testo supplémentaire. Fonctionnement des baux Azure Blob.
Utiliser le contrat depuis un connecteur
IStorageService.OpenExclusiveFileAsync retourne un IStorageFileLease. Le connecteur conserve cet objet pendant la durée de sa collecte. Lost est un jeton d’annulation signalant que l’accès exclusif n’est plus garanti ; DisposeAsync libère le verrou à la déconnexion.
using GraphicStream.Immersive.Hub.IO;
// relativePath désigne un objet dans le stockage configuré du Hub.
await using IStorageFileLease state = await Context.StorageService
.OpenExclusiveFileAsync(relativePath, cancellationToken);
using var collection = CancellationTokenSource.CreateLinkedTokenSource(
cancellationToken, state.Lost);
using Stream? previous = await state.ReadAsync(collection.Token);
// Lire l’état précédent et préparer serializedState.
using var payload = new MemoryStream(serializedState);
await state.WriteAsync(payload, collection.Token);
Cet extrait illustre les appels du contrat ; relativePath, serializedState et cancellationToken sont fournis par le connecteur. Dans Testo, TestoStorage conserve le verrou entre les collectes et TestoAccount propage Lost aux opérations en cours. Il ne faut pas ouvrir puis relâcher le verrou entre la réservation d’un POST et l’enregistrement de son résultat.
Les fournisseurs fichiers et Azure Blob du Hub implémentent ce contrat. Le fournisseur SQL du Hub ne le propose pas encore : Testo signale alors une erreur explicite à la connexion.
Préserver le quota et reprendre une collecte
Avant chaque POST à Testo, le connecteur augmente le compteur puis sauvegarde l’objet d’état. Si cette sauvegarde échoue, le POST n’est pas envoyé. Après réception de l’identifiant d’extraction, celui-ci est également sauvegardé pour permettre la reprise de son suivi par GET. Une fois le résultat récupéré, les données, la date de reprise et le retrait de l’extraction terminée sont sauvegardés ensemble.
Une erreur de stockage ou la perte du verrou suspend la collecte ; reconnecter le connecteur une fois le problème résolu. Le compteur reste conservateur : une réservation reste comptée si le résultat d’un appel réseau est incertain. Le stockage et l’API Testo ne forment pas une transaction commune ; si le processus s’arrête après l’acceptation d’un POST mais avant la sauvegarde de son identifiant, une nouvelle demande peut être nécessaire à la reprise.
Au redémarrage, le connecteur recharge l’état et compare les dates des dernières collectes aux intervalles configurés. Un cache encore récent évite une nouvelle extraction immédiate. Si une collecte est déjà due, elle est lancée normalement et sa réservation s’ajoute au compteur conservé. Le changement de mois UTC renouvelle le compteur mensuel selon la règle prévue, indépendamment des redémarrages.
Deux instances utilisant la même clé, la même région et le même stockage ciblent le même objet. Une seule peut le verrouiller ; la seconde est refusée tant que la première le détient. Ce mécanisme protège le cache et son compteur, mais ne constitue pas une orchestration automatique de bascule entre plusieurs Hubs. Des clés ou stockages distincts ont des compteurs distincts, alors que le quota Testo reste partagé au niveau du compte.
Mettre à jour une ancienne installation
Si aucun état n’existe encore dans le stockage du Hub et que l’ancien cache local est accessible, Testo importe une fois ses données, ses extractions et son compteur. Il recherche le dossier historique par défaut ou utilise l’ancienne propriété CacheDirectory si elle est encore présente ; cette propriété sert uniquement à la migration et n’est plus proposée dans le formulaire. Les anciens fichiers sont conservés.
L’ancien collecteur doit être arrêté pendant cette opération. Un compteur ancien illisible provoque une erreur explicite, sans remise à zéro silencieuse. Si le Hub change aussi de machine, transférer l’état persistant issu de cette migration dans le stockage cible avant d’activer la collecte ; un nouveau serveur ne peut pas retrouver les fichiers d’une autre machine.
Adapter une API asynchrone
L’API prépare un export en arrière-plan : la première réponse confirme la demande, elle ne contient pas encore les mesures. Le schéma suivant montre une extraction groupée, puis ce que le connecteur en fait pour servir les handles.
Les trois échanges avec Testo correspondent au fonctionnement asynchrone documenté par Testo. Le cache et la notification au Hub sont les étapes ajoutées par notre connecteur. La prochaine collecte démarre selon ses paramètres d’intervalle ; une lecture de handle n’entraîne pas une nouvelle extraction.
L'API Testo prépare les données sous forme de fichiers. Un POST démarre une extraction, un GET permet d'en suivre l'état, puis le connecteur télécharge chaque fichier annoncé dans data_urls.
| Données | Endpoint utilisé |
|---|---|
| Capteurs, appareils et canaux | /v3/devices/properties |
| Emplacements et parents | /v1/locations |
| Affectations des capteurs | /v1/measuring-objects |
| Batterie et communication | /v4/devices/status |
| Mesures | /v2/measurements |
Une extraction est demandée au format JSON. Le client accepte un tableau JSON ou des objets JSON séparés par des sauts de ligne. Il reconnaît également un contenu gzip grâce à sa signature, même si l'en-tête HTTP de compression est absent.
{
"options": {
"result_file_format": "JSON"
}
}
Authentification et téléchargements
Le client envoie la clé dans l'en-tête x-custom-api-key utilisé par les exemples officiels Testo. L'implémentation fournie conserve ce nom d'en-tête et utilise explicitement HTTP/1.1.
using var request = new HttpRequestMessage(HttpMethod.Post, endpoint)
{
Version = HttpVersion.Version11,
VersionPolicy = HttpVersionPolicy.RequestVersionExact
};
request.Headers.TryAddWithoutValidation("x-custom-api-key", apiKey);
La clé est ajoutée à chaque requête vers l'API, pas dans les en-têtes par défaut du client HTTP. Les fichiers sont téléchargés depuis les URL S3 temporaires fournies par Testo, sans transmettre la clé. Les redirections automatiques sont désactivées.
L'identifiant d'une extraction en cours est sauvegardé. Une interruption du téléchargement ou une attente trop longue permet de reprendre son suivi par GET au cycle suivant sans créer immédiatement un nouveau POST. Le client abandonne les références locales de plus de douze heures et redemande une extraction. Une réponse terminée peut contenir plusieurs fichiers : tous doivent être lus.
Reconstituer les emplacements
Un capteur, un appareil, un emplacement et un objet de mesure sont des entités différentes. Le nombre de lignes exportées n'est donc pas le nombre de capteurs.
Le connecteur regroupe l'inventaire par sensor_uuid. Il associe les sensorUuid des channel_assignments aux emplacements désignés par back_reference, puis remonte les parent_uuid pour construire un chemin lisible.
Musée exemple > Exposition permanente > Salle A > Ambiance
Le champ parent_uuid est demandé explicitement par $select, car la réponse par défaut peut l'omettre. Plusieurs affectations sont conservées et affichées séparément. Un capteur sans affectation reste dans l'inventaire ; son handle Location signale l'absence d'emplacement.
Regrouper les lectures et maîtriser le quota
Dans cet exemple, le nombre de handles et de sessions clientes ne détermine pas le nombre de requêtes Testo. Pour 100 capteurs avec quatre grandeurs chacun, les 400 handles partagent le cache et les extractions de mesures d'une même instance de connecteur. HandleHandles, GetHandle et WriteValue ne déclenchent aucun appel HTTP.
Le collecteur démarre à la connexion du connecteur et fonctionne jusqu'à sa déconnexion, même si aucun handle n'est encore activé. Ajouter une session ou un handle ne démarre donc pas un collecteur supplémentaire ; fermer une session ne déconnecte pas le connecteur Testo.
Avec les réglages par défaut, un mois de 31 jours représente environ :
| Collecte | Calcul | POST |
|---|---|---|
| Mesures toutes les 15 minutes | 31 × 24 × 4 | 2976 |
| État des appareils toutes les heures | 31 × 24 | 744 |
| Trois extractions d'inventaire par jour | 31 × 3 | 93 |
| Total théorique | Hors reprises exceptionnelles | 3813 |
La politique d'usage Testo annonce un quota de 10000 POST par mois et par compte. Le suivi par GET et les téléchargements n'entrent pas dans ce compteur. Le plafond local de 9000 laisse une marge, mais ne réserve pas cette marge auprès de Testo.
Le compteur local ne connaît pas les appels d'autres logiciels, d'autres machines ou d'autres clés du même compte. Changer de clé ou de dossier de cache crée aussi un autre compteur local. Conserver le cache et coordonner le budget entre toutes les applications du compte.
Chaque POST est réservé dans l’objet d’état du stockage du Hub avant son envoi, y compris si une panne réseau rend ensuite son résultat incertain. TestoQuota gère cette réservation ; TestoStorage la sauvegarde à travers le contrat de stockage exclusif. Un état persistant illisible suspend les requêtes au lieu de remettre silencieusement le compteur à zéro.
Les erreurs réseau et HTTP sont espacées par une attente croissante, jusqu'à une heure. Une erreur d'authentification suspend les tentatives automatiques jusqu'à une nouvelle connexion. Un dépassement de quota reconnu suspend les demandes jusqu'au prochain mois UTC. Aucun POST n'est relancé immédiatement en boucle.
Tenir compte des mesures transmises en retard
La fréquence de mesure d'un capteur et sa fréquence de transmission au cloud peuvent être différentes. Interroger le cloud plus souvent ne force pas une nouvelle mesure sur l'appareil.
La première collecte recherche les mesures dans InitialLookbackHours. Les suivantes utilisent une fenêtre de dates source plus large, LateArrivalDays, et filtrent sur processed_at, la date de traitement dans le cloud. Un recouvrement de cinq minutes limite les pertes à la frontière de deux collectes.
Le cache garde la mesure la plus récente par capteur et par grandeur, selon timestamp, puis processed_at en cas d'égalité. Une ancienne mesure arrivée tardivement ne remplace donc pas une valeur plus récente.
Cette stratégie collecte les dernières valeurs ; elle ne constitue pas un archivage exhaustif. Une mesure reçue avec un retard dépassant LateArrivalDays, ou une donnée antérieure à la recherche initiale, peut ne pas être récupérée. Élargir la fenêtre initiale avant le premier démarrage si nécessaire. Les fichiers trop volumineux sont refusés au-delà de 128 Mio compressés ou décompressés.
Choisir les handles et comprendre leur qualité
Un capteur peut exposer plusieurs grandeurs. La propriété publique Inventory fournit les capteurs accessibles au compte ; AvailablePaths construit les adresses correspondantes. Pour configurer la température d'une instance « Salle A », retrouver son capteur dans cet inventaire et utiliser le Path se terminant par /Temperature. Le consommateur demandera ensuite ce Path au Hub dans sa session. Inventory et AvailablePaths sont des propriétés du connecteur Testo, pas des collections OData du serveur Immersive.
Les identifiants de l'exemple ci-dessous sont fictifs. Remplacer l'UUID par un sensor_uuid retourné pour votre compte.
| Suffixe du path | Valeur | Unité ou format |
|---|---|---|
Temperature |
Température mesurée | °C |
RelativeHumidity |
Humidité relative | % HR |
DewPoint |
Point de rosée | °C |
AbsoluteHumidity |
Humidité absolue | g/m³ |
Name |
Nom de l'appareil dans l'inventaire | Texte |
Location |
Affectations avec hiérarchie | Texte ; plusieurs chemins séparés par | |
Battery |
Niveau de batterie | % |
LastCommunication |
Dernière communication avec le cloud | Date ISO 8601 UTC |
Les quatre premières grandeurs sont proposées uniquement si elles sont reconnues dans l'inventaire du capteur. Les unités ci-dessus sont celles attendues pour les canaux climatiques de cet exemple. Le connecteur transmet les valeurs numériques reçues sans conversion d'unité ; vérifier les unités exposées par les capteurs du compte avant de les associer aux grandeurs du modèle Immersive. Il ne prend pas en charge toutes les familles de produits Testo.
Température de la salle
Testo://11111111-1111-4111-8111-111111111111/Temperature
Humidité d'une vitrine
Testo://33333333-3333-4333-8333-333333333333/RelativeHumidity
Emplacement complet d'un capteur
Testo://11111111-1111-4111-8111-111111111111/Location
Date, qualité et valeur
Value contient la valeur sous forme de chaîne ; les nombres utilisent un point décimal, indépendamment de la langue de Windows. ChangeDate conserve la date source UTC pour les mesures et les états disponibles. Pour Name et Location, elle représente la date de collecte des métadonnées. HandledDate indique la date de la dernière extraction correspondante.
Dans ce connecteur, la qualité technique (HandleStatus) est Good si la donnée est présente, suffisamment récente et sans erreur de collecte active. Elle devient Unreachable lorsque la donnée manque, est trop ancienne ou que la collecte échoue. Le choix Unreachable pour une donnée trop ancienne appartient à cet exemple ; ce n'est pas une règle imposée à tous les connecteurs du Hub. Une valeur déjà obtenue reste consultable avec son ancienne date et une qualité dégradée en cas de panne.
Good ne signifie pas qu'une valeur respecte les seuils métier : une température trop élevée peut être correctement lue. Le statut technique du handle ne doit pas être confondu avec un état métier de l'équipement ou une alarme.
Pour les mesures et les états d'appareil, le seuil d'ancienneté est le maximum entre StaleAfterHours et deux périodes de transmission plus une période de collecte. Pour les métadonnées, le seuil vaut deux périodes de rafraîchissement d'inventaire.
GetHandle(path, date) ne fournit pas un historique : une date de recherche non nulle retourne null. Ce connecteur est en lecture seule ; toute demande d'écriture renvoie un WriteValueResult d'échec et un message explicite.
Remonter les journaux à l'utilisateur
Les messages passent par les méthodes de ConnectorBase. Le Hub ou ConnectorTester reçoit ainsi un message structuré associé au connecteur et peut l'afficher dans son journal.
AddStateMessage("Testo connecté : inventaire disponible.");
AddWarningStateMessage("Ce connecteur est en lecture seule.");
AddErrorStateMessage("Collecte interrompue : authentification refusée.");
Un message doit expliquer ce qui s'est passé et permettre une action utile. Éviter de journaliser chaque lecture locale. Dans l'exemple, une erreur de collecte identique n'est pas répétée à chaque passage ; le rétablissement de la collecte produit un message d'information.
Ne pas passer une exception brute contenant la requête HTTP ou des informations de connexion au journal. TestoApi.Sanitize retire la clé et les URL temporaires à paramètres avant de publier le message. Les données de mesure et la clé ne sont pas incluses dans les messages de connexion.
Compiler et tester avec ConnectorTester
ConnectorTester permet d'essayer directement des Paths et d'observer les valeurs publiées. Il n'est pas nécessaire d'y créer une famille Equipment ou une instance EquipmentInstance : c'est un outil de validation du connecteur. Les essais dans le testeur ne remplacent pas la vérification du parcours complet depuis la configuration Immersive jusqu'à une session cliente du Hub.
Compiler le projet
Depuis le dossier qui contient le fichier .csproj fourni — le sous-dossier src dans le paquet d'exemple — compiler normalement le projet. La restauration du package NuGet référencé se fait automatiquement lors de la compilation :
dotnet build .\GraphicStream.Immersive.Hub.Connectors.Testo.csproj -c Release -o .\artifacts
La machine doit disposer du SDK .NET 10 et pouvoir accéder au package GraphicStream.Immersive.Hub.Abstractions en version 2.0.2 dans ses sources NuGet.
Testo 1.1.0 nécessite le Hub ou ConnectorTester mis à jour avec le support du stockage exclusif et l’abstraction 2.0.2. La DLL à distribuer ensuite est artifacts\GraphicStream.Immersive.Hub.Connectors.Testo.dll. Copier uniquement cette DLL dans le dossier Connectors de ConnectorTester, puis redémarrer le testeur pour charger la nouvelle version. Éviter plusieurs copies de la même DLL ou plusieurs versions du même connecteur dans ce dossier.
Vérifier le comportement
- Saisir une clé réelle dans le champ masqué Clé API de la configuration Testo ; la variable d’environnement reste une alternative.
- Sélectionner Testo, vérifier
ConnectionString = https://data-api.eu.smartconnect.testo.com/pour un compte européen etPattern = Testo://, puis connecter. - Vérifier le nombre de capteurs dans le journal. Comparer des UUID distincts, pas le nombre de lignes ou de canaux exportés.
- Enregistrer une température, une humidité et un emplacement appartenant à des capteurs connus.
- Comparer les valeurs et leurs dates avec la plateforme Testo.
- Enregistrer plusieurs centaines de paths et vérifier que le compteur de POST n'augmente pas à l'enregistrement.
- Attendre une collecte et vérifier les notifications dans le panneau des handles en direct.
- Vérifier qu'un path incorrect et une tentative d'écriture produisent des erreurs explicites.
- Noter le compteur de POST et exporter les valeurs affichées. Les champs
Quota.Month,Quota.ReservedPostset les dates de collecte sont consultables dans l’objet d’état du stockage fourni par le Hub, sans le modifier. - Déconnecter Testo, fermer complètement ConnectorTester, le relancer puis reconnecter Testo et réactiver les mêmes handles. Vérifier la conservation des valeurs, de leurs qualités et des dates source. Si aucun intervalle n’est arrivé à échéance, le compteur doit être inchangé.
- Attendre la prochaine collecte programmée : une extraction de mesures groupée doit ajouter une seule réservation au compteur et actualiser les handles concernés. Une échéance simultanée d’inventaire ou d’état des appareils ajoute les extractions correspondantes.
Les tests automatisés de ce projet indépendant utilisent une implémentation minimale de IHubContext, un fournisseur HTTP simulé et des données fictives. Ils ne dépendent pas des sources du Hub ou de ConnectorTester. Ils vérifient notamment les dates initiales, les notifications, le regroupement des lectures, les fichiers gzip et multiples, les emplacements, le quota persistant, la reprise d'extraction, les erreurs et l'absence de dépendance métier ou web.
dotnet test --project .\tests\GraphicStream.Immersive.Hub.Connectors.Testo.Tests.csproj -c Release
Cette commande s'exécute depuis la racine du projet Testo indépendant. La compilation et les tests simulés doivent être complétés par une connexion réelle avec le Hub cible et sa DLL d'abstraction. Vérifier notamment un Path demandé par deux sessions avec des identifiants différents, le premier état retourné lorsqu'une mesure manque, et le statut d'un Path qu'aucun connecteur ne prend en charge. Ces vérifications portent sur le Hub complet ; ConnectorTester valide d'abord le comportement isolé du connecteur.
Vérifier le stockage utilisé en production
Le parcours manuel précédent vérifie le stockage local fourni par ConnectorTester. Les tests automatisés du connecteur utilisent un stockage simulé ; ils ne valident pas eux-mêmes l’implémentation Azure du Hub. Pour une Azure Web App, répéter la fermeture et la reconnexion avec le Hub configuré sur Azure Blob, conserver le même conteneur et observer le même objet d’état. Vérifier que la conservation du quota ne dépend d’aucun dossier local de la Web App.
Les tests automatisés de cette évolution couvrent aussi le fournisseur Azure du Hub avec Azurite : acquisition exclusive, renouvellement du bail, refus d’un ancien détenteur et reprise de Testo. Azurite est un émulateur ; ces tests ne constituent pas un déploiement sur une Web App réelle.
Réutiliser cet exemple pour votre connecteur
Conserver la séparation entre le contrat du Hub, le client du fournisseur et le cache. Adapter ensuite les identifiants, les grandeurs, les règles de qualité et les contraintes de l'API cible.
| Élément réutilisable | Élément à adapter |
|---|---|
| Cycle de vie et annulation | Connexion et authentification du fournisseur. |
| Déclaration des propriétés | Paramètres propres au protocole et à l'environnement. |
| Validation des paths | Syntaxe d'adressage et identifiants stables. |
| Snapshot initial et notifications | Conversion des valeurs, unités et dates. |
| Collecte commune et cache | Stratégie de regroupement, pagination ou abonnement. |
| Journaux structurés | Messages d'erreur utiles aux utilisateurs. |
| Tests avec réponses simulées | Jeux de données et erreurs de l'API cible. |
Pour un protocole permettant l'écriture, implémenter WriteValue avec validation, résultat explicite et confirmation de l'état réellement obtenu. Une valeur demandée ne devient pas automatiquement une valeur confirmée.
Cet exemple ne fournit ni administration web, ni récupération de rapports PDF, ni catalogue universel des produits Testo. Ces fonctions constituent des capacités distinctes à concevoir selon le besoin du client.
Références : documentation Testo Smart Connect, exemples HTTP officiels, quota et questions fréquentes, référence IMD GraphicStream.
Configuration de ConnectorTester et handles au démarrage
Cet exemple concerne le fichier appsettings.json de ConnectorTester. Fusionner les entrées ci-dessous avec ses sections existantes. Ne pas remplacer les autres connecteurs ou les autres paths. La propriété ApiKey contient ici une valeur fictive ; saisir la clé réelle dans le champ masqué de l’interface. La variable d’environnement peut être utilisée si cette propriété est vide. Les UUID fictifs doivent être remplacés avant de tester.
{
"HubSettings": {
"Connectors": [
{
"Name": "Testo Musée exemple",
"Description": "Capteurs climatiques du site de démonstration",
"Type": "GraphicStream.Immersive.Hub.Connectors.Testo.TestoConnector, GraphicStream.Immersive.Hub.Connectors.Testo",
"Pattern": "Testo://",
"ConnectionString": "https://data-api.eu.smartconnect.testo.com/",
"Properties": [
{ "Key": "ApiKey", "Value": "sk_testo_p_EXAMPLE_NOT_A_REAL_KEY" },
{ "Key": "ApiKeyEnvironmentVariable", "Value": "IMMERSIVE_TESTO_API_KEY" },
{ "Key": "PollIntervalMinutes", "Value": "15" },
{ "Key": "StatusIntervalMinutes", "Value": "60" },
{ "Key": "MetadataIntervalHours", "Value": "24" },
{ "Key": "InitialLookbackHours", "Value": "24" },
{ "Key": "LateArrivalDays", "Value": "30" },
{ "Key": "MonthlyPostBudget", "Value": "9000" },
{ "Key": "StaleAfterHours", "Value": "12" }
]
}
],
"PreloadPaths": [
"Testo://11111111-1111-4111-8111-111111111111/Temperature",
"Testo://11111111-1111-4111-8111-111111111111/RelativeHumidity",
"Testo://11111111-1111-4111-8111-111111111111/DewPoint",
"Testo://11111111-1111-4111-8111-111111111111/AbsoluteHumidity",
"Testo://11111111-1111-4111-8111-111111111111/Name",
"Testo://11111111-1111-4111-8111-111111111111/Location",
"Testo://11111111-1111-4111-8111-111111111111/Battery",
"Testo://11111111-1111-4111-8111-111111111111/LastCommunication",
"Testo://33333333-3333-4333-8333-333333333333/Temperature",
"Testo://33333333-3333-4333-8333-333333333333/RelativeHumidity"
]
}
}
PreloadPaths prépare la liste de Paths à essayer dans ConnectorTester. Il ne crée ni famille ni instance dans le serveur Immersive. Connecter d'abord Testo, puis activer la liste dans le testeur pour recevoir les valeurs en direct.