Documentazione dell'infrastruttura Oracle Cloud

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

Utilizzare questo scenario per inviare e monitorare i dati strutturati da un dispositivo in un formato personalizzato. Se un dispositivo invia dati in un formato personalizzato, significa che il dispositivo non può essere programmato per modificarne l'output.

In questo caso, definire il mapping dell'adattatore digital twin personalizzato, per tradurre i dati in entrata in un formato riconosciuto dalla piattaforma IoT.

Un amministratore deve aggiungere un criterio alla tenancy e ai compartimenti che si desidera utilizzare. Per esempi di criteri e prerequisiti, vedere Dettagli criteri per la piattaforma Internet of Things (IoT) e IoT Prerequisiti.

  1. Creare un gruppo di domini IoT e un dominio IoT
  2. Crea un modello digital twin
  3. Creare un adattatore digital twin per un formato personalizzato
  4. Creare un'istanza digital twin con un adattatore
  5. Invia dati telemetria
  6. Visualizza dati telemetria

Passo 1: creare un gruppo di domini IoT e un dominio IoT

Utilizzare un gruppo di domini IoT e un dominio IoT esistenti oppure creare un gruppo di domini IoT e creare un dominio IoT da utilizzare per questo scenario.

Dopo aver ottenuto il gruppo di domini IoT e il dominio IoT che si desidera utilizzare, attenersi alla procedura riportata di seguito per impostare le risorse digital twin per ricevere dati strutturati in un formato personalizzato da un dispositivo. Tutte le risorse IoT devono trovarsi nella stessa area.

Per ottenere il <domain-short-id-from-device-host> per il dominio IoT o per ottenere l'OCID del dominio IoT, è possibile ottenere i dettagli per il dominio IoT con cui si desidera lavorare.

Passo 2: Creare un modello Digital Twin

  1. Creare specifiche utilizzando il Digital Twins Definition Language (DTDL) per il modello di gemello digitale simile a questo esempio con i dati che si desidera raccogliere.

    Per utilizzare questo esempio, salvare questo snippet di codice come file digital-twin-model.json e quindi fare riferimento a questo file nel passo successivo quando si crea un modello gemello digitale.

    Un modello di gemello digitale richiede un Digital Twin Model Identifier (DTMI) come identificativo univoco. Ad esempio: dtmi:com:oracle:example:hvac;1

    {
  "@context": [
    "dtmi:dtdl:context;3"
  ],
  "@id": "dtmi:com:oracle:example:hvac;1",
  "@type": "Interface",
  "displayName": "HVAC",
  "description": "A digital twin model for HVAC",
  "contents": [
    {
      "@type": "Telemetry",
      "name": "temperature",
      "schema": "integer"
    },
    {
      "@type": "Telemetry",
      "name": "humidity",
      "schema": "integer"
    },
    {
      "@type": "Property",
      "name": "power",
      "schema": "boolean"
    },
    {
      "@type": "Property",
      "name": "batteryLevel",
      "schema": "integer"
    }
  ]
}
  2. Utilizzare il comando oci iot digital-twin-model create con il parametro richiesto per creare un modello gemello digitale. Sostituire <iot-domain-OCID> con l'OCID per il dominio IoT che si desidera associare a questo modello di gemello digitale. Fare riferimento al file digital-twin-model.json creato nel passo precedente o a un file di specifiche per lo scenario specifico. Per ulteriori informazioni sui file di riferimento, vedere Uso di un file JSON per l'input complesso:
    oci iot digital-twin-model create --iot-domain-id <iot-domain-OCID> --spec file://digital-twin-model.json
    Risposta di esempio utilizzando il file digital-twin-model.json del passo precedente. Questa risposta di esempio mostra l'URI DTMI e l'OCID del modello digital twin IoT:
    {
  "data": {
    "defined-tags": {
      "Oracle-Tags": {
        "CreatedBy": "default/user@oracle.com",
        "CreatedOn": "2025-09-11T05:56:50.514Z"
      }
    },
    "description": "A digital twin model for HVAC",
    "display-name": "HVAC",
    "freeform-tags": {},
    "id": "<iot-digital-twin-model-OCID>",
    "iot-domain-id": "<iot-domain-OCID>",
    "lifecycle-state": "ACTIVE",
    "spec-uri": "dtmi:com:oracle:example:hvac;1",
    "system-tags": {},
    "time-created": "2025-09-11T05:56:50.587000+00:00",
    "time-updated": "2025-09-11T05:56:50.587000+00:00"
  },
  "etag": "<unique-id>"
}

