Documentazione dell'infrastruttura Oracle Cloud

Scenario: query su una relazione Digital Twin

Un'istanza digital twin può utilizzare modelli digital twin, adattatori digital twin, gerarchie e relazioni per creare un modello virtuale che rappresenti un ambiente reale.

Questo scenario spiega come eseguire query su una relazione digital twin per rispondere a domande su un dispositivo, funzionalità, dati e connettività, per monitorare uno spazio fisico e i relativi dispositivi. In questo scenario, uno spazio è un'area fisica, ad esempio una sala conferenze. Questo è servito da un sensore Env-III che è un dispositivo situato nello spazio che misura le caratteristiche ambientali tra cui temperatura e umidità. Questa gerarchia e la relazione servedBy consentono alle applicazioni di eseguire query su:
  • Quali sensori servono uno spazio specifico?
  • Quale telemetria viene segnalata da questi sensori?
  • Come sono collegati i dispositivi, utilizzando il wi-fi?

Task

  1. Creare un modello Digital Twin con un modello base di capacità
  2. Creare un modello Digital Twin per un sensore
  3. Creare un modello Digital Twin per il sensore Env-III
  4. Creare un modello Digital Twin per lo spazio
  5. Creare un adattatore Digital Twin per lo spazio
  6. Creare un adattatore Digital Twin per il sensore Env-III
  7. Creare un'istanza Digital Twin con un adattatore per uno spazio
  8. Creare un'istanza Digital Twin con un adattatore per un sensore Env-III
  9. Creare una relazione Digital Twin per connettere le istanze Digital Twin
  10. Eseguire query sul grafico Digital Twin Relationship utilizzando SQL

Informazioni preliminari

Assicurarsi di disporre delle autorizzazioni necessarie. Un amministratore concede l'accesso creando i criteri necessari. Per ulteriori informazioni, vedere Prerequisiti e Dettagli dei criteri per la piattaforma Internet of Things (IoT).

