シナリオ: デジタル・ツイン・インスタンスの互換性のあるデジタル・ツイン・モデル・バージョンへのアップグレード

互換性のあるマイナー・バージョンのデジタル・ツイン・モデルを作成し、そのデジタル・ツイン・モデル・バージョン用の新しいデジタル・ツイン・アダプタを作成し、デジタル・ツイン・インスタンスを削除せずに新しいデジタル・ツイン・アダプタを使用するようにデジタル・ツイン・インスタンスを更新することで、デジタル・ツイン・インスタンスをアップグレードします。

このシナリオは、置換またはアップグレードされたデバイスが新しいテレメトリ値などの加算ペイロード・シェイプを送信し、既存のデジタル・ツイン・インスタンスの継続性を保持する場合に使用します。デジタルツインモデルは、正規化されたデータの契約のままです。デジタル・ツイン・アダプタは、受信デバイス・ペイロードをその契約にマップします。

OCI IoTでは、新しいデジタル・ツイン・アダプタが同じデジタル・ツイン・モデル・バージョンまたは互換性のある上位マイナー・バージョンの同じデジタル・ツイン・モデルを参照する場合、アクティブなデジタル・ツイン・インスタンスを別のデジタル・ツイン・アダプタに更新できます。このシナリオでは、基本的なHVACデジタルツインモデルを構築する方法と、以前のデジタルツインモデルをそのまま維持しながら、追加のセンサーで新しいHVACデジタルツインモデルバージョンを作成する方法を示します。

このアップグレード・フローでは、主要なデジタル・ツイン・モデルのバージョン変更は互換性がありません。ダウングレードはサポートされていません。

HVACは暖房、換気および空調の略で、屋内温度、湿度および全体的な空気質を調節するために建物で使用される異なったシステムを指します。

タスク

互換性のあるデジタル・ツイン・モデルのバージョニング・ルールを確認します。
ベースHVACデジタル・ツイン・モデルを作成します。
ベースHVACデジタル・ツイン・アダプタを作成します。
デジタル・ツイン・インスタンスを作成します。
テレメトリをベース・デジタル・ツイン・インスタンスに送信します。
互換性のあるマイナー・デジタル・ツイン・モデル・バージョンを作成します。
新しいデジタル・ツイン・モデル・バージョン用のデジタル・ツイン・アダプタを作成します。
新しいデジタル・ツイン・アダプタを使用するようにデジタル・ツイン・インスタンスを更新します。
アップグレード後にデジタル・ツイン・インスタンスのテレメトリを検証します。
FAQを確認します。
デジタル・ツイン・モデルのアップグレードの問題をトラブルシューティングします。

ベスト・プラクティス

既存のデジタル・ツイン・モデルへの値の追加: このシナリオのステップを使用して、追加デジタル・ツイン・モデル変更用のマイナーDTMIバージョンを作成します(バージョンの変更など)。1から1.1の数値。これは、DTDL v3仕様でサポートされているように、既存のデジタル・ツイン・インスタンスを新しいデジタル・ツイン・アダプタに更新する際のメジャーDTMIバージョンを同じに保ちます。
dtmi:com:oracle:example:hvac;1からdtmi:com:oracle:example:hvac;1.1
デジタル・ツイン・モデルで新しい値を作成してから、新しいデジタル・ツイン・インスタンスを作成: 異なる値でデジタル・ツイン・モデルを作成する必要がある場合は、新しいメジャーDTMIバージョンを使用します。このタイプの更新では、新しいデジタル・ツイン・モデルのメジャー・バージョン変更を使用して新しいデジタル・ツイン・インスタンスを作成する必要があります。次に例を示します:
dtmi:com:oracle:example:hvac;1からdtmi:com:oracle:example:hvac;2
継承が推奨: マイナー更新の場合、新しい値を追加する場合は、以前のデジタル・ツイン・モデル・バージョンを拡張するデジタル・ツイン・モデルなど、追加のデジタル・ツイン・モデルの変更に継承を使用することをお薦めします。新しいデジタル・ツイン・モデル・バージョンごとに@id、場所、コア・ステータスなどの基本属性を再定義するかわりに、新しいデジタル・ツイン・モデルは値を自動的に継承し、エラーを減らして開発時間を節約します。
既存の遠隔測定、プロパティー、コマンド、関係、およびスキーマは互換性があるままにします。マイナー・アップグレード中に既存の契約要素の名前変更、削除、絞り込みまたは変更を行わないでください。
新しいデジタル・ツイン・モデル・バージョン用の新しいデジタル・ツイン・アダプタを作成し、アップグレードされたデバイスが検証されるまで、以前のデジタル・ツイン・アダプタをロールバックできるように維持します。
本番ロールアウトの前に代表的なテレメトリを使用してペイロードをテストします。

