Documentation sur Oracle Cloud Infrastructure

Scénario : Envoi de données structurées dans un format par défaut à l'aide de MQTT

Consultez ce scénario pour savoir comment créer un modèle de jumeau numérique pour recevoir des données de télémétrie historiques à partir d'un oxymètre de pouls à l'aide de MQTT et comment afficher les données IoT dans APEX.

  1. Créer des spécifications DTDL pour un modèle Digital Twin
  2. Créer un modèle jumeau numérique pour un oxymètre de pouls
  3. Créer un adaptateur jumeau numérique par défaut
  4. Créer une instance de jumeau numérique
  5. Publier des données à l'aide de MQTTX
  6. Voir vos données IoT dans APEX
  7. Publier des messages à l'aide de MQTTX
  8. Interroger les données d'instantané IoT dans APEX

Étape 1 : Créer des spécifications DTDL pour un modèle Digital Twin

Définissez une spécification de modèle jumeau numérique dans laquelle seul l'oxymètre d'impulsion est marqué comme étant historique.

Enregistrez-le en tant que fichier texte à référencer à l'étape suivante pour créer le modèle de jumeau numérique en fonction de ces spécifications.

basé sur les spécifications DTDL v3.

{
  "@context": [
    "dtmi:dtdl:context;3",
    "dtmi:dtdl:extension:historization;1"
  ],
  "@id": "dtmi:com:oracle:example:health:po;1",
  "@type": "Interface",
  "displayName": "Pulse Oximeter",
  "description": "This is digital twin model for pulse oximeter",
  "contents": [
    {
      "name": "pulse",
      "displayName": "Heart Rate",
      "@type": [
        "Telemetry",
        "Historized"
      ],
      "schema": "integer"
    },
    {
      "name": "so2",
      "displayName": "Oxygen Saturation",
      "@type": "Telemetry",
      "schema": "integer"
    }
  ]
}

Étape 2 : Créer un modèle jumeau numérique pour un oxymètre de pouls

Créez un modèle jumeau numérique pour un oxymètre d'impulsion et remplacez le <path-to-definition-file> par l'emplacement du fichier qui définit les spécifications du modèle numérique d'oxymètre d'impulsion de l'étape précédente.

Pour plus d'informations sur le référencement de fichiers, voir Utilisation d'un fichier JSON pour les entrées complexes. 

oci iot digital-twin-model create --iot-domain-id <iot-domain-OCID> --spec <path-to-definition-file>

Exemple de réponse :

{
  "data": {
    "defined-tags": {
      "Oracle-Tags": {
        "CreatedBy": "default/user@oracle.com",
        "CreatedOn": "2025-08-17T14:23:03.379Z"
      }
    },
    "description": "This is digital twin model for pulse oximeter",
    "display-name": "Pulse Oximeter",
    "freeform-tags": {},
    "id": "<digital-twin-OCID>",
    "iot-domain-id": "<iot-domain-OCID>",
    "lifecycle-state": "ACTIVE",
    "spec-uri": "dtmi:com:oracle:example:health:po;1",
    "system-tags": {},
    "time-created": "2025-08-17T14:23:03.449000+00:00",
    "time-updated": "2025-08-17T14:23:03.449000+00:00"
  },
  "etag": "<unique-id>"
}

Étape 3 : Créer un adaptateur de jumeau numérique par défaut

Utilisez la commande oci iot digital-twin-adapter create pour créer un adaptateur jumeau numérique par défaut pour le modèle jumeau numérique oxymètre d'impulsion. Cet exemple montre comment créer un adaptateur jumeau numérique par défaut qui ne le spécifie pas sans spécifier inbound-envelope ou envelope-mapping. Par conséquent, les données sont envoyées dans le format par défaut de l'appareil.

Si le mappage d'enveloppe n'est pas spécifié et contient un timeObserved, receivedTime est utilisé en tant que valeur timeObserved. 