Passo 1: Creare un modello Digital Twin con un modello base di capacità

  1. Salvare questo snippet di codice come file model_capability.json. Fare riferimento a questo file nel passo successivo quando si crea un modello gemello digitale. Questa specifica del modello definisce la capacità e funge da modello di base.

    Per ulteriori informazioni sui file di riferimento, vedere Uso di un file JSON per l'input complesso e Creazione di un modello gemello digitale. 

    {
  "@context": [
    "dtmi:dtdl:context;3"
  ],
  "@id": "dtmi:com:oracle:example:core:Capability:cap;1",
  "@type": "Interface",
  "displayName": "Capability",
  "description": "A Capability indicates capacity to produce and ingest data.",
  "contents": [
    {
      "@type": "Property",
      "name": "lastValueTime",
      "schema": "dateTime"
    }
  ]
}

  2. Utilizzare il comando e i parametri oci iot digital-twin-model create per creare un modello gemello digitale con un modello base di funzionalità.

    oci iot digital-twin-model create --iot-domain-id <iot-domain-OCID> --spec file://model_capability.json

    Questa risposta di esempio mostra che il modello digital twin è attivo e fa riferimento all'URI DTMI definito nel file model_capability.json:

    dtmi:com:oracle:example:core:Capability:cap;1

    {
  "data": {
    "defined-tags": {
      "Oracle-Tags": {
        "CreatedBy": "default/user@oracle.com",
        "CreatedOn": "2025-09-11T05:56:50.514Z"
      }
    },
    "description": "A aapability indicates capacity to produce and ingest data.",
    "display-name": "Capability",
    "freeform-tags": {},
    "id": "<iot-digital-twin-model-OCID>",
    "iot-domain-id": "<iot-domain-OCID>",
    "lifecycle-state": "ACTIVE",
    "spec-uri": "dtmi:com:oracle:example:core:Capability:cap;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 2: Creare un modello Digital Twin per un sensore

  1. Salvare questo snippet di codice come file model_sensor.json. Fare riferimento a questo file nel passo successivo per creare un altro modello gemello digitale. Si tratta di una definizione di sensore che eredita le proprietà e estende il modello di base delle capacità.
    {
  "@context": [
    "dtmi:dtdl:context;3"
  ],
  "@id": "dtmi:com:oracle:example:core:Sensor:sen;1",
  "@type": "Interface",
  "extends": "dtmi:com:oracle:example:core:Capability:cap;1",
  "displayName": "Sensor",
  "description": "Capability to detect or measure properties of the physical world.",
  "contents": [
    {
      "@type": "Relationship",
      "displayName": "observes",
      "name": "observes",
      "target": "dtmi:com:oracle:example:core:Space:ex;1"
    }
  ]
}
  2. Utilizzare questo comando e parametri per definire le specifiche per creare un modello gemello digitale. 
    oci iot digital-twin-model create --iot-domain-id <iot-domain-OCID> --spec file://model_sensor.json

    Questa risposta di esempio mostra che il modello digital twin è attivo e fa riferimento all'URI DTMI specifico definito nel file model_sensor.json:

    dtmi:com:oracle:example:core:sensor:sen;1

    {
  "data": {
    "defined-tags": {
      "Oracle-Tags": {
        "CreatedBy": "default/user@oracle.com",
        "CreatedOn": "2025-09-11T06:03:25.687Z"
      }
    },
    "description": "Capability to detect or measure properties of the physical world.",
    "display-name": "Sensor",
    "freeform-tags": {},
    "id": "<iot-digital-twin-model-OCID>",
    "iot-domain-id": "<iot-domain-OCID>",
    "lifecycle-state": "ACTIVE",
    "spec-uri": "dtmi:com:oracle:example:core:Sensor:sen;1",
    "system-tags": {},
    "time-created": "2025-09-11T06:03:25.753000+00:00",
    "time-updated": "2025-09-11T06:03:25.753000+00:00"
  },
  "etag": "<unique-id>"
}

Passo 3: Creare un modello Digital Twin per il sensore Env-III

  1. Salvare questo snippet di codice come file model_env.json. Fare riferimento a questo file nel passo successivo quando si crea un altro modello gemello digitale.
    {
  "@context": [
    "dtmi:dtdl:context;3",
    "dtmi:dtdl:extension:quantitativeTypes;1",
    "dtmi:dtdl:extension:historization;1",
    "dtmi:com:oracle:dtdl:extension:validation;1"
  ],
  "@id": "dtmi:com:oracle:example:stack:enviii:ev;2",
  "@type": "Interface",
  "extends": [
    "dtmi:com:oracle:example:core:sensor:sen;1"
  ],
  "displayName": "M5 with EnvIII sensors",
  "description": "Model envIII",
  "contents": [
    {
      "@type": [
        "Telemetry",
        "Historized",
        "Temperature"
      ],
      "name": "room_temp",
      "schema": "double",
      "unit": "degreeCelsius"
    }
  ]
}
  2. Utilizzare questo comando e parametri per definire le specifiche per creare un altro modello gemello digitale. 
    oci iot digital-twin-model create --iot-domain-id <iot-domain-OCID> --spec file://model_env.json

    Questo esempio mostra che il modello gemello digitale è attivo e fa riferimento all'URI DTMI specifico definito nel file model_env.json:

    dtmi:com:oracle:example:stack:enviii:ev;2
    {
  "data": {
    "defined-tags": {
      "Oracle-Tags": {
        "CreatedBy": "default/user@oracle.com",
        "CreatedOn": "2025-09-11T06:07:30.882Z"
      }
    },
    "description": "Model envIII",
    "display-name": "M5 with EnvIII sensors",
    "freeform-tags": {},
    "id": "<iot-digital-twin-model-OCID>",
    "iot-domain-id": "<iot-domain-OCID>",
    "lifecycle-state": "ACTIVE",
    "spec-uri": "dtmi:com:oracle:example:stack:enviii:ev;2",
    "system-tags": {},
    "time-created": "2025-09-11T06:07:30.944000+00:00",
    "time-updated": "2025-09-11T06:07:30.944000+00:00"
  },
  "etag": "<unique-id>"
}

Passo 4: Creare un modello Digital Twin per lo spazio

  1. Salvare questo snippet di codice come file model_space.json e fare riferimento a questo file nel passo successivo quando si crea un modello gemello digitale per lo spazio. Lo spazio è servedBy il modello del sensore.
    {
  "@context": [
    "dtmi:dtdl:context;3"
  ],
  "@id": "dtmi:com:oracle:example:core:Space:sp;1",
  "@type": "Interface",
  "displayName": "Space",
  "description": "Model Space",
  "contents": [
    {
      "@type": "Relationship",
      "displayName": "served by",
      "name": "servedBy",
      "target": "dtmi:com:oracle:example:core:sensor:sen;1"
    }
  ]
}
  2. Utilizzare il comando seguente per creare un modello di gemello digitale che fa riferimento a file://model_space.json per applicare le specifiche definite nel file a questo modello di gemello digitale. 
    oci iot digital-twin-model create --iot-domain-id <iot-domain-OCID> --spec file://model_space.json

    Questa risposta di esempio mostra che il modello digital twin è attivo e fa riferimento a questo URI DTMI specifico definito nel file model_space.json:

    dtmi:com:oracle:example:core:Space:sp;1
    {
  "data": {
    "defined-tags": {
      "Oracle-Tags": {
        "CreatedBy": "default/user@oracle.com",
        "CreatedOn": "2025-09-11T06:06:45.538Z"
      }
    },
    "description": "Model Space",
    "display-name": "Space",
    "freeform-tags": {},
    "id": "<iot-digital-twin-model-OCID>",
    "iot-domain-id": "<iot-domain-OCID>",
    "lifecycle-state": "ACTIVE",
    "spec-uri": "dtmi:com:oracle:example:core:Space:sp;1",
    "system-tags": {},
    "time-created": "2025-09-11T06:06:45.574000+00:00",
    "time-updated": "2025-09-11T06:06:45.574000+00:00"
  },
  "etag": "<unique-id>"
}

Passo 5: Creare un adattatore Digital Twin per lo spazio

Utilizzare questo comando per creare un adattatore gemello digitale e associare la specifica del modello gemello digitale all'URI DTMI per lo spazio.

Quando si crea un adattatore digital twin, è possibile forzare il sistema a creare un payload e mapping predefiniti non specificando le opzioni inbound-envelope o inbound-routes.

Se il mapping dell'envelope non viene specificato e contiene un valore timeObserved, receivedTime viene utilizzato come valore timeObserved. 

oci iot digital-twin-adapter create --iot-domain-id <iot-domain-OCID> --digital-twin-model-spec-uri "dtmi:com:oracle:example:core:space:sp;1"
Questa risposta di esempio mostra un OCID adattatore digital twin specifico e che è associato a un modello digital twin specifico e a un URI DTMI.

dtmi:com:oracle:example:core:Space: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:core:Space:sp;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": "/",
      "reference-payload": {
        "data": {
          "time": "2025-09-11T06:09:27.878106Z"
        },
        "data-format": "JSON"
      }
    },
    "inbound-routes": [
      {
        "condition": "*",
        "description": "default condition",
        "payload-mapping": {},
        "reference-payload": null
      }
    ],
    "iot-domain-id": "<iot-domain-OCID>",
    "lifecycle-state": "ACTIVE",
    "system-tags": {},
    "time-created": "2025-09-11T06:09:27.879000+00:00",
    "time-updated": "2025-09-11T06:09:27.879000+00:00"
  },
  "etag": "<unique-id>"
}