このシナリオのファイルの理解

hvac-model.json: 温度および湿度のテレメトリのための基盤DTDLのデジタル双生児モデル。
hvac-envelope.json: timeObservedを抽出するベース・デジタル・ツイン・アダプタ・エンベロープ。
hvac-routes.json: 温度および湿度のベース・デジタル・ツイン・アダプタのルート・マッピング。
hvac-e-model.json: エネルギー消費テレメトリを追加する互換性のあるマイナーDTDLデジタルツインモデルバージョン。
hvac-e-envelope.json: 追加のテレメトリ・フィールドを受け入れる、アップグレードされたデジタル・ツイン・アダプタ・エンベロープ。
hvac-e-routes.json: 温度、湿度およびエネルギー消費のためのアップグレードされたデジタル・ツイン・アダプタ・ルート・マッピング。

ステップ1: 互換性のあるデジタル・ツイン・モデル・バージョニング・ルールの確認

デジタル・ツイン・モデルを作成すると、OCI IoTは、同じメジャー・バージョンのアクティブなデジタル・ツイン・モデルがすでに存在するかどうかを確認します。

存在する場合、新しいマイナー・バージョンのデジタル・ツイン・モデルは、互換性のあるバージョン番号および値を持つ厳密な加算である必要があります。別のデジタル・ツイン・アダプタを使用するようにデジタル・ツイン・インスタンスを更新する場合、アダプタは、同じデジタル・ツイン・モデル・バージョンまたは互換性のある上位マイナー・バージョンを参照する必要があります。

古いデジタル・ツイン・モデル・バージョンと新しいデジタル・ツイン・モデル・バージョンの間で、次の互換性チェックが適用されます。

アップグレードされたデジタル・ツイン・インタフェースおよびモデル・バージョンを作成する場合、新しいマイナー・バージョンは、前のマイナー・バージョンに.1を加えたものである必要があります。次に例を示します。

dtmi:com:oracle:example:hvac;1からdtmi:com:oracle:example:hvac;1.1

スキームおよびパスを含むすべてのインタフェース@id値が一致する必要があり、新しいマイナー・バージョンのみが、マイナー増分を含むバージョン番号と、既存のモデルに追加される追加値です。アップグレードは、メジャー・バージョンが一定であり、変更されていない場合にのみ互換性があります。

DTDL要素	互換性ルール	ノート
`Interface`	既存の`extends`値は同じままにする必要があります。追加の拡張が許可されます。既存のすべてのモデル・コンテンツは、同じ名前のままにする必要があります。新規コンテンツは許可されます。スキーマ・コレクションのサイズとスキーマIDパスは同じである必要があります。	再利用可能なインタフェース・スキーマの追加はサポートされず、拒否されます。
`Telemetry`	既存のテレメトリでは、同じ名前、DTDLクラス、セマンティックまたは隣接型、`@id`パス、ユニット、スキーマおよび検証制約を保持する必要があります。	`comment`、`displayName`および`description`は比較されません。
`Property`	既存のプロパティは、同じコンテンツ・ルール、書込み可能設定、スキーマ、単位および検証制約を保持する必要があります。	インタフェース・プロパティおよび関係プロパティに適用されます。
`Command`	既存のコマンドは残しておく必要があります。リクエストおよびレスポンスの存在、名前、スキーマおよび検証の制約が一致する必要があります。	リクエストまたはレスポンスの追加、削除または変更には互換性がありません。
`Relationship`	既存の関係では、同じ書込み可能設定、ターゲット、最小多重度、最大多重度および既存の関係プロパティを保持する必要があります。	新しい関係プロパティを使用できます。
`Component`	コンポーネント・スキーマは同じままである必要があります。	参照されたコンポーネント・インタフェースは、このチェックでは再帰的に比較されません。
`Schema`	具象スキーマ・タイプは同じままにする必要があります。既存の`primitive`、`geospatial`、`array`、`enum`、`map`、`object`および`field`スキーマは、互換性のある型および検証制約を保持する必要があります。	`Primitive-to-object`、`enum-to-map`および同様の変更には互換性がありません。
`Enum`	既存の`enum`値は、同じ名前およびリテラル値のままにする必要があります。	新しい`enum`値が許可されます。
`Object`	既存のフィールドは残しておく必要があります。既存の各フィールド・スキーマと検証制約が一致する必要があります。	新しい`object`フィールドを使用できます。
`Interface schemas`	古い再利用可能な各スキーマは、同じDTMIスキームおよびパスによって新しいデジタル・ツイン・モデルに存在し、そのスキーマ固有の比較に合格する必要があります。	既存の再利用可能なスキーマの削除または変更には互換性がありません。サポートされている場合は、新しい再使用可能スキーマを使用できます。

