Oracle Cloud Infrastructureドキュメント

シナリオ: デジタル・ツイン関係の問合せ

デジタル・ツイン・インスタンスは、デジタル・ツイン・モデル、デジタル・ツイン・アダプタ、階層および関係を使用して、実際の環境を表す仮想モデルを作成できます。

このシナリオでは、デジタル・ツイン関係を問い合せて、デバイス、機能、データおよび接続に関する質問に回答し、物理領域とそのデバイスを監視する方法について説明します。このシナリオでは、スペースは物理的なエリア(会議室など)です。これは、温度や湿度などの環境特性を測定する空間にあるデバイスであるEnv-IIIセンサーによって提供されます。この階層とservedBy関係により、アプリケーションは次を問い合せることができます。
  • どのセンサーが特定のスペースにサービスを提供しますか?
  • これらのセンサーによって報告されるテレメトリは何ですか?
  • wi-fiを使用してデバイスを接続する方法

タスク

  1. 機能ベース・モデルを使用したデジタル・ツイン・モデルの作成
  2. センサーのデジタル・ツイン・モデルの作成
  3. Env-IIIセンサー用のデジタルツインモデルの作成
  4. スペースのデジタル・ツイン・モデルの作成
  5. スペース用のデジタル・ツイン・アダプタの作成
  6. Env-IIIセンサー用のデジタルツインアダプタを作成する
  7. スペースのアダプタを使用したデジタル・ツイン・インスタンスの作成
  8. Env-IIIセンサーのアダプタを使用したデジタル・ツイン・インスタンスの作成
  9. デジタル・ツイン・インスタンスに接続するためのデジタル・ツイン・リレーションシップの作成
  10. SQLを使用したデジタル・ツイン関係グラフの問合せ

開始する前に

必要な権限があることを確認してください。管理者は、必要なポリシーを作成してアクセス権を付与します。詳細は、前提条件およびInternet of Things (IoT)プラットフォームのポリシー詳細を参照してください。