Passo 3: Creare un adattatore Digital Twin per un formato personalizzato

Se un dispositivo invia dati in un formato personalizzato, significa che il dispositivo non può essere programmato per modificarne l'output. In questo caso, definire il formato personalizzato nella mappatura dell'adattatore gemello digitale,

A tale scopo, definire inbound-envelope e inbound-routes in un formato JSON per convertire i dati in un formato che si desidera utilizzare nei servizi e nelle applicazioni Oracle in modo da poter connettersi per visualizzare i dati IoT in sistemi diversi.

Uso dell'interfaccia CLI

  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": {
    "dataFormat": "JSON",
    "data": {
      "time": "<timestamp>",
      "data": {
        "temp": 0,
        "hum": 0,
        "power": false,
        "batteryLevel": 0
      }
    }
  },
  "envelope-mapping": {
    "timeObserved": "$.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\"}",
    "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. 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>"
}

Passo 4: Creare un'istanza Digital Twin con l'adattatore

Uso dell'interfaccia CLI

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 o creare un certificato nella stessa area e tenancy di qualsiasi altra risorsa IoT correlata.

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.

Sostituire <digital-twin-adapter-OCID> con l'adattatore gemello digitale creato nel passo precedente. 
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>
Questa risposta di esempio mostra l'adattatore digital twin e l'URI DTMI definiti per il modello digital twin associato a questa istanza digital twin.

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

Passo 5: Invia dati telemetria

Utilizzare il seguente comando curl e il comando <digital-twin-instance-external-key> per inviare o inviare dati. Per ulteriori informazioni, vedere Uso di cURL.

A seconda del tipo di dati che si desidera inviare, utilizzare il seguente esempio per inviare la telemetria:
curl -u 'digital-twin-instance-external-key:device-password' -H "content-type: application/json" https://<domain-short-id-from-device-host>.device.iot.<region>.oci.oraclecloud.com/telemetry/heartbeat -d '{"temp": 70, "hum": 55}'
Accepted%
curl -i -X POST \
     -u "<digital-twin-instance-external-key>:<device-password>" \
     -H "Content-Type: application/json" \
     "https://<domain-short-id-from-device-host>.device.iot.<region>.oci.oraclecloud.com/telemetry/heartbeat" \
     -d '{
           "digital_twin_instance_id": "<iot-digital-twin-instance-OCID>",
           "received_at": "2024-08-14T06:01:30.432829Z",
           "endpoint": "telemetry/heartbeat",
           "content_type": "application/json",
           "content": {
             "time": "<time>",
             "data": {
               "temp": 70,
               "hum": 65
             }
           }
         }'

Passo 6: visualizzazione dei dati di telemetria

Utilizza l'API di dati Internet of Things per ottenere i dati

Se si accede ai dati IoT mediante ORDS e si dispone del token di autenticazione richiesto, è possibile utilizzare l'API dati di Internet of Things per ottenere i dati che si desidera monitorare.

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

Sostituire le variabili con i valori per l'ambiente in uso:
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>\"}]}"

Utilizzare istruzioni SQL per visualizzare i dati

Se si accede configurato alla vista dei dati direttamente nel database o si accede configurato per visualizzare i dati in APEX, è possibile utilizzare questa istruzione SQL per visualizzare i dati di telemetria raw:
select * from <domain-short-id-from-device-host>__IOT.RAW_DATA where digital_twin_instance_id = '<iot-digital-twin-OCID>';
Nota

Si noti che il nome dello schema contiene due caratteri di sottolineatura: __IOT

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 = '<iot-digital-twin-OCID>';
In alternativa, utilizzare questa istruzione SQL per visualizzare i dati di telemetria storicizzati. 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 per il gemello digitale da cui si desidera visualizzare i dati rifiutati:
select * from <domain-short-id>__IOT.DIGITAL_TWIN_HISTORIZED_DATA where digital_twin_id = '<digital-twin-OCID>';