ステップ2: ベースHVACデジタルツインモデルの作成

温度および湿度テレメトリを使用したベース・デジタル・ツイン・モデルを作成します。

コンソールを使用して、IoTドメインにベースHVACデジタル・ツイン・モデルを作成します。
1. 「IoTドメイン」リスト・ページで、操作するIoTドメインを開きます。
2. 「デジタル・ツイン・モデル」タブを選択し、「作成」を選択します。
3. DTDL JSONをhvac-model.jsonからアップロードまたは貼り付けます。
4. 「作成」を選択します。
hvacモデル.json
{ "@context": [ "dtmi:dtdl:context;3" ], "@id": "dtmi:com:oracle:example:hvac;1", "@type": "Interface", "displayName": "HVAC", "description": "A digital twin model for HVAC", "contents": [ { "@type": "Telemetry", "name": "temperature", "schema": "integer" }, { "@type": "Telemetry", "name": "humidity", "schema": "integer" } ] }

IoTドメインにベースHVACデジタル・ツイン・モデルを作成するには、oci iot digital-twin-model createコマンドを使用します。

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

hvacモデル.json

{
  "@context": [
    "dtmi:dtdl:context;3"
  ],
  "@id": "dtmi:com:oracle:example:hvac;1",
  "@type": "Interface",
  "displayName": "HVAC",
  "description": "A digital twin model for HVAC",
  "contents": [
    {
      "@type": "Telemetry",
      "name": "temperature",
      "schema": "integer"
    },
    {
      "@type": "Telemetry",
      "name": "humidity",
      "schema": "integer"
    }
  ]
}

CreateDigitalTwinModel操作を実行して、IoTドメインにベースHVACデジタル・ツイン・モデルを作成します。
APIをコールするときは、hvac-model.jsonに示されているものと同じDTDLペイロードを使用します。

ステップ3: ベースHVACデジタルツインアダプタの作成

ベースHVACデジタル・ツイン・モデル・バージョンを参照し、デバイス・ペイロードをデジタル・ツイン・モデルのテレメトリ・フィールドにマップするデジタル・ツイン・アダプタを作成します。

コンソールを使用して、ベースHVACデジタル・ツイン・アダプタを作成し、インバウンド・エンベロープをアップロードまたは貼り付けてJSONをルーティングします。
1. 「IoTドメイン」リスト・ページで、操作するIoTドメインを開きます。
2. 「デジタル・ツイン・アダプタ」タブを選択し、「作成」を選択します。
3. ベースHVACデジタル・ツイン・アダプタの名前と説明(オプション)を入力します。
4. DTMI dtmi:com:oracle:example:hvac;1を使用して、ベースHVACデジタル・ツイン・モデルを選択します。
5. 「インバウンド・エンベロープおよびルートの指定」をオンにして、hvac-envelope.jsonおよびhvac-routes.jsonをアップロードまたは貼り付けます。
6. 「作成」を選択します。
hvac-envelope.json
{ "referenceEndpoint": "/telemetry", "referencePayload": { "dataFormat": "JSON", "data": { "time": 1773768299143534, "temp": 0, "hum": 0 } }, "envelopeMapping": { "timeObserved": "$.time" } }
hvac-routes.json
[ { "condition": "*", "payloadMapping": { "$.temperature": "$.temp", "$.humidity": "$.hum" } } ]

oci iot digital-twin-adapter createコマンドを使用して、ベースHVACデジタル・ツイン・アダプタを作成します。

oci iot digital-twin-adapter create \
  --iot-domain-id <iot-domain-OCID> \
  --digital-twin-model-spec-uri "dtmi:com:oracle:example:hvac;1" \
  --inbound-envelope file://hvac-envelope.json \
  --inbound-routes file://hvac-routes.json

