Oracle Cloud Infrastructureドキュメント

デジタル・ツイン・モデルの作成

Internet of Things用のデジタル・ツイン・モデルを作成します(IoT)。

デジタル・ツイン・モデルは、デジタル・ツインのセマンティクスを定義し、DTDL v3仕様に基づいています。デジタル・ツイン・モデルは、デジタル・ツイン・モデル識別子(DTMI)を一意の識別子として使用します。

たとえば: dtmi:com:oracle:iot:connectable;1

デジタル・ツイン・モデルがDTDL仕様v3を使用することを示す、必要なデジタル・ツイン・モデル・コンテキスト: dtmi:dtdl:context;3

デジタル・ツイン・インスタンスでは、構造化されたデバイス・データを受信するために、デジタル・ツイン・モデルとデジタル・ツイン・アダプタが必要です。具体的な例は、シナリオを参照してください。

ノート

Digital Twins Definition Language (DTDL) v3は、Digital Twin ConsortiumによってGitHubでサポートされています。以下の点に注意してください。
  • MQTT拡張および書込み可能プロパティはサポートされていません。writableプロパティが含まれている場合は、falseに設定する必要があります。
  • historizedとして注釈を付けることができるのは、コンポーネント内のcontentのみです。これは、IoTプラットフォームがそのセンサーの時系列テレメトリを保持する必要があることを示しています。次のデジタル・ツイン・モデルの例dtdl-model-specifications.jsonを参照してください。

デバイスから取込み可能なデータを使用せずにデジタル・ツイン・インスタンスを作成する場合は、デジタル・ツイン・アダプタを使用せず、認証IDパラメータ--auth-idを使用せずにデジタル・ツイン・インスタンスを作成できます。関連付けられたデジタル・ツイン・モデルにテレメトリまたはプロパティを含めることはできません。その後、デジタル・ツイン・インスタンスを作成した後、デジタル・ツイン関係を作成して、データや認証の複雑さなしにIoT環境をシミュレートできます。

  • oci iot digital-twin-model createコマンドおよび必須パラメータを使用して、特定のIoTドメインにデジタル・ツイン・モデルを作成します。指定は、コマンドラインで直接JSONコンテンツとして、またはコマンドラインで参照されるファイルとして指定します。

    インライン例: この例では、コマンドラインでJSON仕様を直接指定しています:

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

    ファイル参照の例: この例では、指定を含むdtdl-model-specifications.jsonファイルを作成する方法と、コマンドで.jsonファイルを参照する方法を示します。ファイルの参照の詳細は、オペレーティング・システムに応じて形式が異なる場合があります。複雑な入力のためのJSONファイルの使用を参照してください:

    oci iot digital-twin-model create --iot-domain-id <iot-domain-OCID> --spec file://dtdl-model-specifications.json
    次の例のデジタル・ツイン・モデルのこのスニペットでは:
    • humidity値はhistorizedテレメトリとして注釈付けされるため、各湿度読取りは、最新の値のみを記録するのではなく、timeObservedタイムスタンプで時系列測定として格納されます。
    • また、0–100の範囲のintegerであることが検証されます。履歴化として注釈を付けることができるのは、コンポーネント内のコンテンツのみです。次の例では、この@type宣言に注意してください。
    {
  "@type": ["Telemetry","Historized","Validated"],
  "name": "humidity",
  "schema": "integer",
  "minimum": 0,
  "maximum": 100
}
    このHVACモデルでは、dtdl-model-specifications.json
    • このモデルは、DTDL v3仕様に基づいており、一意の識別子としてデジタル・ツイン・モデル識別子(DTMI)が含まれています: @id: "dtmi:com:oracle:iot:sample:hvac:<unique-id>;1"
    • この例のデジタル・ツイン・モデルは、履歴化、定性タイプおよび検証拡張コンテキストを有効にします。DTMI Validation Extension Referenceを参照してください。
    • 前述のスニペットで説明したように、humidityテレメトリにはHistorizedという注釈が付けられているため、湿度検針は時系列データおよび検針として時間の経過とともに保持されます。
    • locationテレメトリにはHistorizedの注釈が付けられているため、場所への変更も時間の経過とともに保持され、プロパティの場所履歴が監査証跡で記録されます。
    • temperatureテレメトリにはHistorizedの注釈は付けられず、別の場所で構成された別のダウンストリーム永続性で最後に認識された値のみが記録されます。
    • serialNumberプロパティは、正規表現パターンを使用してValidatedとマークされ、Historizedと注釈付けされないため、現在または最新の値のみが保持され、変更の履歴追跡は行われません。
    {
  "@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}$"
    }
  ]
}

    このCLIレスポンスの例は、DTMI URIがdtmi:com:oracle:iot:sample:hvac:unique-id;1のIoTドメインに対して作成されたデジタル・ツイン・モデルを示しています。

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

    CLIコマンドのパラメータおよび値の完全なリストは、CLIコマンド・リファレンスを参照してください。

  • CreateDigitalTwinModel操作を実行して、特定のIoTドメインにデジタル・ツイン・モデルを作成します。

    リクエストの例:

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

    レスポンスの例:

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