Passaggio 6: creare un adattatore Digital Twin per il sensore Env-III

Utilizzare questo comando per creare un adattatore digital twin e associare la specifica del modello digital twin all'URI DTMI per il sensore Env-III. 
oci iot digital-twin-adapter create --iot-domain-id <iot-domain-OCID> --digital-twin-model-spec-uri "dtmi:com:oracle:room:m5stack:enviii:ev;2"
Questa risposta di esempio mostra un OCID adattatore digital twin specifico ed è associata a un modello digital twin e a DTMI specifici.

dtmi:com:oracle:example:stack:enviii:ev;2

{
  "data": {
    "defined-tags": {
      "Oracle-Tags": {
        "CreatedBy": "default/user@oracle.com",
        "CreatedOn": "2025-09-11T06:10:23.303Z"
      }
    },
    "description": null,
    "digital-twin-model-id": "<iot-digital-twin-model-OCID>",
    "digital-twin-model-spec-uri": "dtmi:com:oracle:example:stack:enviii:ev;2",
    "display-name": "<digital-twin-adapter-display-name>",
    "freeform-tags": {},
    "id": "<iot-digital-twin-adapter-OCID>",
    "inbound-envelope": {
      "envelope-mapping": {
        "time-observed": "$.time"
      },
      "reference-endpoint": "/",
      "reference-payload": {
        "data": {
          "sht_temp": 0.0,
          "time": "2025-09-11T06:10:26.127416Z"
        },
        "data-format": "JSON"
      }
    },
    "inbound-routes": [
      {
        "condition": "*",
        "description": "Default condition",
        "payload-mapping": {
          "$.sht_temp": "$.sht_temp"
        },
        "reference-payload": null
      }
    ],
    "iot-domain-id": "<iot-domain-OCID>",
    "lifecycle-state": "ACTIVE",
    "system-tags": {},
    "time-created": "2025-09-11T06:10:27.204000+00:00",
    "time-updated": "2025-09-11T06:10:27.204000+00:00"
  },
  "etag": "<unique-id>"
}

