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 spécifier comment extraire les métadonnées des données utiles de l'appareil. Pour extraire la valeur à $.time du JSON entrant et la mapper au champ timeObserved dans le modèle de jumeau numérique. Ces mappages vous permettent d'extraire des métadonnées spécifiques telles que des horodatages à l'aide d'expressions JQ.

   Cet exemple présente le point d'extrémité du périphérique, un exemple de données utiles et un mappage d'enveloppe entrante qui applique des expressions JQ pour extraire ou remodeler les données.

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

2. Créez un fichier file://inbound-routes.json pour définir comment des données utiles spécifiques à partir de messages d'appareil sont mappées et acheminées vers votre instance de jumeau numérique.

   Chaque route comprend une condition correspondant au point d'extrémité, une structure de données utiles de référence et des instructions de mappage pour le transfert ou la transformation de valeurs.

   Cet exemple montre 2 conditions de données utiles définies.
   Note
   
   Le nombre maximal de routes entrantes autorisées est de 128.

   [
     {
       "condition": "${endpoint(2) == \"heartbeat\"}",
       "reference-payload": {
         "data": {
           "temp": 75,
           "hum": 62
         }
       },
       "payload-mapping": {
         "$.temperature": "$.data.temp",
         "$.humidity": "${.data.hum - 5}"
       }
     },
     {
       "condition": "${endpoint(2) == \"health\"}",
       "reference-payload": {
         "data": {
           "power": false,
           "batteryLevel": 60
         }
       },
       "payload-mapping": {
         "$.power": "$.data.power",
         "$.batteryLevel": "${.data.batteryLevel - 5}"
       }
     }
   ]

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 que vous souhaitez 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 mappage de données utiles personnalisé défini dans les options --inbound-envelope et --inbound-routes, en référençant les fichiers json, et un OCID d'adaptateur jumeau numérique spécifique associé à un modèle jumeau numérique spécifique avec un URI DTMI unique et un OCID de modèle 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 et <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 la clé secrète de la chambre forte à utiliser et remplacez <iot-domain-OCID> par l'OCID du domaine IoT pour votre environnement.

Si l'instance de jumeau numérique est configurée pour recevoir des données d'appareil, vous devez utiliser le paramètre d'ID authentification avec une clé secrète de chambre forte ou un OCID de certificat, afin que le jumeau numérique puisse s'authentifier. Pour ce faire, créez une clé secrète ou créez un certificat dans la même région et la même location que toutes les autres ressources IoT connexes.

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": "<vault-secret-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 des HTTP. Vous pouvez également utiliser MQTT et MQTT sur WebSockets. Pour des exemples spécifiques, voir 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>';

Ou utilisez cet énoncé SQL pour voir les données de télémétrie rejected. Remplacez <domain-short-id-from-device-host> par l'ID abrégé de domaine pour votre domaine IoT et <iot-digital-twin-OCID> par l'OCID du jumeau numérique à partir duquel vous voulez voir les données rejetées :

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

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