シナリオ: HTTPを使用したデフォルト形式での構造化データの送信

このシナリオでは、デジタル・ツイン・リソースの作成方法、HTTPSまたはMQTTSを介したデフォルト形式またはカスタム形式で構造化テレメトリを送信する方法、および正規化されたデータを表示する方法について説明します。

このシナリオでは、デジタル・ツイン・モデル、デジタル・ツイン・アダプタおよびデジタル・ツイン・インスタンスを使用して、構造化テレメトリを送信します。

デフォルトの形式: IoTプラットフォームで想定されるプロパティ名とデータ構造を送信するようにプログラムできるデバイスに対して、この形式を使用します。デジタルツインモデルに一致するテレメトリを送信するように物理デバイスを構成します。

カスタム形式: デバイスの出力を変更できない場合、この形式を使用します。カスタム・デジタル・ツイン・アダプタ・マッピングを定義して、IoTプラットフォームで認識されるモデル・プロパティに受信データを変換します。

ステップ1: IoTドメイン・グループおよびIoTドメインの作成

既存のIoTドメイン・グループおよびIoTドメインを使用するか、このシナリオ用に作成します。すべてのリソースが同じリージョンにある必要があります。コンソール、CLIおよびAPIの手順については、IoTドメイン・グループの作成およびIoTドメインの作成を参照してください。

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

次のDTDL v3仕様をdigital-twin-model.jsonとして保存します。次のステップでは、両方のアダプタの選択肢がこのHVACモデルを使用します。

{
  "@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"
    },
    {
      "@type": "Property",
      "name": "power",
      "schema": "boolean"
    },
    {
      "@type": "Property",
      "name": "batteryLevel",
      "schema": "integer"
    }
  ]
}

モデルを作成するには、「デジタル・ツイン・モデルの作成」のコンソール手順を使用します。digital-twin-model.jsonの内容をアップロードまたは貼り付けます。
oci iot digital-twin-model createコマンドを使用します:
```
oci iot digital-twin-model create \
  --iot-domain-id <iot-domain-OCID> \
  --spec file://digital-twin-model.json
```
次のステップで、返されたデジタル・ツイン・モデルOCIDを保存します。
CreateDigitalTwinModel操作を実行します。IoTドメインIDを設定し、リクエストのモデル仕様と同じDTDL仕様を使用します。

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

デバイス・ペイロードと一致するアダプタ形式を選択します。

デフォルト・フォーマット: ペイロード・フィールドがデジタル・ツイン・モデルにすでに一致する場合に使用します。インバウンド・エンベロープまたはインバウンド・ルートを指定しないでください。
カスタム・フォーマット: デバイス・ペイロード・フィールドまたはエンベロープを変換する必要がある場合に使用します。インバウンド・エンベロープとインバウンド・ルートの両方を指定します。

カスタム書式マッピング・ファイル

カスタム・フォーマットを選択した場合は、このインバウンド・エンベロープをinbound-envelope.jsonとして保存します。$.timeをtimeObservedにマップします。

{
  "reference-endpoint": "telemetry/health",
  "reference-payload": {
    "data-format": "JSON",
    "data": {
      "time": "<timestamp>",
      "data": {
        "temp": 0,
        "hum": 0,
        "power": false,
        "batteryLevel": 0
      }
    }
  },
  "envelope-mapping": {
    "timeObserved": "$.time"
  }
}

次のインバウンド・ルートをinbound-routes.jsonとして保存します:

[
  {
    "condition": "${endpoint(2) == \"heartbeat\"}",
    "description": "heartbeat",
    "payload-mapping": {
      "$.humidity": "${.hum-1}",
      "$.temperature": "$.temp"
    },
    "reference-payload": {
      "data": {
        "hum": 62,
        "temp": 75
      },
      "data-format": "JSON"
    }
  },
  {
    "condition": "${endpoint(2) == \"health\"}",
    "description": "health",
    "payload-mapping": {
      "$.batteryLevel": "$.batteryPercentage",
      "$.power": "$.on"
    },
    "reference-payload": {
      "data": {
        "batteryPercentage": 60,
        "on": false
      },
      "data-format": "JSON"
    }
  }
]

「デジタル・ツイン・アダプタの作成」のコンソール手順を使用します。
- デフォルト・フォーマット: HVACモデルを選択し、カスタム・インバウンド・エンベロープおよびインバウンド・ルートを空のままにします。
- カスタム形式: HVACモデルを選択し、inbound-envelope.jsonとinbound-routes.jsonの両方を指定します。

デフォルト形式:

oci iot digital-twin-adapter create \
  --iot-domain-id <iot-domain-OCID> \
  --digital-twin-model-spec-uri 'dtmi:com:oracle:example:hvac;1'

カスタム形式:

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://inbound-envelope.json \
  --inbound-routes file://inbound-routes.json

返されたデジタル・ツイン・アダプタOCIDを保存します。

CreateDigitalTwinAdapter操作を実行します。
- デフォルトの形式: IoTドメインおよびモデル仕様URIを設定し、インバウンド・エンベロープおよびインバウンド・ルートを省略します。
- カスタム形式: 同じリソース値を設定し、共有JSONの例からの両方のマッピングを含めます。

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

前のステップのデフォルト・アダプタまたはカスタム・アダプタを使用して、直接接続されたインスタンスを作成します。テストには、デジタル・ツイン・インスタンスのボールト・シークレットを認証IDとして使用します。本番環境では、mTLS証明書を使用します。

「デジタル・ツイン・インスタンスの作成」のコンソール手順を使用します。「直接接続」を選択し、ステップ3で作成したアダプタを選択して、認証OCIDを選択または貼り付けます。

oci iot digital-twin-instance createコマンドを使用します:

oci iot digital-twin-instance create \
  --iot-domain-id <iot-domain-OCID> \
  --display-name <display-name> \
  --auth-id <secret-or-certificate-OCID> \
  --digital-twin-adapter-id <digital-twin-adapter-OCID>

返されたインスタンスのOCIDおよび外部キーを保存します。

CreateDigitalTwinInstance操作を実行します。IoTドメインID、選択したアダプタIDおよびシークレットまたは証明書の認証IDを設定します。

ステップ5: Telemetryデータの送信

デジタル・ツイン・インスタンスの外部キーをデバイス・ユーザー名として認証します。ボールト・シークレットを使用してテストする場合は、そのプレーン・テキストの内容をデバイス・パスワードとして使用します。

ノート

ステップ3のアダプタ選択と一致するペイロードを使用してください。デフォルトのペイロードでは、モデル・プロパティ名が使用されます。カスタム・ペイロードでは、アダプタ・マッピングで定義されたデバイス・フィールド名が使用されます。