ステップ1: 機能ベース・モデルを使用したデジタル・ツイン・モデルの作成

  1. このコード・スニペットをmodel_capability.jsonファイルとして保存します。デジタル・ツイン・モデルを作成する場合は、次のステップでこのファイルを参照します。このモデル仕様では、機能を定義し、ベース・モデルとして機能します。

    ファイルの参照の詳細は、複合入力のためのJSONファイルの使用およびデジタル・ツイン・モデルの作成を参照してください。 

    {
  "@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. oci iot digital-twin-model createコマンドおよびパラメータを使用して、機能ベース・モデルを持つデジタル・ツイン・モデルを作成します。

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

    このレスポンス例では、デジタル・ツイン・モデルがアクティブであり、model_capability.jsonファイルに定義されているDTMI URIを参照しています。

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

ステップ2: センサー用のデジタル・ツイン・モデルの作成

  1. このコード・スニペットをmodel_sensor.jsonファイルとして保存します。次のステップでこのファイルを参照して、別のデジタル・ツイン・モデルを作成します。これは、機能ベース・モデルからプロパティを継承し、機能ベース・モデルを拡張するセンサー定義です。
    {
  "@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. このコマンドおよびパラメータを使用して、デジタル・ツイン・モデルを作成する仕様を定義します。 
    oci iot digital-twin-model create --iot-domain-id <iot-domain-OCID> --spec file://model_sensor.json

    このレスポンス例は、デジタル・ツイン・モデルがアクティブであり、model_sensor.jsonファイルに定義されている特定のDTMI URIを参照していることを示しています。

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

ステップ3:Env-IIIセンサー用のデジタルツインモデルの作成

  1. このコード・スニペットをmodel_env.jsonファイルとして保存します。別のデジタル・ツイン・モデルを作成する場合は、次のステップでこのファイルを参照します。
    {
  "@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. このコマンドおよびパラメータを使用して、別のデジタル・ツイン・モデルを作成するための仕様を定義します。 
    oci iot digital-twin-model create --iot-domain-id <iot-domain-OCID> --spec file://model_env.json

    次の例は、デジタル・ツイン・モデルがアクティブで、model_env.jsonファイルに定義されている特定のDTMI URIを参照していることを示しています。

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

ステップ4: スペースのデジタル・ツイン・モデルの作成

  1. このコード・スニペットをmodel_space.jsonファイルとして保存し、スペースのデジタル・ツイン・モデルを作成するときに次のステップでこのファイルを参照します。領域は、センサー・モデルservedByです。
    {
  "@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. 次のコマンドを使用して、file://model_space.jsonを参照するデジタル・ツイン・モデルを作成し、ファイルに定義されている仕様をこのデジタル・ツイン・モデルに適用します。 
    oci iot digital-twin-model create --iot-domain-id <iot-domain-OCID> --spec file://model_space.json

    このレスポンス例は、デジタル・ツイン・モデルがアクティブであり、model_space.jsonファイルに定義されているこの特定のDTMI URIを参照していることを示しています。

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

ステップ5: スペース用のデジタル・ツイン・アダプタの作成

このコマンドを使用して、デジタル・ツイン・アダプタを作成し、デジタル・ツイン・モデル仕様をスペースのDTMI URIに関連付けます。

デジタル・ツイン・アダプタを作成する場合、inbound-envelopeまたはinbound-routesオプションを指定しないことで、システムにデフォルトのペイロードおよびマッピングを強制的に作成できます。

エンベロープ・マッピングが指定されておらず、timeObservedが含まれている場合は、receivedTimeが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"
このレスポンス例では、特定のデジタル・ツイン・アダプタOCIDを示し、特定のデジタル・ツイン・モデルおよびDTMI URIに関連付けられています。

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

ステップ6:Env-IIIセンサー用のデジタルツインアダプタを作成する

このコマンドを使用して、デジタル・ツイン・アダプタを作成し、デジタル・ツイン・モデル仕様をEnv-IIIセンサーのDTMI URIに関連付けます。 
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"
このレスポンス例は、特定のデジタル・ツイン・アダプタOCIDを示し、特定のデジタル・ツイン・モデルおよびDTMIに関連付けられています。

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

ステップ7: スペースのアダプタを使用したデジタル・ツイン・インスタンスの作成

このコマンドを使用して、シークレットを使用して認証し、特定のデジタル・ツイン・モデルおよびデジタル・ツイン・アダプタに関連付けられている表示名でデジタル・ツイン・インスタンスを作成します。ボールト・シークレットの作成方法の詳細は、シークレットの作成を参照してください。 
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>
このレスポンス例では、特定のデジタル・ツイン・インスタンスOCIDと、関連するデジタル・ツイン・アダプタ、デジタル・ツイン・モデル、外部キーIDを示し、スペースに定義された特定のDTMI URIを含みます。

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

ステップ8: Env-IIIセンサー用のアダプタを使用したデジタル・ツイン・インスタンスの作成

このコマンドを使用して、シークレットを使用して認証し、特定のデジタル・ツイン・モデル、デジタル・ツイン・アダプタおよびIoTドメインに関連付けられている表示名を持つデジタル・ツイン・インスタンスを作成します。OCIDを、環境の関連するIoTリソースに置き換えます。

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>"
このレスポンス例は、デジタル・ツイン・インスタンスがアクティブで、関連するデジタル・ツイン・モデルおよびデジタル・ツイン・アダプタが含まれていることを示しています。
{
  "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>"
}

ステップ9: 2つのデジタル・ツイン・インスタンスを接続するためのデジタル・ツイン関係の作成

このコマンドを使用して、2つのデジタル・ツイン・インスタンス間のデジタル・ツイン関係を作成し、コンテンツ・パスをservedBy、接続タイプをwi-fi、このデジタル・ツイン関係の表示名として定義します。
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"
このレスポンス例は、このデジタル・ツイン関係のコンテンツ・パスおよび関連するデジタル・ツイン・インスタンスを示しています。
{
  "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>"
}

ステップ10: SQLを使用したデジタル・ツイン関係グラフの問合せ

SQL問合せを使用して、APEX内のIoTデータを表示する場合、またはAPEXへの接続の構成または直接データベース接続の構成を必要とするデータベース内で直接表示する場合。

APEXまたはデータベース内の直接で、次のSQL文を使用して、特定のデジタル・ツイン・インスタンスのデジタル・ツイン関係の詳細を検索します。<domain-short-id-from-device-host>をデバイス・ホストからのドメイン短縮IDに置き換えます。<digital-twin-instance-OCID>を、操作するデジタル・ツイン・インスタンスOCIDに置き換えます:

ノート

__IOTには2つのアンダースコアがあります。
<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)
);

2つのデジタル・ツイン・インスタンス間の関係を検索するには、次の問合せを使用します。FROM_DIGITAL-TWIN-INSTANCE-OCIDをソースのデジタル・ツイン・インスタンスOCIDに置き換え、TO_DIGITAL-TWIN-INSTANCE-OCIDを、次のコンテンツ・パスを検索するターゲットのデジタル・ツイン・インスタンスOCIDに置き換えます。

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