DRAFT — Preliminary version, do not share. · Version préliminaire, ne pas partager.

Flux entrants

Les flux entrants font entrer des messages de vos systèmes dans un topic de projet, par exemple pour envoyer des commandes aux appareils ou pour alimenter Insight en données de référence. Cette page présente les deux voies d'entrée : votre broker MQTT publie dans la plateforme, ou vos systèmes envoient des messages par POST via HTTPS au moyen de la Public API.

Faire entrer et sortir vos données : vos systèmes publient dans les topics du projet

Fonctionnement des flux entrants

Les deux flux utilisent un connecteur avec un lien entrant ("ingoing": true). Le lien pointe vers un topic de projet de type custom_actions, dimension ou fact :

Les messages d'un topic custom_actions sont transmis à l'appareil ciblé sur registries/<registry-id>/devices/<serial-number>/custom_actions (voir MQTT topics and message formats).

Format des messages

Les deux flux acceptent le même message JSON :

{
  "device_id": 1234,
  "registry_id": 56,
  "version": "1.0.0",
  "headers": {"trace-id": "abc"},
  "data": "hello"
}
Champ Type Description
device_id integer Identifiant de l'appareil cible. Obligatoire et non nul pour les topics custom_actions, sinon le message est abandonné. Facultatif pour les autres types de topic.
registry_id integer Registre de l'appareil cible. Mêmes règles que pour device_id.
version string Version facultative, transmise en tant qu'en-tête.
headers object of strings En-têtes supplémentaires facultatifs. En cas de conflit de nom, la valeur de headers l'emporte.
data string Le corps du message livré sur le topic.

device_id, registry_id et version deviennent des en-têtes du message ; un identifiant absent ou égal à 0 est omis.

Avant de commencer

Publier depuis votre broker MQTT

  1. Créez un connecteur MQTT ou MQTTS vers votre broker, comme décrit dans Connectors.

  2. Créez un lien entrant. external_topic_name est le topic auquel Fundamentum s'abonne sur votre broker ; il ne peut pas être utilisé également par un lien sortant du même connecteur.

    fun api v1 pub-sub store-link --project-id <project-id> --connector-id <connector-id> \
  --body '{"pubsub_topic_id": <topic-id>, "external_topic_name": "plant/commands", "ingoing": true}'

  3. Publiez le message sur votre broker, par exemple avec Mosquitto :

    mosquitto_pub -h mqtt.example.com -p 8883 --cafile ca.pem --cert client.pem --key client.key \
  -t plant/commands \
  -m '{"device_id": <device-id>, "registry_id": <registry-id>, "data": "{\"led\":\"on\"}"}'

Envoyer un POST via HTTPS

  1. Créez un connecteur HTTPS. Pour un usage entrant, il suffit qu'il soit activé ; son host et son en-tête personnalisé s'appliquent aux liens sortants.

    fun api v1 pub-sub store-connector --project-id <project-id> --body '{
  "name": "erp-inbound",
  "adapter_type": 3,
  "is_enabled": true,
  "connection_string": "host=https://erp.example.com"
}'

  2. Créez un lien entrant vers le topic cible. external_topic_name n'est pas utilisé par les liens entrants HTTPS.

    fun api v1 pub-sub store-link --project-id <project-id> --connector-id <connector-id> \
  --body '{"pubsub_topic_id": <topic-id>, "external_topic_name": "erp-commands", "ingoing": true}'

    Notez l'id du lien dans la réponse.

  3. Publiez un message :

    fun api v1 pub-sub publish-to-link --project-id <project-id> --connector-id <connector-id> --link-id <link-id> \
  --body '{"device_id": <device-id>, "registry_id": <registry-id>, "data": "{\"led\":\"on\"}"}'

    La requête brute, que n'importe quel client HTTP peut envoyer avec un bearer token :

    POST https://api.fundamentum-iot.com/v1/projects/<project-id>/connectors/<connector-id>/links/<link-id>/publish
Authorization: Bearer $TOKEN
Content-Type: application/json

{"device_id": 1234, "registry_id": 56, "data": "{\"led\":\"on\"}"}

    Un appel réussi renvoie :

    {"status": "success"}

    L'API répond 422 si le connecteur n'est pas un connecteur HTTPS activé ou si le lien n'est pas entrant.

Étapes suivantes