Wrapper d’API Senet vers ThingPark legacy deprecated

Cette documentation définit comment le wrapper d’API Senet vers ThingPark peut être utilisé pour gérer les capteurs et les passerelles provisionnés dans ThingPark, à l’aide de l’ancienne signature Senet.

Note importante

Les API Senet sont maintenant obsolètes, ce wrapper fournit aux clients une approche temporaire rétrocompatible. Néanmoins, Netmore recommande fortement d’intégrer aux API ThingPark natives dès que possible.

Mappage de domaine

Pour utiliser le wrapper d’API, le chemin du point de terminaison Senet doit être précédé par le nom d’hôte ThingPark.
Par exemple, en Amérique du Nord, le nom d’hôte ThingPark est thingparkenterprise.us.actility.com, donc le chemin complet du point de terminaison pour récupérer la liste des passerelles devient GET https://thingparkenterprise.us.actility.com/rest/integration/bstn/details.

Authentification

Les clients s’authentifient auprès du wrapper au moyen de clés d’API, puis le wrapper associe en interne la clé d’API client au compte de service ThingPark.

prudence

De nouvelles clés doivent être émises après la migration de Senet vers ThingPark. Contactez l’équipe support Netmore si vous n’avez pas encore reçu vos nouvelles clés d’API.

Gestion des passerelles

Pour permettre la rétrocompatibilité lors du déploiement de passerelles (par exemple lors du paramétrage de l’emplacement ou du nom, ou de l’interrogation de la liste des BS par API), le wrapper prend en charge les points de terminaison suivants de l’ancienne API Senet :

• POST /rest/integration/bstn/deploy
• GET /rest/integration/bstn/details

Tous les autres points de terminaison de gestion de réseau hérités pris en charge par Senet ne sont pas pris en charge dans ce wrapper.

note

Tout point de terminaison utilisé pour provisionner de nouvelles passerelles est hors du périmètre de ce wrapper. Les API ThingPark natives doivent être utilisées dans ce cas. Pour plus d’informations, voir le Tutoriel.

Mappage POST /rest/integration/bstn/deploy

Le wrapper prend en charge la mise à jour des métadonnées de passerelle dans ThingPark, telles que le nom, l’emplacement et l’adresse statique.
Le point de terminaison Senet hérité est documenté ici.

Cependant, en raison de différences dans le modèle de data, le mappage de ce point de terminaison présente les limitations suivantes :

• Les informations radius ne peuvent pas être stockées dans ThingPark.
• height est stocké comme adminAlt dans ThingPark ; ce champ indique la hauteur au-dessus du niveau de la mer, et non la hauteur au-dessus du sol. Le wrapper gère la conversion d’unités entre pieds et mètres.

Mappage GET /rest/integration/bstn/details

Le wrapper prend en charge la récupération de la liste des passerelles enregistrées sous le compte client.
Le point de terminaison Senet hérité est documenté ici.

Notes sur le mappage de requête

Requête Senet	Notes
status=any	Retourne toutes les passerelles sous le compte client.
status=alert	Retourne les passerelles avec au moins une alarme non effacée et non acquittée.
status=connIssue	Retourne les passerelles avec des problèmes de connexion de backhaul. RF_ERROR n’est pas inclus.

Notes sur le mappage de réponse

Champ Senet	Transformation
alertLevel	Aucun mappage fiable n’est défini : alertLevel décrit la configuration d’alerte, et non la sévérité actuelle de l’alarme. Le champ n’est pas retourné.
location	{ latitude, longitude } à partir de l’emplacement administratif. Null lorsque locationType != 1.
gpsLocation	Null lorsque locationType != 2, ce qui signifie qu’aucun emplacement GNSS embarqué n’est disponible depuis la passerelle.
gpsAltitude	Null lorsque locationType != 2, ce qui signifie qu’aucune altitude GNSS embarquée n’est disponible depuis la passerelle.
height	Altitude au-dessus du niveau de la mer. La valeur définie via POST /rest/integration/bstn/deploy est retournée telle quelle.
deltaTime	Aucune information équivalente de décalage d’horloge n’est disponible dans ThingPark. Le champ est retourné comme 0, ou null selon la politique de réponse applicable.