oci iot digital-twin-adapter create --iot-domain-id <iot-domain-OCID> --digital-twin-model-spec-uri "dtmi:com:oracle:example:health:po;1" --display-name "<your-pulse-oximeter-name>" --description "<this-is-digital-twin-adapter-for-pulse-oximeter>"
Exemple de réponse indiquant les valeurs des données utiles de l'appareil et du domaine IoT associé, du modèle de jumeau numérique, de l'adaptateur de jumeau numérique et de l'URI DTMI.
{
  "data": {
    "defined-tags": {
      "Oracle-Tags": {
        "CreatedBy": "default/user@oracle.com",
        "CreatedOn": "2025-08-17T14:25:51.190Z"
      }
    },
    "description": "<this-is-digital-twin-adapter-for-pulse-oximeter>"
    "digital-twin-model-id": "<iot-digital-twin-model-OCID>",
    "digital-twin-model-spec-uri": "dtmi:com:oracle:example:health:po;1",
    "display-name": "Pulse Oximeter",
    "freeform-tags": {},
    "id": "<iot-digital-twin-adapter-OCID>",
    "inbound-envelope": {
      "envelope-mapping": {
        "time-observed": "$.time"
      },
      "reference-endpoint": "/",
      "reference-payload": {
        "data": {
          "pulse": 0,
          "so2": 0,
          "time": "2025-08-17T14:25:52.184012284Z"
        },
        "data-format": "JSON"
      }
    },
    "inbound-routes": [
      {
        "condition": "*",
        "description": "Default condition",
        "payload-mapping": {
          "$.pulse": "$.pulse",
          "$.so2": "$.so2"
        },
        "reference-payload": null
      }
    ],
    "iot-domain-id": "<iot-domain-OCID>",
    "lifecycle-state": "ACTIVE",
    "system-tags": {},
    "time-created": "2025-08-17T14:25:52.186000+00:00",
    "time-updated": "2025-08-17T14:25:52.186000+00:00"
  },
  "etag": "<unique-id>"
}

Étape 4 : Créer une instance de jumeau numérique

Utilisez cette commande oci iot digital-twin-instance create pour créer une instance de jumeau numérique.

Remplacez <iot-domain-OCID> et <iot-digital-twin-adapter-OCID> pour associer cette instance de jumeau numérique aux ressources IoT connexes créées au cours des étapes précédentes.

Remplacez <vault-secret-OCID> par une clé secrète de chambre forte créée dans la même région que l'instance de jumeau numérique. Pour plus d'informations, voir Création d'une clé secrète. 

oci iot digital-twin-instance create --iot-domain-id <iot-domain-OCID> --digital-twin-adapter-id <iot-digital-twin-adapter-OCID> --auth-id <vault-secret-OCID> --display-name "<Pulse Oximeter 1>"
Cet exemple de réponse montre une instance de jumeau numérique avec l'adaptateur jumeau numérique associé, le modèle de jumeau numérique, y compris l'URI DTMI.
{
  "data": {
    "auth-id": "<vault-secret-OCID>",
    "defined-tags": {
      "Oracle-Tags": {
        "CreatedBy": "default/user@oracle.com",
        "CreatedOn": "2025-08-17T14:39:44.292Z"
      }
    },
    "description": null,
    "digital-twin-adapter-id": "<iot-digital-twin-adapter-OCID>",
    "digital-twin-model-id": "<iot-digital-twin-model-OCID>",
    "digital-twin-model-spec-uri": "dtmi:com:oracle:example:health:po;1",
    "display-name": "Pulse Oximeter 1",
    "external-key": "<unique-id>",
    "freeform-tags": {},
    "id": "<iot-digital-twin-instance-OCID>",
    "iot-domain-id": "<iot-domain-OCID>",
    "lifecycle-state": "ACTIVE",
    "system-tags": {},
    "time-created": "2025-08-17T14:39:45.238000+00:00",
    "time-updated": "2025-08-17T14:39:45.238000+00:00"
  },
  "etag": "<unique-id>"
}

Étape 5 : Publier des données à l'aide de MQTTX

  1. Installez MQTTX.
    https://mqttx.app/docs/cli/downloading-and-installation
  2. Configurer MQTTX.

    Remplacez <device-host-from-iot-domain>.

    Remplacez <external-key> à partir de la réponse de l'instance de jumeau numérique.

    mqttx init