Passo 7: Creare un'istanza Digital Twin con un adattatore per uno spazio

Utilizzare questo comando per creare un'istanza gemella digitale con un nome visualizzato che utilizza un segreto per l'autenticazione ed è associato a un modello gemello digitale specifico e a un adattatore gemello digitale. Per informazioni su come creare un segreto vault, vedere Creazione di un segreto. 
oci iot digital-twin-instance create --auth-id <vault-secret-OCID> --iot-domain-id <iot-domain-OCID> --digital-twin-adapter-id <iot-digital-twin-adapter-OCID> --display-name <your-display-name>
Questa risposta di esempio mostra l'OCID dell'istanza digital twin specifica ed è associata all'adattatore digital twin, al modello digital twin, all'ID chiave esterna e include l'URI DTMI specifico definito per lo spazio:

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

{
  "data": {
    "auth-id": "<vault-secret-OCID>",
    "defined-tags": {
      "Oracle-Tags": {
        "CreatedBy": "default/user@oracle.com",
        "CreatedOn": "2025-09-11T06:12:43.393Z"
      }
    },
    "description": null,
    "digital-twin-adapter-id": "<iot-digital-twin-adapter-OCID>",
    "digital-twin-model-id": "<iot-digital-twin-model-OCID>",
    "digital-twin-model-spec-uri": "dtmi:com:oracle:example:core:Space:sp;1",
    "display-name": "device for conference room 103",
    "external-key": "<unique-id>",
    "freeform-tags": {},
    "id": "<iot-digital-twin-instance-OCID>",
    "iot-domain-id": "<iot-domain-OCID>",
    "lifecycle-state": "ACTIVE",
    "system-tags": {},
    "time-created": "2025-09-11T06:12:44.178000+00:00",
    "time-updated": "2025-09-11T06:12:44.178000+00:00"
  },
  "etag": "<unique-id>"
}

Passo 8: Creare un'istanza Digital Twin con un adattatore per un sensore Env-III

Utilizzare questo comando per creare un'istanza digital twin con un nome visualizzato che utilizza un segreto per l'autenticazione ed è associato a un modello digital twin specifico, un adattatore digital twin e un dominio IoT. Sostituire gli OCID con le risorse IoT correlate per l'ambiente.

oci iot digital-twin-instance create --auth-id <vault-secret-OCID> --iot-domain-id <iot-domain-OCID> --digital-twin-adapter-id <iot-digital-twin-adapter-OCID> --display-name "<your-display-name>"
Questa risposta di esempio mostra che l'istanza digital twin è attiva e contiene il modello digital twin correlato e l'adattatore digital twin.
{
  "data": {
    "auth-id": "<vault-secret-OCID>",
    "defined-tags": {
      "Oracle-Tags": {
        "CreatedBy": "default/user@oracle.com",
        "CreatedOn": "2025-09-11T06:14:33.493Z"
      }
    },
    "description": null,
    "digital-twin-adapter-id": "<iot-digital-twin-adapter-OCID>",
    "digital-twin-model-id": "<iot-digital-twin-model-OCID>",
    "digital-twin-model-spec-uri": "dtmi:com:oracle:example:stack:enviii:ev;2",
    "display-name": "Envii device 2",
    "external-key": "<unique-id>",
    "freeform-tags": {},
    "id": "<iot-digital-twin-instance-OCID>",
    "iot-domain-id": "<iot-domain-OCID>",
    "lifecycle-state": "ACTIVE",
    "system-tags": {},
    "time-created": "2025-09-11T06:14:34.821000+00:00",
    "time-updated": "2025-09-11T06:14:34.821000+00:00"
  },
  "etag": "<unique-id>"
}