Les champs suivants sont omis de la réponse car ils n’ont pas de correspondance exacte dans le modèle de data ThingPark :

• radius
• antennaHeight, car le champ ThingPark associé est lié à l’objet antenne plutôt qu’à la passerelle elle‑même
• channelConfig, car la configuration de canal est définie par la RF region dans ThingPark

Gestion des capteurs

Le wrapper prend en charge les opérations de gestion de capteur héritées de Senet pour envoyer des downlink, exporter des capteurs, enregistrer et activer des capteurs, mettre à jour les informations de capteur, désactiver des capteurs et vérifier l’état des opérations en masse.

Les points de terminaison suivants sont pris en charge :

• POST /rest/integration/device/sendmsg
• GET /rest/integration/device/csvExport
• GET /rest/integration/device/jsonExport
• POST /rest/integration/device/register
• POST /rest/integration/device/registerandactivate
• POST /rest/integration/device/activate
• POST /rest/integration/device/deactivate
• POST /rest/integration/device/update
• GET /rest/integration/device/status

Les points de terminaison hérités suivants ne sont pas pris en charge :

• GET /rest/integration/mcastStatus
• POST /rest/integration/device/activateOne
• POST /rest/integration/device/deactivateOne
• GET /rest/integration/device/getmsgs
• POST /rest/integration/device/clearmsgs
• POST /rest/integration/device/exportAbp

Mappage POST /rest/integration/device/sendmsg

Le point de terminaison POST /rest/integration/device/sendmsg met en file d’attente un downlink applicatif pour un capteur LoRaWAN.

Le wrapper prend en charge :

• les downlink confirmés et non confirmés
• Ports applicatifs LoRaWAN de 1 à 225
• le vidage de la file de downlink existante du capteur avant d’ajouter le nouveau message, via clear=true
• validité du message configurée via timeoutMinutes

La payload fournie dans pdu doit être hexadécimale. Elle est transmise à ThingPark pour l’envoi vers le capteur.

En raison de différences de plate‑forme, les limitations suivantes s’appliquent :

• Les ports de 226 à 254 sont rejetés avec le code HTTP 400 car ThingPark prend en charge uniquement les ports applicatifs de 1 à 225.
• Le paramètre class spécifique à la requête est ignoré. La planification des downlink utilise la classe définie par le profil de capteur dans ThingPark.
• Le paramètre immediate spécifique à la requête est ignoré. Un comportement de temporisation de downlink équivalent, lorsqu’il est requis, est configuré sur l’abonnement réseau du capteur et ne peut pas être modifié pour une requête individuelle.
• Le msgId retourné est fourni uniquement pour la compatibilité de réponse. Il ne peut pas être utilisé avec getmsgs ou clearmsgs, qui ne sont pas pris en charge par ce wrapper.

Mappage GET /rest/integration/device/csvExport

Le point de terminaison GET /rest/integration/device/csvExport exporte tous les capteurs correspondants au format CSV. Le wrapper récupère l’ensemble complet des résultats, y compris les résultats répartis sur plusieurs pages ThingPark.

Les filtres suivants sont pris en charge :

Paramètre de requête Senet	Comportement
fields	Sélectionne et ordonne les colonnes de sortie.
state	Filtre les capteurs selon l’état de cycle de vie pris en charge. Utilisez ALL pour désactiver le filtrage par état.
contractId	Filtre les capteurs par abonnement réseau correspondant.
devEuis	Filtre par une liste de DevEUI séparée par des virgules.
appEui	Le compte client est déterminé par la clé d’API. Une valeur fournie ne sélectionne pas un autre compte client.
psrDays	Ignoré car l’historique équivalent du taux de succès de paquet par jour n’est pas disponible via ce mappage.

