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

Topics

Les topics sont les canaux par lesquels transitent les données de votre projet. Cette page vous montre avec quels topics un projet démarre, comment créer les vôtres, comment recevoir les flux d'événements de la plateforme, tels que les alertes, et comment les messages des appareils arrivent sur un topic.

Le chemin des données d'un appareil : l'appareil publie sur ses topics MQTT, son registre achemine chaque message vers un topic du projet (ici …/events/engine arrive sur un topic que vous avez créé, engine_readings), la plateforme ajoute l'état de connexion au topic des états, et les connecteurs, les fonctions cloud et les pipelines Insight consomment les topics

Comprendre le fonctionnement des topics

Chaque topic appartient à un projet et possède un type qui fixe le sens de ses messages :

Type Sens Ce qui y circule
telemetry Plateforme → vous Télémétrie des appareils (tout format, transmise telle quelle)
states Plateforme → vous États des appareils (clé/valeur)
custom_actions Vous → appareils Messages transmis aux appareils
dimension, fact Dans les deux sens Flux d'événements de la plateforme ; également utilisés comme entrées d'Insight

Chaque projet démarre avec trois topics par défaut, un pour chaque type destiné aux appareils : readings (télémétrie), states et custom_actions. Il existe au plus un topic par défaut par type ; définir un nouveau topic comme topic par défaut retire cette désignation au précédent.

L'API renvoie le nom complet de chaque topic, construit à partir du nom court que vous choisissez : regions.<region-id>.projects.<project-id>.topics.<name>. Vous ne fournissez jamais que le nom court.

Comprendre comment les données d'un appareil parviennent à un topic

Les appareils ne publient jamais directement sur les topics. Chaque registre possède des topics de registre qui associent un topic MQTT d'appareil à un topic du projet :

L'appareil publie sur Arrive sur
registries/<registry-id>/devices/<serial-number>/events Le topic de télémétrie par défaut du registre
registries/<registry-id>/devices/<serial-number>/events/<subtype> Le topic de télémétrie associé à <subtype>
registries/<registry-id>/devices/<serial-number>/states Le topic d'états par défaut du registre
registries/<registry-id>/devices/<serial-number>/states/<subtype> Le topic d'états associé à <subtype>

Dans l'autre sens, les messages d'un topic custom_actions parviennent aux appareils sur registries/<registry-id>/devices/<serial-number>/custom_actions[/<subtype>]. Consultez Topics MQTT et formats de messages pour la liste complète.

Lors de la création d'un registre, celui-ci reçoit un topic de registre par défaut pour chaque type, associé aux topics par défaut du projet. Les topics de registre par défaut ne peuvent pas être supprimés ; la réinitialisation des topics d'un registre les rétablit.

Un message de télémétrie sur un topic du projet encapsule la charge utile de l'appareil, encodée en base64, avec le numéro de série de l'appareil :

{"deviceId": "<serial-number>", "data": "<base64-payload>"}

Il contient également les en-têtes suivants : project_id, registry_id, serial_number, device_id, received_at (RFC 3339 avec nanosecondes) et device_parent_id pour les sous-appareils. La télémétrie envoyée via l'alternative HTTPS arrive dans la même enveloppe.

La plateforme ajoute également un état connection à chaque appareil, connected ou disconnected, en fonction de ses heartbeats et de son autre trafic (consultez Surveiller). Il arrive sur le topic des états avec les états que l'appareil signale lui-même.

Avant de commencer

Vous pouvez également effectuer toutes ces opérations depuis la page PubSub du Hub.

1. Lister les topics de votre projet

fun api v1 pub-sub list-pub-sub-topics --project-id <project-id>

Chaque topic comprend id, name, default_type, is_default, registry_topic_count et source (user pour les topics que vous avez créés, scoping pour les flux d'événements de la plateforme).

2. Créer votre propre topic

Les noms de topic comptent de 3 à 256 caractères : lettres ASCII, chiffres et traits de soulignement (pas de points).

fun api v1 pub-sub store-pub-sub-topic --project-id <project-id> \
  --body '{"name": "engine_readings", "default_type": "telemetry", "is_default": false}'

La requête brute :

POST https://api.fundamentum-iot.com/v1/projects/<project-id>/pub-sub-topics
Authorization: Bearer $TOKEN
Content-Type: application/json

{"name": "engine_readings", "default_type": "telemetry", "is_default": false}

Vous pouvez créer des topics telemetry, states et custom_actions. Les topics dimension et fact ne sont créés que par l'activation d'un flux d'événements de la plateforme (étape 4).

3. Acheminer les messages des appareils vers votre topic

Associez un sous-type d'un registre au topic que vous avez créé. Les appareils publient alors sur .../events/engine pour atteindre engine_readings :

fun api v1 registry store-registry-topic --project-id <project-id> --registry-id <registry-id> \
  --body '{"registry_id": <registry-id>, "pub_sub_topic_id": <topic-id>, "type": "telemetry", "sub_type_name": "engine"}'

Pour rétablir l'association par défaut d'un registre :

fun api v1 registry reset-registry-topics --project-id <project-id> --registry-id <registry-id>

Un topic ne peut pas être supprimé tant que des topics de registre y font encore référence ; supprimez d'abord ces associations.

4. Recevoir les flux d'événements de la plateforme

La plateforme publie ses propres événements (par exemple les alertes) sur des flux communs à toute la plateforme. L'activation d'un flux pour votre projet copie en temps réel chaque événement concernant votre projet vers un topic dédié de votre projet.

Listez les flux disponibles :

fun api v1 pub-sub list-scopeable-topics --project-id <project-id>

Chaque entrée comporte un name, un type (dimension ou fact) et, une fois le flux activé, le scoped_name de la copie de votre projet.

Activez-en un, par exemple alerts :

fun api v1 pub-sub scope-pub-sub-topic --project-id <project-id> --scopeable-topic alerts

L'activation est idempotente. Le topic du projet est nommé regions.<region-id>.projects.<project-id>.<type>.<stream> et conserve la clé, la valeur et les en-têtes de chaque événement.

Pour cesser de recevoir les événements :

fun api v1 pub-sub unscope-pub-sub-topic --project-id <project-id> --scopeable-topic alerts

La désactivation conserve le topic du projet, ce qui vous permet de le réactiver ultérieurement. Les événements publiés pendant que le flux est inactif ne sont pas copiés.

Prochaines étapes