? Select MQTTX CLI output mode Text
? Select the default MQTT protocol MQTTS
? Enter the default MQTT broker host <device-host-from-iot-domain>
? Enter the default MQTT port 8883
? Enter the maximum reconnect times for MQTT connection 10
? Enter the default username for MQTT connection authentication <external-key>
? Enter the default password for MQTT connection authentication <auth-id-secret-value>
Configuration file created/updated at /Users/<user-name>/.mqttx-cli/config
  3. Valider la connexion.
    mqttx conn -h <data-host> -u <external-key> -P '<vault-secret-value>'
  4. publication des données-échantillons;
    Note

    -u et -P ne sont requis que s'ils sont définis comme valeur par défaut dans mqtt init.

Étape 6 : Voir vos données IoT dans APEX

Si vous voulez voir vos données IoT dans APEX, vous devez configurer la connexion à APEX.

Une fois la configuration configurée, vous pouvez suivre les étapes suivantes pour voir votre schéma de base de données IoT dans APEX :

  1. Allez à l'URL APEX avec l'ID abrégé du groupe de domaines à partir de l'hôte de données : 
    https://<domain-group-short-id-from-data-host>.data.iot.<region>.oci.oraclecloud.com/ords/r/apex
  2. Utilisez l'ID court de domaine provenant de l'hôte de l'appareil pour vous connecter à APEX : 
    device-host:<domain-short-id-from-device-host>.device.iot.<region>.oci.oraclecloud.com
    Dans APEX, connectez-vous à l'aide de :

  3. Allez à Atelier SQL. Utilisez des commandes SQL pour interroger vos données IoT. 

    select * from <iot-domain-short-id-from-device-host>__IOT.SNAPSHOT_DATA where digital_twin_instance_id='<iot-digital-twin-instance-OCID>';

    
DIGITAL_TWIN_INSTANCE_ID	        CONTENT_PATH	VALUE	TIME_OBSERVED
<iot-digital-twin-instance-OCID>	so2	           95	  17-AUG-25 03.15.56.000205 PM
<iot-digital-twin-instance-OCID>	pulse	        75	  17-AUG-25 03.15.56.000205 PM

    select * from <iot-domain-short-id-from-device-host>__IOT.HISTORIZED_DATA where digital_twin_instance_id='ocid1.iotdigitaltwininstance.oc1.<region>.<unique-id>';

    
ID	DIGITAL_TWIN_INSTANCE_ID	        CONTENT_PATH	VALUE	TIME_OBSERVED
87	<iot-digital-twin-instance-OCID>	pulse	        75	  17-AUG-25 03.15.56.000205 PM

Étape 7 : Publier des messages à l'aide de MQTTX

Publiez à nouveau pour confirmer qu'il est connecté et que le message est publié.

Lorsque vous avez créé l'instance de jumeau numérique à l'étape précédente, si vous avez spécifié la clé secrète de chambre forte comme ID authentification, vous pouvez obtenir le contenu de cette clé secrète stockée dans une chambre forte OCI et remplacer <vault-secret-content> par le contenu de la clé secrète.

mqttx pub -t "/data" -m '{ "pulse": 76, "so2": 94}' -u <external-key> -P '<vault-secret-content>'

Étape 8 : Interroger les données d'instantané IoT dans APEX

  1. Dans APEX, utilisez cet énoncé pour interroger les données d'instantané. Notez les deux traits de soulignement dans le nom du schéma.
    select * from <iot-domain-short-id-from-device-host>__IOT.SNAPSHOT_DATA where digital_twin_instance_id='<iot-digital-twin-instance-ocid>';
  2. Consultez les dernières valeurs connues mises à jour pour chaque instance de jumeau numérique. 
    DIGITAL_TWIN_INSTANCE_ID	CONTENT_PATH	VALUE	TIME_OBSERVED
ocid1.iotdigitaltwininstance.oc1.<region>.<unique-id>	so2	  94	17-AUG-25 03.22.34.000753 PM
ocid1.iotdigitaltwininstance.oc1.<region>.<unique-id>	pulse	76	17-AUG-25 03.22.34.000753 PM
  3. Dans APEX, utilisez cette interrogation d'énoncé pour les données historiques.
    select * from <iot-domain-short-id-from-device-host>__IOT.HISTORIZED_DATA where digital_twin_instance_id='<iot-digital-twin-instance-OCID>';
  4. Observez seulement l'oxymètre d'impulsion montre des données historiques de séries chronologiques, en raison seulement de l'oxymètre d'impulsion marqué comme historisé dans le modèle de jumeau numérique de l'étape précédente.
    