Si fields est omis, les colonnes par défaut sont devEui, contract, tags, state, lastHeardFrom et joinEui.

Les états de capteur pris en charge sont :

• REGISTERED
• DEACTIVATED
• ACTIVATED
• JOINED

Les limitations d’export suivantes s’appliquent :

• activationDate et deactivationDate sont retournés vides car les horodatages équivalents ne sont pas disponibles via ce mappage.
• Les champs de taux de succès de paquet demandés via psrDays sont retournés vides.
• Les champs demandés pour lesquels aucune valeur ThingPark équivalente n’existe sont retournés vides.

Mappage GET /rest/integration/device/jsonExport

Le point de terminaison GET /rest/integration/device/jsonExport fournit la même sélection de capteurs, le même filtrage, la même gestion d’état de cycle de vie et les mêmes limitations que csvExport, mais sérialise le résultat en JSON.

La réponse contient des métadonnées décrivant la requête d’export et un tableau data contenant les capteurs exportés. Les étiquettes de capteur sont retournées sous forme de tableau. Les champs sans valeur ThingPark équivalente, y compris activationDate et deactivationDate, sont retournés à null.

Mappage POST /rest/integration/device/register

Le point de terminaison POST /rest/integration/device/register crée des capteurs OTAA ou ABP sans activer leur abonnement réseau. Les capteurs résultants restent suspendus jusqu’à leur activation.

Pour les capteurs OTAA, le wrapper prend en charge :

• devEui
• appKey
• la sélection de profil de capteur via profId et les informations de capteur fournies
• joinEui facultatif
• latitude et longitude
• métadonnées
• étiquettes

Pour les capteurs ABP, le wrapper prend en charge :

• devEui
• devAddr
• nwkSKey
• appSKey facultatif
• sélection de profil de capteur
• latitude et longitude
• métadonnées
• étiquettes

prudence

Pour l’enregistrement ABP, devAddr et nwkSKey sont tous deux obligatoires. Une requête à laquelle manque l’une ou l’autre valeur est rejetée avec un code HTTP 400.

Un contractId fourni n’est pas appliqué lors de l’enregistrement. L’abonnement réseau est attaché lorsque le capteur est activé.

Mappage POST /rest/integration/device/registerandactivate

Le point de terminaison POST /rest/integration/device/registerandactivate crée des capteurs OTAA ou ABP et attache immédiatement leur abonnement réseau.

Les champs de capteur pris en charge et les exigences ABP sont les mêmes que pour register. En outre, contractId doit identifier un abonnement réseau valide. S’il est manquant ou ne peut pas être résolu, la requête est rejetée avec un code HTTP 400.

Mappage POST /rest/integration/device/activate

Le point de terminaison POST /rest/integration/device/activate active un capteur existant enregistré ou désactivé en attachant l’abonnement réseau identifié par contractId.

Le wrapper suppose OTAA par défaut. Pour activer un capteur ABP, l’appelant doit fournir le paramètre de requête non documenté actType=ABP.

La requête peut également mettre à jour les informations suivantes lors de l’activation :

• l’affectation de profil de capteur, le cas échéant
• latitude et longitude
• métadonnées
• étiquettes

Le capteur doit déjà exister, et contractId doit identifier un abonnement réseau valide. Dans le cas contraire, la requête échoue avec un code HTTP 404 ou 400, respectivement.

Mappage POST /rest/integration/device/deactivate

Le point de terminaison POST /rest/integration/device/deactivate désactive un capteur existant en détachant son abonnement réseau. Une fois suspendus dans ThingPark, les paquets provenant du capteur sont ignorés par le network server.

Le wrapper suppose OTAA par défaut. Pour désactiver un capteur ABP, l’appelant doit fournir le paramètre de requête non documenté actType=ABP.

