Scénario : envoi de données structurées dans un format personnalisé à l'aide de HTTP

1. Définissez une enveloppe entrante file://inbound-envelope.json pour indiquer comment extraire les métadonnées de la charge utile de l'appareil. Pour extraire la valeur dans $.time du JSON entrant et la mettre en correspondance avec le champ timeObserved dans le modèle de jumeau numérique. Ces mappings vous permettent d'extraire des métadonnées spécifiques telles que les horodatages à l'aide d'expressions JQ.

   Cet exemple illustre l'adresse de périphérique, un exemple de charge utile et un mapping d'enveloppes entrantes qui applique des expressions JQ pour extraire ou remodeler les données.

   {
     "reference-endpoint": "telemetry/health",
     "reference-payload": {
       "data-format": "JSON",
       "data": {
         "time": "<timestamp>",
         "data": {
           "temp": 0,
           "hum": 0,
           "power": false,
           "batteryLevel": 0
         }
       }
     },
     "envelope-mapping": {
       "time-observed": "$.time"
     }
   }

2. Créez un fichier file://inbound-routes.json pour définir la façon dont les données de charge utile spécifiques des messages d'appareil sont mises en correspondance et acheminées vers votre instance de jumeau numérique.

   Chaque route inclut une condition correspondant à l'adresse, une structure de charge utile de référence et des instructions de mise en correspondance pour le transfert ou la transformation de valeurs.

   Cet exemple présente 2 conditions de charge utile définies.
   Remarque
   
   Le nombre maximal d'itinéraires entrants autorisé est de 128.

   [
     {
       "condition": "${endpoint(2) == \"heartbeat\"}",
       "description": "heartbeat",
       "payload-mapping": {
         "$.humidity": "${.hum-1}",
         "$.temperature": "$.temp"
       },
       "reference-payload": {
         "data": {
           "hum": 62,
           "temp": 75
         },
         "data-format": "JSON"
       }
     },
     {
       "condition": "${endpoint(2) == \"health\"}",
       "description": "health",
       "payload-mapping": {
         "$.humidity": "${.hum-1}",
         "$.temperature": "$.temp"
       },
       "reference-payload": {
         "data": {
           "batteryPercentage": 60,
           "on": false
         },
         "data-format": "JSON"
       }
     }
   ]

3. Utilisez la commande oci iot digital-twin-adapter create pour créer un adaptateur jumeau numérique. Remplacez <iot-domain-OCID> par l'OCID de votre domaine IoT et remplacez <dtmi:com:oracle:example:hvac> par l'URI DTMI par l'URI DTMI du modèle de jumeau numérique à associer à cet adaptateur de jumeau numérique.

   L'exemple suivant utilise le paramètre URI DTMI pour associer le modèle de jumeau numérique. Vous pouvez également utiliser le paramètre --digital-twin-model-id avec <digital-twin-model-OCID> pour le modèle de jumeau numérique à associer à cet adaptateur de jumeau numérique.

   Référencez les fichiers file://inbound-enevelop.json et file://inbound-enevelop.json créés à l'étape précédente.

   oci iot digital-twin-adapter create --iot-domain-id <iot-domain-OCID> --digital-twin-model-spec-uri 'dtmi:com:oracle:example:hvac;1' --inbound-envelope <file://inbound-enevelop.json> --inbound-routes <file://inbound-routes.json>

   Cet exemple de réponse présente un mapping de charge utile personnalisé défini dans les options --inbound-envelope et --inbound-routes, en référençant les fichiers json, ainsi qu'un OCID d'adaptateur de jumeau numérique spécifique associé à un modèle de jumeau numérique spécifique avec un URI DTMI unique et un OCID de modèle de jumeau numérique :

   dtmi:com:oracle:example:core:hvac:sp;1

   {
     "data": {
       "defined-tags": {
         "Oracle-Tags": {
           "CreatedBy": "default/user@oracle.com",
           "CreatedOn": "2025-09-11T06:09:27.323Z"
         }
       },
       "description": null,
       "digital-twin-model-id": "<iot-digital-twin-model-OCID>",
       "digital-twin-model-spec-uri": "dtmi:com:oracle:example:hvac;1",
       "display-name": "<digital-twin-adapter-display-name>",
       "freeform-tags": {},
       "id": "<iot-digital-twin-adapter-OCID>",
       "inbound-envelope": {
         "envelope-mapping": {
           "time-observed": "$.time"
         },
         "reference-endpoint": "telemetry/health",
         "reference-payload": {
           "data": {
             "time": "2025-09-11T06:09:27.878106Z"
           },
           "data-format": "JSON"
         }
       },
       "inbound-routes": [
         {
           "condition": "${endpoint(2) == \"heartbeat\"}",
           "description": null,
           "payload-mapping": {
             "$.humidity": "${.hum-1}",
             "$.temperature": "$.temp"
           },
           "reference-payload": {
             "data": {
               "hum": 62,
               "temp": 75
             },
             "data-format": "JSON"
           }
         },
         {
           "condition": "${endpoint(2) == \"health\"}",
           "description": null,
           "payload-mapping": {},
           "reference-payload": {
             "data": {
               "batteryPercentage": 60,
               "on": false
             },
             "data-format": "JSON"
           }
         }
       ],
       "iot-domain-id": "<iot-domain-OCID>",
       "lifecycle-state": "ACTIVE",
       "system-tags": {},
       "time-created": "2025-09-30T19:55:36.293000+00:00",
       "time-updated": "2025-09-30T19:55:36.293000+00:00"
     },
     "etag": "<unique-id>"
   }
   