ID	DIGITAL_TWIN_INSTANCE_ID              CONTENT_PATH	VALUE	TIME_OBSERVED
87	<iot-digital-twin-instance-OCID>	pulse	       75	   17-AUG-25 03.15.56.000205 PM
88	<iot-digital-twin-instance-OCID>	pulse	       76	   17-AUG-25 03.22.34.000753 PM

Étape 9 : Utilisation de la trousse SDK

Vérifiez cette simulation avancée des données que vous pouvez utiliser en tant que fichier JavaScript dans la trousse SDK Internet of Things.
/**
 * MQTTX Scenario file example
 *
 * This script generates random pulse and so2 to simulate pulse oximeter.
 */
function generator(faker, options) {
  return {
    // If no topic is returned, use the topic in the command line parameters.
    // Topic format: 'mqttx/simulate/myScenario/' + clientId,
    message: JSON.stringify({
      pulse: faker.number.int({ min: 60, max: 120 }), // Generate a random pulse between 60 and 120.
      so2: faker.number.int({ min: 90, max: 100 }), // Generate a random so2 between 90 and 100.
    })
  }
}
// Export the scenario module
module.exports = {
  name: 'Pulse Oximeter Scenario', // Name of the scenario
  generator, // Generator function
}
Exemple utilisant la commande mqttx simulate et référençant le fichier.
mqttx simulate --file <path-to-above-script-file>  -u <external-key> -P '<vault-secret-content>'
❯  Starting publish simulation, scenario: Pulse Oximeter Scenario, connections: 1, req interval: 10ms, message interval: 1000ms
✔  [1/1] - Connected
✔  Created 1 connections in 1.198s
Published total: 10, message rate: 1/s
^C after 10 (or how much every you want)

Étape 10 : Interroger les données IoT dans APEX

  1. Dans APEX, vous pouvez maintenant interroger les données d'instantané pour l'oxymètre d'impulsion. 
    select * from <iot-domain-short-id>__IOT.SNAPSHOT_DATA where digital_twin_instance_id  = 'ocid1.iotdigitaltwininstance.oc1.<region>.<unique-id>';

    ocid1.iotdigitaltwininstance.oc1.<region>.<unique-id>	so2	90	17-AUG-25 03.29.19.000429 PM
ocid1.iotdigitaltwininstance.oc1.<region>.<unique-id>	       pulse	90	17-AUG-25 03.29.19.000429 PM
  2. interrogation des données historiques;
    select * from <iot-domain-short-id>__IOT.HISTORIZED_DATA where digital_twin_instance_id  = 'ocid1.iotdigitaltwininstance.oc1.<region>.<unique-id>';
  3. Observez les données de série chronologique de l'oxymètre de pouls.
    
ID	DIGITAL_TWIN_INSTANCE_ID	        CONTENT_PATH	VALUE	TIME_OBSERVED
94	<iot-digital-twin-instance-OCID>	pulse	       81	 17-AUG-25 03.29.15.000424 PM
96	<iot-digital-twin-instance-OCID>	pulse	       116	17-AUG-25 03.29.17.000430 PM
92	<iot-digital-twin-instance-OCID>	pulse	       105	17-AUG-25 03.29.13.000416 PM
89	<iot-digital-twin-instance-OCID>	pulse	       87	 17-AUG-25 03.29.10.000409 PM
97	<iot-digital-twin-instance-OCID>	pulse	       112	17-AUG-25 03.29.18.000429 PM
91	<iot-digital-twin-instance-OCID>	pulse	       73	 17-AUG-25 03.29.12.000411 PM
93	<iot-digital-twin-instance-OCID>	pulse	       70	 17-AUG-25 03.29.14.000413 PM
87	<iot-digital-twin-instance-OCID>	pulse	       75	 17-AUG-25 03.15.56.000205 PM
88	<iot-digital-twin-instance-OCID>	pulse	       76	 17-AUG-25 03.22.34.000753 PM
90	<iot-digital-twin-instance-OCID>	pulse	       74	 17-AUG-25 03.29.11.000409 PM