Passo 9: Creare una relazione Digital Twin per connettere due istanze Digital Twin

Utilizzare questo comando per creare una relazione digital twin tra due istanze digital twin e per definire il percorso del contenuto come servedBy, il tipo di connessione come wi-fi e il nome visualizzato per questa relazione digital twin.
oci iot digital-twin-relationship create --iot-domain-id <iot-domain-OCID> --target-digital-twin-instance-id <iot-digital-twin-instance-OCID> --source-digital-twin-instance-id <iot-digital-twin-instance-OCID> --content-path "servedBy" --content '{"connectionType": "wi-fi"}' --display-name "Env and sensor relationship"
Questa risposta di esempio mostra il percorso del contenuto e le istanze digital twin correlate per questa relazione digital twin:
{
  "data": {
    "content": {
      "connectionType": "wi-fi"
    },
    "content-path": "servedBy",
    "defined-tags": {
      "Oracle-Tags": {
        "CreatedBy": "default/user@oracle.com",
        "CreatedOn": "2025-09-11T07:40:08.926Z"
      }
    },
    "description": null,
    "display-name": "Env and sensor relationship",
    "freeform-tags": {},
    "id": "<iot-digital-twin-relationship-OCID>",
    "iot-domain-id": "<iot-domain-OCID>",
    "lifecycle-state": "ACTIVE",
    "source-digital-twin-instance-id": "<iot-digital-twin-instance-OCID>",
    "system-tags": {},
    "target-digital-twin-instance-id": "<iot-digital-twin-instance-OCID>",
    "time-created": "2025-09-11T07:40:09.755000+00:00",
    "time-updated": "2025-09-11T07:40:09.755000+00:00"
  },
  "etag": "<unique-id>"
}

Passo 10: eseguire una query sul grafico Digital Twin Relationship utilizzando SQL

Se si desidera utilizzare le query SQL per visualizzare i dati IoT in APEX o direttamente nel database che richiede la configurazione di una connessione ad APEX o la configurazione di una connessione diretta al database.

In APEX o direttamente nel database, utilizzare le istruzioni SQL riportate di seguito per trovare i dettagli della relazione digital twin per un'istanza digital twin specifica. Sostituire <domain-short-id-from-device-host> con il valore domain short id dell'host del dispositivo. Sostituire <digital-twin-instance-OCID> con l'OCID dell'istanza del gemello digitale con cui si desidera lavorare:

Nota

Osserva due caratteri di sottolineatura in __IOT.
<domain-short-id-from-device-host>__IOT.DIGITAL_TWINS
SELECT * FROM GRAPH_TABLE(
    <domain-short-id-from-device-host>__IOT.DIGITAL_TWINS
    MATCH (a IS digitalTwinInstance) -[e IS digitalTwinRelationship]-> (b IS digitalTwinInstance)
    WHERE a.id = '<digital-twin-instance-OCID>'
    COLUMNS (a.id as src, e.content_path as rel, b.id as tgt)
);

Per trovare le relazioni tra due istanze digital twin, utilizzare la query seguente. Sostituire FROM_DIGITAL-TWIN-INSTANCE-OCID con l'OCID dell'istanza digital twin di origine e TO_DIGITAL-TWIN-INSTANCE-OCID con l'OCID dell'istanza digital twin di destinazione per cui si desidera trovare il percorso del contenuto per:

SELECT * FROM GRAPH_TABLE(
    <domain-short-id-from-device-host>__IOT.DIGITAL_TWINS
    MATCH (a IS digitalTwinInstance) -[e IS digitalTwinRelationship]-> (b IS digitalTwinInstance)
    WHERE a.id = 'FROM_DIGITAL-TWIN-INSTANCE-OCID'AND b.id = 'TO_DIGITAL-TWIN-INSTANCE-OCID'
    COLUMNS (a.id as src, e.content_path as rel, b.id as tgt)
);