Utilisez les paramètres oci iot digital-twin-instance create, <iot-domain-OCID> et <certificate-or-secret-OCID> requis pour créer une instance de jumeau numérique. Remplacez <certificate-or-secret-OCID> par l'OCID de clé secrète de coffre à utiliser et remplacez <iot-domain-OCID> par l'OCID du domaine IoT de votre environnement.

Si l'instance de jumeau numérique est configurée pour recevoir des données de périphérique, vous devez utiliser le paramètre d'ID d'authentification avec une clé secrète de coffre ou un OCID de certificat, afin que le jumeau numérique puisse s'authentifier. Pour cela, créez une clé secrète. Pour la production, l'instance de jumeau numérique doit utiliser un certificat mTLS pour l'authentification.

Cet exemple utilise l'option --display-name. Remplacez <your-digital-twin-instance-name> par un nom convivial pour votre instance de jumeau numérique.

oci iot digital-twin-instance create --iot-domain-id <iot-domain-OCID> --display-name <your-digital-twin-instance-name> --auth-id <certificate-or-secret-OCID> --digital-twin-adapter-id <digital-twin-adapter-OCID>

dtmi:com:oracle:example:hvac;1

{
  "data": {
    "auth-id": "<secret-or-certificate-OCID>",
    "defined-tags": {
      "Oracle-Tags": {
        "CreatedBy": "default/user@oracle.com",
        "CreatedOn": "2025-08-14T17:41:11.973Z"
      }
    },
    "description": null,
    "digital-twin-adapter-id": "<iot-digital-twin-adapter-OCID>",
    "digital-twin-model-id": "<digital-twin-model-OCID>",
    "digital-twin-model-spec-uri": "dtmi:com:oracle:example:hvac;1",
    "display-name": "<your-digital-twin-instance-name>",
    "external-key": "<digital-twin-instance-external-key>",
    "freeform-tags": {},
    "id": "<digital-twin-instance-OCID>",
    "iot-domain-id": "<iot-domain-OCID>",
    "lifecycle-state": "ACTIVE",
    "system-tags": {},
    "time-created": "2025-08-14T17:41:13.638000+00:00",
    "time-updated": "2025-08-14T17:41:13.638000+00:00"
  },
  "etag": "<unique-id>"
}

Cet exemple utilise HTTPs. Vous pouvez également utiliser MQTT et MQTT sur WebSockets. Pour obtenir des exemples spécifiques, reportez-vous à Scénarios.

curl -H "Authorization: Bearer <token>" \
     -X GET "https://<domain-group-short-id>.data.iot.<region>.oci.oraclecloud.com/ords/<domain-short-id>/20250531/rawData?q={\"$and\":[{\"digital_twin_instance_id\":\"<iot-digital-twin-OCID>\"}]}"

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

Vous pouvez également utiliser cette instruction SQL pour visualiser les données de télémétrie rejected. Remplacez <domain-short-id-from-device-host> par l'ID abrégé de domaine de votre domaine IoT et <iot-digital-twin-OCID> par l'OCID du jumeau numérique à partir duquel vous voulez visualiser les données rejetées :

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

select * from <domain-short-id-from-device-host>__IOT.HISTORIZED_DATA where digital_twin_id = '<digital-twin-OCID>';