hvac-envelope.json

{
  "referenceEndpoint": "/telemetry",
  "referencePayload": {
    "dataFormat": "JSON",
    "data": {
      "time": 1773768299143534,
      "temp": 0,
      "hum": 0
    }
  },
  "envelopeMapping": {
    "timeObserved": "$.time"
  }
}

hvac-routes.json

[
  {
    "condition": "*",
    "payloadMapping": {
      "$.temperature": "$.temp",
      "$.humidity": "$.hum"
    }
  }
]

CreateDigitalTwinAdapter操作を実行して、IoTドメインにベースHVACデジタル・ツイン・アダプタを作成します。
ダウンロード可能なファイルに示されているものと同じインバウンド・エンベロープおよびインバウンド・ルート・ペイロードを使用します。

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

ベースHVACデジタル・ツイン・アダプタを使用するデジタル・ツイン・インスタンスを作成します。外部キーは、デバイスが接続するときに使用するユーザー名です。

コンソールを使用して、HVACデバイスのデジタル・ツイン・インスタンスを作成します。
1. 「IoTドメイン」リスト・ページで、操作するIoTドメインを開きます。
2. 「デジタル・ツイン・インスタンス」タブを選択し、「作成」を選択します。
3. 表示名としてLG HVAC 1と入力します。
4. Step 3で作成した基本HVACデジタルツインアダプタを選択します。
5. 認証IDを選択するか、証明書またはシークレットOCIDを貼り付けます。
6. 外部キーとして hvac1と入力します。
7. 「作成」を選択します。

デジタル・ツイン・インスタンスを作成するには、oci iot digital-twin-instance createコマンドを使用します。

oci iot digital-twin-instance create \
  --iot-domain-id <iot-domain-OCID> \
  --display-name "LG HVAC 1" \
  --auth-id <certificate-or-secret-OCID> \
  --digital-twin-adapter-id <base-digital-twin-adapter-OCID> \
  --external-key hvac1

CreateDigitalTwinInstance操作を実行して、デジタル・ツイン・インスタンスを作成します。
ベースHVACデジタル・ツイン・アダプタOCIDおよびデバイス資格証明の認証IDを使用します。

ステップ5: ベース・デジタル・ツイン・インスタンスへのテレメトリの送信

ベース・デジタル・ツイン・アダプタ・マッピングに一致するペイロードを送信し、デジタル・ツイン・インスタンス・コンテンツを取得して正規化されたテレメトリを検証します。

MQTTXを使用して、MQTTSを介してテレメトリを送信します。

mqttx pub \
  -t "data" \
  -m '{
    "temp": 70,
    "hum": 60
  }' \
  -u hvac1 \
  -P '<secret-contents>'

curlを使用して、HTTPS経由でテレメトリを送信します。この例では、デジタル・ツイン・インスタンスの外部キーおよびプレーン・テキストのシークレット・コンテンツとともにHTTP Basic認証を使用します。
```
curl -i -u "hvac1:<secret-contents>" \
  -H "Content-Type: application/json" \
  -X POST \
  "https://<domain-short-id>.device.iot.<region>.oci.oraclecloud.com/data" \
  -d '{
    "temp": 70,
    "hum": 60
  }'
```

デジタル・ツイン・インスタンス・コンテンツを取得して、最新の正規化された値を確認します。

「デジタル・ツイン・インスタンス」タブで、LG HVAC 1のデジタル・ツイン・インスタンスの詳細ページを開き、最新のコンテンツ値を確認します。
デジタル・ツイン・インスタンスからコンテンツを取得するには、oci iot digital-twin-instance get-contentコマンドを使用します。
```
oci iot digital-twin-instance get-content \
  --digital-twin-instance-id <lg-hvac-1-OCID>
```
GetDigitalTwinInstanceContent操作を実行して、デジタル・ツイン・インスタンスからコンテンツを取得します。

ステップ6: 互換性のあるマイナーHVACデジタルツインモデルバージョンを作成する

ベースHVACデジタルツインモデルをextendsし、エネルギー消費のためのテレメトリを追加する、互換性のあるマイナーデジタルツインモデルバージョンを作成します。メジャー・バージョンは1のままであり、マイナー・バージョンは1.1に増加します。