Le capteur doit déjà exister. Les paramètres qui ne sont pas nécessaires à l’identification du capteur, y compris appEui, joinEui, contractId et profId, n’affectent pas la désactivation.

Mappage POST /rest/integration/device/update

Le point de terminaison POST /rest/integration/device/update met à jour les attributs mutables pris en charge des capteurs existants. La mise à jour ne modifie pas l’état d’activation du capteur ni son abonnement réseau.

Le wrapper suppose OTAA par défaut. Pour mettre à jour un capteur ABP, l’appelant doit fournir le paramètre de requête non documenté actType=ABP.

Le wrapper prend en charge la mise à jour de :

• appKey OTAA
• nwkKey OTAA, lorsque cela s’applique à la configuration du capteur
• latitude et longitude
• métadonnées
• étiquettes

Les valeurs liées au profil de capteur fournies via profId, devType, devClass ou fwVer ne sont pas appliquées par ce point de terminaison.

Les mises à jour de clés via ce point de terminaison s’appliquent uniquement aux capteurs OTAA. Le point de terminaison n’expose pas les champs de clés de session ABP nécessaires pour mettre à jour les clés d’un capteur ABP.

Opérations sur les étiquettes

Lorsque des étiquettes sont fournies, tagsOperation est requis et prend en charge les valeurs suivantes :

tagsOperation	Comportement
REPLACE	Remplace l’ensemble complet d’étiquettes par les étiquettes fournies. Un ensemble vide efface toutes les étiquettes.
APPEND	Ajoute les étiquettes fournies à l’ensemble d’étiquettes actuel du capteur.
DELETE	Supprime les étiquettes fournies de l’ensemble d’étiquettes actuel du capteur.

L’ensemble fourni effectif combine les étiquettes au niveau du capteur et les étiquettes au niveau de la requête.

Mappage GET /rest/integration/device/status

Les opérations d’enregistrement, d’activation, de désactivation et de mise à jour de capteur sont traitées de manière asynchrone. Leurs réponses initiales fournissent un reqId. Utilisez le point de terminaison GET /rest/integration/device/status pour interroger la tâche correspondante.

Le wrapper peut retourner les états de tâche suivants :

• QUEUED
• RUNNING
• DONE_SUCCESS
• DONE_FAILED

La réponse inclut le pourcentage d’achèvement, les compteurs d’opérations et les messages d’erreur disponibles par capteur.

Certains états de tâche Senet hérités n’ont pas d’équivalent dans ThingPark et ne sont pas retournés. Cela inclut les états d’initialisation, de pause, de reprise, d’annulation et de suppression.

note

L’état de tâche reste disponible uniquement tant que la notification ThingPark correspondante est conservée. Interrogez le point de terminaison de statut après avoir soumis une opération en masse et stockez tout résultat nécessaire pour référence ultérieure.

Opérations asynchrones et gestion des erreurs

Les points de terminaison suivants utilisent un traitement asynchrone :

• register
• registerandactivate
• activate
• deactivate
• update

Après une requête acceptée, utilisez le reqId retourné avec GET /rest/integration/device/status pour récupérer la progression et les résultats par capteur.

prudence

Le champ callback n’est pas pris en charge : le wrapper n’envoie jamais la fin d’une tâche vers une URL fournie par l’appelant. Interrogez GET /rest/integration/device/status pour obtenir le résultat de la tâche.

Le wrapper utilise le mappage général de codes HTTP suivant :

Code HTTP	Signification
400	Requête invalide ou valeur de champ non prise en charge.
403	Échec d’authentification ou d’autorisation.
404	Capteur ou tâche demandé introuvable.
501	L’opération demandée ou le mappage sémantique n’est pas pris en charge.
500	Erreur interne de traitement.

Pour les requêtes en masse, les erreurs de validation ou de traitement peuvent être signalées au niveau de la tâche via la réponse de statut plutôt que dans la réponse initiale d’acceptation.