Lorsque vous avez des dizaines ou des centaines d’appareils, ajoutez-les à partir d’un fichier CSV plutôt qu’un par un. Chaque import est d’abord vérifié : « Chaque import est d’abord un essai à blanc : rien n’est écrit tant que quelqu’un n’a pas examiné ce qui se passerait. », puis appliqué, et il peut être annulé. Les nouveaux appareils reçoivent immédiatement leurs identifiants, remis dans un fichier que vous pouvez télécharger une seule fois.
Les imports se font sur la page Imports (adresse /admin/settings/imports, dans la partie Organisation du menu). La page est disponible lorsque le module d’import est activé dans votre organisation. Vous devez disposer de l’autorisation de créer des appareils.
Préparer le fichier
Le fichier est au format CSV, enregistré en UTF-8, séparé par des virgules, des points-virgules ou des tabulations, avec les noms de colonnes sur la première ligne. Jusqu’à 1 000 lignes par fichier. Sélectionnez Télécharger un modèle dans l’assistant d’import pour obtenir un fichier contenant toutes les colonnes et une ligne d’exemple.
| Colonne | Signification | Règles |
|---|---|---|
name | Nom de l’appareil (unique dans ce compte) | Obligatoire. |
label | Libellé | Texte libre facultatif. |
type | Type d’appareil | Facultatif, par exemple pump-controller. |
profile | Nom du profil d’appareil (vide = le profil par défaut) | Le profil doit exister. |
serial | Numéro de série | Facultatif, jusqu’à 32 caractères parmi A–Z a–z 0–9 . _ : -. Unique sur la plateforme. |
mac | Adresse MAC | Facultatif. Conservée dans les informations complémentaires de l’appareil. |
credentialType | Type d’identifiant (vide = ACCESS_TOKEN) | ACCESS_TOKEN ou MQTT_BASIC. Le X.509 n’est jamais importé. |
mqttUsername | Nom d’utilisateur MQTT (MQTT_BASIC ; vide = généré) | Unique sur la plateforme. |
mqttClientId | Identifiant client MQTT (MQTT_BASIC, facultatif) | De 1 à 64 caractères parmi A–Z a–z 0–9 . _ : -. |
attr:<key> | Un attribut serveur | Jusqu’à 50 colonnes d’attributs, valeurs de 4 096 caractères maximum. |
shared:<key> | Un attribut partagé | Idem ci-dessus. |
Exemple :
name,label,profile,serial,credentialType,attr:maxTemp,shared:cfg.report_interval_s
pump-house-01,Pump house north,Water pumps,SN-000123,ACCESS_TOKEN,80,300
pump-house-02,Pump house south,Water pumps,SN-000124,MQTT_BASIC,75,300Attention
Ne mettez jamais un secret dans le fichier. Une colonne portant un nom de secret (token, password, secret, key, credential, claim code) est refusée, de même qu’une cellule ressemblant à un jeton d’accès. Hermetry crée lui-même les identifiants.
Importer
- Ouvrez Imports puis sélectionnez Nouvel import.
- Fichier : sous Que importer, choisissez Appareils IoT, sélectionnez le fichier CSV, et laissez activée l’option La première ligne contient les noms de colonnes. L’assistant indique le nombre de lignes trouvées.
- Colonnes : vérifiez que chaque champ correspond à la bonne colonne de votre fichier (« Les colonnes portant des noms correspondants sont déjà renseignées. »). Les colonnes commençant par
attr:oushared:sont prises telles quelles. Choisissez Lorsqu’un enregistrement existe déjà :
| Stratégie | Effet |
|---|---|
| Ajouter uniquement les nouveaux enregistrements ; signaler les existants | Un nom existant est une erreur. |
| Mettre à jour uniquement les enregistrements existants | Seuls les noms existants sont modifiés ; les autres sont ignorés. |
| Ajouter les nouveaux enregistrements et mettre à jour les existants | Les deux. |
| Ajouter les nouveaux enregistrements et ignorer les existants | Les noms existants sont ignorés. |
- Sélectionnez Vérifier le fichier. Chaque ligne est vérifiée ; rien n’est encore écrit. L’étape Vérification affiche Lignes dans le fichier, Prêtes à importer, Seront ignorées et Présentent un problème, avec Lignes posant problème (Ligne, Champ, Problème).
- Corrigez le fichier et sélectionnez Choisir un autre fichier, ou sélectionnez Importer n lignes et confirmez. Les lignes posant problème sont laissées de côté.
Ce que la vérification refuse
| Problème | Signification |
|---|---|
| Le nom apparaît plusieurs fois dans ce fichier. | Chaque nom une seule fois par fichier. Les numéros de série et les noms d’utilisateur MQTT aussi. |
| Aucun profil d’appareil ne s’appelle « … ». | Créez d’abord le profil, ou laissez la colonne vide pour le profil par défaut. |
| Un appareil nommé « … » existe déjà. | Choisissez « ignorer les doublons » pour n’importer que les nouvelles lignes, ou « mettre à jour » pour modifier les appareils existants. |
| Un import ne modifie pas le numéro de série d’un appareil existant. | Les numéros de série sont figés. |
| Le profil « … » n’autorise pas … | Le profil n’autorise pas ce type d’identifiant. Choisissez un autre profil ou un autre type d’identifiant. |
| Un appareil avec ce numéro de série est déjà enregistré. | Une unité sous licence s’ajoute en la revendiquant, et non par import. |
| Ce nom d’utilisateur MQTT est déjà utilisé. | Les noms d’utilisateur sont uniques sur la plateforme. |
La limite d’appareils de votre forfait est vérifiée pour l’ensemble du fichier avant toute écriture : un fichier qui ne tient pas est refusé en entier, avec les chiffres.
Ce que change une mise à jour
Une mise à jour modifie le libellé, le type, le profil, l’adresse MAC et les attributs, et conserve les anciennes valeurs pour l’annulation. Elle ne modifie jamais un numéro de série ni un identifiant (« L’identifiant d’un appareil existant n’est pas modifié par un import ; renouvelez-le depuis la page de l’appareil. »). Réimporter le même fichier est sans risque : rien n’est créé deux fois et aucun identifiant n’est recréé ; l’assistant signale que ce fichier exact a déjà été importé.
Télécharger les identifiants
Après un import ayant ajouté des appareils, l’étape Résultat propose Une étape de plus : Télécharger les identifiants des nouveaux appareils. « Les jetons d’accès et mots de passe MQTT des appareils ajoutés par cet import, dans un fichier téléchargeable une seule fois, dans les 15 minutes suivant l’import. Conservez-le en lieu sûr : il n’est pas réaffiché. »
- Seule la personne ayant lancé l’import peut le télécharger.
- Après le téléchargement, ou après 15 minutes, il n’est plus disponible (« Terminé. Cette opération ne peut pas être répétée. »).
- Un appareil dont le fichier a été perdu reçoit de nouveaux identifiants depuis sa propre page, avec Régénérer le secret.
Annuler
L’étape Résultat et la liste des imports proposent Annuler cet import : « Les enregistrements ajoutés sont supprimés et les enregistrements modifiés sont rétablis dans leur état précédent. » Pour les appareils :
- un appareil créé n’est supprimé que s’il ne s’est jamais connecté,
- un appareil mis à jour est rétabli à partir des valeurs qu’il avait avant l’import.
Les lignes qui ne peuvent pas être rétablies sont comptées (« n lignes n’ont pas pu être rétablies. »).