Scenario: invio di dati strutturati in un formato personalizzato mediante HTTP

1. Definire un envelope in entrata file://inbound-envelope.json per specificare come estrarre i metadati dal payload del dispositivo. Per estrarre il valore in $.time dal file JSON in entrata e mapparlo al campo timeObserved nel modello gemello digitale. Questi mapping consentono di estrarre metadati specifici, ad esempio indicatori orari, utilizzando le espressioni JQ.

   Questo esempio mostra l'endpoint del dispositivo, un payload di esempio e un mapping dell'envelope in entrata che applica espressioni JQ per estrarre o rimodellare i dati.

   {
     "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. Creare un file file://inbound-routes.json per definire il modo in cui i dati del payload specifici dei messaggi dispositivo vengono mappati e instradati all'istanza digital twin.

   Ogni instradamento include una condizione che corrisponde all'endpoint, una struttura di payload di riferimento e istruzioni di mapping per il trasferimento o la trasformazione dei valori.

   Questo esempio mostra 2 condizioni di payload definite.
   Nota
   
   Il numero massimo di instradamenti in entrata consentiti è 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. Utilizzare il comando oci iot digital-twin-adapter create per creare un adattatore digital twin. Sostituire <iot-domain-OCID> con l'OCID per il dominio IoT e sostituire <dtmi:com:oracle:example:hvac> con l'URI DTMI con l'URI DTMI per il modello gemello digitale che si desidera associare a questo adattatore gemello digitale.

   Nell'esempio seguente viene utilizzato il parametro URI DTMI per associare il modello gemello digitale. In alternativa, è possibile utilizzare il parametro --digital-twin-model-id con <digital-twin-model-OCID> per il modello gemello digitale che si desidera associare a questo adattatore gemello digitale.

   Fare riferimento ai file file://inbound-enevelop.json e file://inbound-enevelop.json creati nel passo precedente.

   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>

   Questa risposta di esempio mostra un mapping di payload personalizzato definito nelle opzioni --inbound-envelope e --inbound-routes, facendo riferimento ai file json e a un OCID adattatore digital twin specifico associato a un modello digital twin specifico con un URI DTMI univoco e OCID modello digital twin:

   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>"
   }
   

Utilizzare i parametri richiesti oci iot digital-twin-instance create e <iot-domain-OCID> e <certificate-or-secret-OCID> per creare un'istanza gemella digitale. Sostituire <certificate-or-secret-OCID> con l'OCID segreto del vault che si desidera utilizzare e sostituire <iot-domain-OCID> con l'OCID per il dominio IoT per l'ambiente in uso.

Se l'istanza digital twin è impostata per ricevere i dati del dispositivo, è necessario utilizzare il parametro ID autenticazione con un segreto vault o un OCID certificato, in modo che il digital twin possa eseguire l'autenticazione. A tale scopo creare un segreto. Per la produzione, l'istanza digital twin deve utilizzare un certificato mTLS per l'autenticazione.

In questo esempio viene utilizzata l'opzione --display-name, sostituire <your-digital-twin-instance-name> con un nome riconoscibile dall'utente per l'istanza digital twin.

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>"
}

In questo esempio vengono utilizzati i protocolli HTTP. In alternativa, è possibile utilizzare MQTT e MQTT su WebSockets. Per esempi specifici, vedere Scenari.

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>';

Oppure utilizzare questa istruzione SQL per visualizzare i dati di telemetria rejected. Sostituire <domain-short-id-from-device-host> con l'ID breve del dominio per il dominio IoT e <iot-digital-twin-OCID> con l'OCID del gemello digitale da cui si desidera visualizzare i dati rifiutati:

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>';