Documentazione dell'infrastruttura Oracle Cloud

Creazione di un modello Digital Twin

Crea un modello digital twin per l'Internet of Things (IoT).

Un modello gemello digitale definisce la semantica di un gemello digitale e si basa sulle specifiche DTDL v3.

Un'istanza digital twin richiede un modello digital twin e un adattatore digital twin per ricevere dati da un dispositivo che invia dati strutturati. Per esempi specifici, vedere Scenari.

Nota

Digital Twins Definition Language (DTDL) v3 è supportato su GitHub dal Digital Twin Consortium. È importante notare quanto riportato di seguito.
  • Le estensioni MQTT e le proprietà scrivibili non sono supportate. Se è inclusa una proprietà writable, è necessario impostarla su false.
  • Solo il content all'interno del componente può essere annotato come historized, indicando che la piattaforma IoT deve conservare la telemetria della serie temporale del sensore, vedere l'esempio del modello gemello digitale dtdl-model-specifications.json di seguito.

Se si desidera creare un'istanza digital twin senza dati ingeribili da un dispositivo, è possibile creare un'istanza digital twin senza un adattatore digital twin e senza il parametro ID autenticazione, --auth-id. Il modello gemello digitale associato non deve contenere telemetria o proprietà. Dopo aver creato un'istanza digital twin, è possibile creare una relazione digital twin per simulare l'ambiente IoT senza la complessità dei dati o dell'autenticazione.

    1. Nella pagina elenco Domini IoT selezionare il dominio IoT da utilizzare. Per assistenza nella ricerca della pagina di elenco dei domini IoT, vedere Elenco dei domini IoT.
    2. Selezionare la scheda Modelli gemelli digitali, quindi selezionare Crea.
    3. Immettere un nome e, facoltativamente, una descrizione di facile utilizzo. Evitare di fornire informazioni riservate.
    4. Selezionare un'opzione per aggiungere la specifica DTDL del modello:
      • Per caricare il file dtdl-specification.json, selezionare Carica la specifica. Trascinare o selezionare un file .json con la specifica DTDL per questo modello gemello digitale.
      • Per aggiungere JSON per il modello gemello digitale, selezionare Incolla specifica.
    5. Tag: (facoltativo) aggiungere una o più tag al modello gemello digitale. Se si dispone delle autorizzazioni per creare una risorsa, si dispone anche delle autorizzazioni per applicare tag in formato libero a tale risorsa. Per applicare una tag definita, è necessario disporre delle autorizzazioni per utilizzare lo spazio di nomi tag. Per ulteriori informazioni sull'applicazione di tag, vedere Tag risorsa. Se non sei sicuro di applicare i tag, salta questa opzione o chiedi a un amministratore. È possibile applicare le tag in un secondo momento.
    6. Selezionare Crea.

    Visualizza i dettagli del modello digital twin. Copiare l'OCID dominio IoT associato, il modello gemello digitale DTMI o l'OCID modello gemello digitale.

    Selezionare la scheda correlata per visualizzare la specifica DTDL, le istanze digital twin associate, gli adattatori digital twin associati o le tag per questo modello digital twin.

  • Utilizzare il comando oci iot digital-twin-model create e i parametri necessari per creare un modello gemello digitale in un dominio IoT specifico. Fornire le specifiche come contenuto JSON direttamente nella riga di comando o come file a cui viene fatto riferimento nella riga di comando:

    Esempio in linea: questo esempio mostra come fornire le specifiche JSON direttamente nella riga di comando:

    oci iot digital-twin-model create --iot-domain-id <iot-domain-OCID> --spec '{"@context": ["dtmi:dtdl:context;3", "dtmi:dtdl:extension:historization;1", "dtmi:dtdl:extension:quantitativeTypes;1", "dtmi:com:oracle:dtdl:extension:validation;1"], "@id": "dtmi:com:oracle:iot:sample:hvac:UgNaNWHbzK;1", "@type": "Interface", "contents": [{"@type": ["Telemetry", "Temperature"], "name": "temperature", "schema": "integer", "unit": "degreeFahrenheit"}, {"@type": ["Telemetry", "Historized", "Validated"], "name": "humidity", "schema": "integer", "minimum": 0, "maximum": 100}, {"@type": ["Property", "Historized"], "name": "location", "schema": "point", "writable": true}, {"@type": ["Property", "Validated"], "name": "serialNumber", "schema": "string", "pattern": "^([0-9]){2}([0-9]){5}([0-9]){6}$"}]}'

    Esempio di riferimento file: in questo esempio viene illustrato come creare un file dtdl-model-specifications.json contenente le specifiche, come fare riferimento al file .json nel comando. Il formato può variare in base al sistema operativo in uso per ulteriori informazioni sui file di riferimento. Vedere Utilizzo di un file JSON per l'input complesso.

    oci iot digital-twin-model create --iot-domain-id <iot-domain-OCID> --spec file://dtdl-model-specifications.json
    In questo snippet dal modello gemello digitale di esempio qui sotto:
    • Si noti che il valore humidity è annotato come telemetria historized, quindi ogni lettura dell'umidità viene memorizzata come misura di serie temporale con un indicatore orario timeObserved, invece di registrare solo il valore più recente.
    • È inoltre convalidato come integer nell'intervallo 0–100. Solo il contenuto all'interno di un componente può essere annotato come nota istorizzata questa dichiarazione @type nell'esempio seguente.
    {
  "@type": ["Telemetry","Historized","Validated"],
  "name": "humidity",
  "schema": "integer",
  "minimum": 0,
  "maximum": 100
}
    In questo modello HVAC, dtdl-model-specifications.json
    • Questo modello si basa sulla specifica DTDL v3 e contiene un Digital Twin Model Identifier (DTMI) come identificativo univoco: @id: "dtmi:com:oracle:iot:sample:hvac:<unique-id>;1"
    • Questo modello di gemello digitale di esempio consente la cronologia, i tipi qualitativi e i contesti di estensione della convalida. Vedere Informazioni di riferimento sull'estensione per la convalida DMI.
    • Come descritto nello snippet sopra la telemetria humidity è annotata come Historized, quindi le letture dell'umidità vengono conservate come dati delle serie temporali, letture nel tempo.
    • La telemetria location viene annotata come Historized, pertanto le modifiche alla posizione vengono conservate anche nel tempo, registrando la cronologia della posizione della proprietà con un audit trail.
    • La telemetria temperature non viene annotata con Historized, registrando solo l'ultimo valore noto un'altra persistenza a valle configurata altrove.
    • La proprietà serialNumber viene contrassegnata come Validated utilizzando un pattern regex e non viene annotata come storicizzata, pertanto viene mantenuto solo il valore corrente o più recente e non un tracciamento cronologico delle modifiche.
    {
  "@context": [
    "dtmi:dtdl:context;3",
    "dtmi:dtdl:extension:historization;1",
    "dtmi:dtdl:extension:quantitativeTypes;1",
    "dtmi:com:oracle:dtdl:extension:validation;1"
  ],
  "@id": "dtmi:com:oracle:iot:sample:hvac:UgNaNWHbzK;1",
  "@type": "Interface",
  "contents": [
    {
      "@type": [
        "Telemetry",
        "Temperature"
      ],
      "name": "temperature",
      "schema": "integer",
      "unit": "degreeFahrenheit"
    },
    {
      "@type": [
        "Telemetry",
        "Historized",
        "Validated"
      ],
      "name": "humidity",
      "schema": "integer",
      "minimum": 0,
      "maximum": 100
    },
    {
      "@type": [
        "Property",
        "Historized"
      ],
      "name": "location",
      "schema": "point",
      "writable": false
    },
    {
      "@type": [
        "Property",
        "Validated"
      ],
      "name": "serialNumber",
      "schema": "string",
      "pattern": "^([0-9]){2}([0-9]){5}([0-9]){6}$"
    }
  ]
}

    Questa risposta CLI di esempio mostra che il modello digital twin è stato creato per il dominio IoT, con un URI DTMI: dtmi:com:oracle:iot:sample:hvac:unique-id;1:

    {
  "data": {
    "defined-tags": {
      "Oracle-Tags": {
        "CreatedBy": "default/user",
        "CreatedOn": "2025-08-05T17:43:00.438Z"
      }
    },
    "description": null,
    "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:iot:sample:hvac:unique-id;1",
    "system-tags": {},
    "time-created": "2025-08-05T17:43:00.508000+00:00",
    "time-updated": "2025-08-05T17:43:00.508000+00:00"
  },
  "etag": "<unique-id>"
}

    Per un elenco completo dei parametri e dei valori per i comandi CLI, vedere Riferimento per i comandi CLI

  • Eseguire l'operazione CreateDigitalTwinModel per creare un modello di gemello digitale nel dominio IoT specifico.

    Richiesta di esempio:

    POST /20250531/digitalTwinModels