コンソールを使用して、IoTドメインに互換性のあるマイナーHVACデジタル・ツイン・モデル・バージョンを作成します。
1. 「IoTドメイン」リスト・ページで、操作するIoTドメインを開きます。
2. 「デジタル・ツイン・モデル」タブを選択し、「作成」を選択します。
3. DTDL JSONをhvac-e-model.jsonからアップロードまたは貼り付けます。
4. 「作成」を選択します。
hvac-e-model.json
{ "@context": [ "dtmi:dtdl:context;3" ], "@id": "dtmi:com:oracle:example:hvac;1.1", "@type": "Interface", "extends": "dtmi:com:oracle:example:hvac;1", "displayName": "HVACe", "description": "A digital twin model for HVACe", "contents": [ { "@type": "Telemetry", "name": "energyConsumption", "schema": "integer" } ] }

互換性のあるマイナーHVACデジタル・ツイン・モデル・バージョンを作成するには、oci iot digital-twin-model createコマンドを使用します。

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

hvac-e-model.json

{
  "@context": [
    "dtmi:dtdl:context;3"
  ],
  "@id": "dtmi:com:oracle:example:hvac;1.1",
  "@type": "Interface",
  "@extends": "dtmi:com:oracle:example:hvac;1",
  "displayName": "HVACe",
  "description": "A digital twin model for HVACe",
  "contents": [
    {
      "@type": "Telemetry",
      "name": "energyConsumption",
      "schema": "integer"
    }
  ]
}

CreateDigitalTwinModel操作を実行して、互換性のあるマイナーHVACデジタル・ツイン・モデル・バージョンをIoTドメインに作成します。
APIをコールするときは、hvac-e-model.jsonに示されているものと同じDTDLペイロードを使用します。

ステップ7: 新しいデジタル・ツイン・モデル・バージョンのデジタル・ツイン・アダプタの作成

互換性のあるマイナーHVACデジタル・ツイン・モデル・バージョンを参照し、追加のテレメトリ・フィールドをマップする新しいデジタル・ツイン・アダプタを作成します。

コンソールを使用して、アップグレードされたHVACデジタル・ツイン・アダプタを作成し、インバウンド・エンベロープをアップロードまたは貼り付けてJSONをルーティングします。
1. 「IoTドメイン」リスト・ページで、操作するIoTドメインを開きます。
2. 「デジタル・ツイン・アダプタ」タブを選択し、「作成」を選択します。
3. アップグレードされたHVACデジタル・ツイン・アダプタの名前と説明(オプション)を入力します。
4. DTMI dtmi:com:oracle:example:hvac;1.1を使用してHVACデジタル・ツイン・モデル・バージョンを選択します。
5. 「インバウンド・エンベロープおよびルートの指定」をオンにして、hvac-e-envelope.jsonおよびhvac-e-routes.jsonをアップロードまたは貼り付けます。
6. 「作成」を選択します。
hvac-e-envelope.json
{ "referenceEndpoint": "/telemetry", "referencePayload": { "dataFormat": "JSON", "data": { "time": 1773768299143534, "temp": 0, "hum": 0, "ec": 0 } }, "envelopeMapping": { "timeObserved": "$.time" } }
hvac-e-routes.json
[ { "condition": "*", "payloadMapping": { "$.temperature": "$.temp", "$.humidity": "$.hum", "$.energyConsumption": "$.ec" } } ]

アップグレードされたHVACデジタル・ツイン・アダプタを作成するには、oci iot digital-twin-adapter createコマンドを使用します。

oci iot digital-twin-adapter create \
  --iot-domain-id <iot-domain-OCID> \
  --digital-twin-model-spec-uri "dtmi:com:oracle:example:hvac;1.1" \
  --inbound-envelope file://hvac-e-envelope.json \
  --inbound-routes file://hvac-e-routes.json

hvac-e-envelope.json

{
  "referenceEndpoint": "/telemetry",
  "referencePayload": {
    "dataFormat": "JSON",
    "data": {
      "time": 1773768299143534,
      "temp": 0,
      "hum": 0,
      "ec": 0
    }
  },
  "envelopeMapping": {
    "timeObserved": "$.time"
  }
}

hvac-e-routes.json

[
  {
    "condition": "*",
    "payloadMapping": {
      "$.temperature": "$.temp",
      "$.humidity": "$.hum",
      "$.energyConsumption": "$.ec"
    }
  }
]

CreateDigitalTwinAdapter操作を実行して、アップグレードされたHVACデジタル・ツイン・アダプタをIoTドメインに作成します。
ダウンロード可能なファイルに示されているものと同じインバウンド・エンベロープおよびインバウンド・ルート・ペイロードを使用します。

