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, compresa la temperatura. 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

Creare un modello Digital Twin con un modello base di capacità
Creare un modello Digital Twin per un sensore
Creare un modello Digital Twin per il sensore Env-III
Creare un modello Digital Twin per lo spazio
Creare un adattatore Digital Twin per il sensore Env-III
Creare un'istanza Digital Twin per uno spazio
Creare un'istanza Digital Twin con un adattatore per un sensore Env-III
Creare una relazione Digital Twin per connettere le istanze Digital Twin
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à

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

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

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

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

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

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

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

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

Passaggio 5: 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:stack: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 6: creare un'istanza Digital Twin per uno spazio

Utilizzare questo comando per creare un'istanza digital twin per uno spazio. Questo esempio mostra come associare un modello di gemello digitale utilizzando il parametro URI specifica DTMI --digital-twin-model-spec-uri. In alternativa, è possibile utilizzare il parametro OCID del modello gemello digitale per associare il modello gemello digitale specificando l'OCID del modello gemello digitale.

Questa istanza digital twin non richiede un adattatore o un'autenticazione perché non invia o pubblica dati ad altri sistemi o servizi.

oci iot digital-twin-instance create --iot-domain-id <iot-domain-OCID> --display-name <device-for-conference-room-103> --digital-twin-model-spec-uri <dtmi:com:oracle:example:core:Space:sp;1>

Questa risposta di esempio mostra l'OCID dell'istanza digital twin specifica, il modello digital twin, l'ID della chiave esterna e include l'URI DTMI specifico definito per lo spazio:

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

{
  "data": {
    "auth-id": null,
    "defined-tags": {
      "Oracle-Tags": {
        "CreatedBy": "default/user@oracle.com",
        "CreatedOn": "2025-09-11T06:12:43.393Z"
      }
    },
    "description": null,
    "digital-twin-adapter-id": 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": "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 7: 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-or-certificate-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 8: 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" --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 9: 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. Nel grafico delle proprietà vengono visualizzate solo le istanze e le relazioni dei gemelli digitali con lifecycle_state = ACTIVE.

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

Documentazione dell'infrastruttura Oracle Cloud