content-type: application/json+ld
{
    "@context": ["dtmi:dtdl:context;3"],
    "@id": "dtmi:com:oracle:labauto:SmartSpecimenVault;1",
    "@type": "Interface",
    "extends": "dtmi:com:oracle:iot:connectable;1",
    "displayName": "HVAC",
    "contents": [
        {"@type": "Telemetry", "name": "temperature", "schema": "integer"},
        {"@type": "Telemetry", "name": "humidity", "schema": "integer", "minimum":0, "maximum": 100},
        {"@type": "Property", "name": "desiredTemperature", "schema": "integer", "writable": false},
        {"@type": "Property", "name": "serialNumber", "schema": "string"} 
    ]
}

    Risposta di esempio:

    header:
content-type: application/json
Body:
{
    "id": "<digital-twin-model-OCID>"
    "displayName": "<your-HVAC-display-name>",
    "description": "<digital-twin-model-for-HVAC>"
    "lifecycleState": "ACTIVE",
    "freeformTags": {},
    "definedTags": {
       "Oracle-Tags": {
         "CreatedBy": "default/user@oracle.com",
         "CreatedOn": "2024-07-22T10:24:53.446Z"
       }
    },
    "specUri": "dtmi:com:oracle:labauto:SmartSpecimenVault;1"
    "timeCreated": "2025-01-13T10:24:53Z",
    "timeUpdated": "2025-01-14T17:15:21Z"
}