ステップ8: 新しいデジタル・ツイン・アダプタを使用するためのデジタル・ツイン・インスタンスの更新

互換性のあるマイナー・デジタル・ツイン・モデル・バージョンのデジタル・ツイン・アダプタを参照するように、既存のデジタル・ツイン・インスタンスを更新します。デジタル・ツイン・インスタンスは、新しいデジタル・ツイン・モデル契約のペイロードの受入れを開始する間、同じアイデンティティ、外部キーおよびデータ継続性を保持します。

ノート

置換デジタル・ツイン・モデルが新しいメジャー・バージョンを使用したり、既存の要素を削除したり、フィールドの名前を変更したり、制約を絞り込んだり、デジタル・ツイン・モデル契約を非加算的な方法で変更したりする場合は、既存のデジタル・ツイン・インスタンスを更新するかわりに、新しいデジタル・ツイン・インスタンスを使用します。

コンソールを使用して、アップグレードされたHVACデジタル・ツイン・アダプタを使用するように既存のデジタル・ツイン・インスタンスを更新します。
1. 「IoTドメイン」リスト・ページで、操作するIoTドメインを開きます。
2. 「デジタル・ツイン・インスタンス」タブを選択します。
3. LG HVAC 1のデジタル・ツイン・インスタンスの詳細ページを開きます。
4. 「編集」を選択します。
5. デジタルツインアダプタを、Step 7で作成したアップグレードされたHVACデジタルツインアダプタに変更します。
6. 変更を保存します。

デジタル・ツイン・インスタンスを更新するには、oci iot digital-twin-instance updateコマンドを使用します。

oci iot digital-twin-instance update \
  --digital-twin-instance-id <lg-hvac-1-OCID> \
  --digital-twin-adapter-id <upgraded-digital-twin-adapter-OCID>

UpdateDigitalTwinInstance操作を実行して、デジタル・ツイン・インスタンスを更新します。
デジタル・ツイン・アダプタIDをアップグレードされたHVACデジタル・ツイン・アダプタのOCIDに設定します。

ステップ9: アップグレード後のデジタル・ツイン・インスタンスのテレメトリの検証

新しいテレメトリ・フィールドを含むペイロードを送信し、デジタル・ツイン・インスタンスのコンテンツに、アップグレードされたデジタル・ツイン・アダプタによってマップされた値が含まれていることを確認します。

検証に失敗した場合は、デジタル・ツイン・モデルDTMI、デジタル・ツイン・アダプタ--digital-twin-model-spec-uri、エンベロープ・マッピングおよびルート・ペイロード・マッピングを比較します。アップグレードされたデジタル・ツイン・アダプタは、互換性のあるマイナー・デジタル・ツイン・モデル・バージョンを参照し、ペイロード・フィールドをそのデジタル・ツイン・モデルで定義された名前にマップする必要があります。

MQTTXを使用して、MQTTSを介してテレメトリを送信します。

mqttx pub \
  -t "data" \
  -m '{
    "temp": 70,
    "hum": 60,
    "ec": 38
  }' \
  -u hvac1 \
  -P '<secret-contents>'

curlを使用して、HTTPS経由でテレメトリを送信します。この例では、デジタル・ツイン・インスタンスの外部キーおよびプレーン・テキストのシークレット・コンテンツとともにHTTP Basic認証を使用します。
```
curl -i -u "hvac1:<secret-contents>" \
  -H "Content-Type: application/json" \
  -X POST \
  "https://<domain-short-id>.device.iot.<region>.oci.oraclecloud.com/data" \
  -d '{
    "temp": 70,
    "hum": 60,
    "ec": 38
  }'
```

オプション・ステップ: コンテンツの取得

デジタル・ツイン・インスタンス・コンテンツを取得して、最新の正規化された値を確認します。

「デジタル・ツイン・インスタンス」タブで、LG HVAC 1のデジタル・ツイン・インスタンスの詳細ページを開き、最新のコンテンツ値を確認します。
デジタル・ツイン・インスタンスからコンテンツを取得するには、oci iot digital-twin-instance get-contentコマンドを使用します。
```
oci iot digital-twin-instance get-content \
  --digital-twin-instance-id <lg-hvac-1-OCID>
```
GetDigitalTwinInstanceContent操作を実行して、デジタル・ツイン・インスタンスからコンテンツを取得します。

FAQ

このFAQでは、互換性のあるデジタル・ツイン・モデルのアップグレードと追加のペイロード・シェイプについて説明します。

加算ペイロード・シェイプとは何ですか。: 加算ペイロード・シェイプは、既存のペイロード・フィールドを保持し、既存のフィールド名、データ型、意味、単位または制約を変更せずに新しいフィールドを追加します。このシナリオでは、ベース・ペイロード{ "temp": 70, "hum": 60 }が{ "temp": 70, "hum": 60, "ec": 38 }になります。ペイロードは加算的です。これは、tempとhumは依然として同じことを意味し、デバイスはエネルギー消費のためにecのみを追加するためです。
加算ペイロード・シェイプは、デジタル・ツイン・モデル・バージョンとどのように関連しますか。: デバイス・ペイロードとデジタル・ツイン・モデルは一緒に進化する必要があります。新しいデジタル・ツイン・モデル・バージョンでは、既存のtemperatureおよびhumidityテレメトリ互換性を維持しながら、energyConsumptionが追加されます。アップグレードされたデジタル・ツイン・アダプタは、新しいペイロード・フィールドecを新しいデジタル・ツイン・モデル・フィールドenergyConsumptionにマップします。
添加物ではないものは何ですか?: 既存のフィールドの名前の変更、既存のフィールドの削除、スキーマ・タイプの変更、単位または意味の変更、検証制約の絞り込み、コマンド要求または応答契約の変更、または別の主要なデジタル・ツイン・モデル・バージョンへの移動を行う場合、変更は付加的ではありません。たとえば、humをhumidityPctに変更したり、tempを整数から文字列に変更することは加算的ではありません。
古いデバイスは元のペイロードを送信し続けられますか。: はい。アップグレードされたデジタル・ツイン・アダプタ・マッピングで引き続き処理されている場合、古いデバイスは元のフィールドを送信し続けます。新しいフィールドは、アップグレードされたデバイスから送信され、デジタル・ツイン・アダプタによって新しいデジタル・ツイン・モデル・フィールドにマップされる場合にのみ移入されます。

トラブルシューティング

デジタル・ツイン・モデル作成要求が拒否されました

新しいマイナー・デジタル・ツイン・モデル・バージョンでは、新しいコンテンツのみを追加するのではなく、既存の契約要素が変更された可能性があります。古いDTDLデジタルツインモデルと新しいDTDLデジタルツインモデルを比較します。既存の遠隔測定、プロパティー、コマンド、関係、スキーマ、および検証の制約は、互換性を保つ必要があります。

デジタル・ツイン・インスタンス更新リクエストは拒否されました

新しいデジタル・ツイン・アダプタは、互換性のないデジタル・ツイン・モデル・バージョン、別のメジャー・バージョンまたはダウングレードを参照する場合があります。デジタル・ツイン・アダプタで、同じデジタル・ツイン・モデル・バージョンまたはdtmi:com:oracle:example:hvac;1.1などの互換性のある上位マイナー・バージョンが使用されていることを確認します。

アップグレードは成功しますが、新しいフィールドは格納されません。

デジタル・ツイン・インスタンスは、古いデジタル・ツイン・アダプタを引き続き使用するか、アップグレードされたルート・マッピングで新しいペイロード・フィールドをマップしない可能性があります。デジタル・ツイン・インスタンスのデジタル・ツイン・アダプタOCIDを確認し、hvac-e-routes.jsonが$.energyConsumptionを$.ecにマップしていることを確認します。

アップグレード後に既存のテレメトリがありません

アップグレードされたデジタル・ツイン・アダプタ・マッピングにより、既存のペイロード・マッピングが削除されたか、ペイロード・パスが変更された可能性があります。temperatureおよびhumidityの既存のマッピングを保持し、energyConsumptionの新しいマッピングを追加します。

デジタル・ツイン・インスタンスがアップグレードされたデジタル・ツイン・アダプタに移動すると、古いデバイスで障害が発生する

アップグレードされたデジタル・ツイン・アダプタでは、新しいフィールドが必要な場合や、元のペイロード・シェイプがサポートされなくなった場合があります。新しいフィールドを含まないペイロードのデジタル・ツイン・アダプタ・マッピングを許容可能にするか、各デバイス・ペイロード・シェイプの検証後にデバイスを小さいグループに移動してください。

Oracle Cloud Infrastructureドキュメント