シナリオ: HTTPを使用したカスタム形式での構造化データの送信

1. インバウンド・エンベロープfile://inbound-envelope.jsonを定義して、デバイスのペイロードからメタデータを抽出する方法を指定します。受信JSONから$.timeの値を抽出し、デジタル・ツイン・モデルのtimeObservedフィールドにマップします。これらのマッピングにより、JQ式を使用してタイムスタンプなどの特定のメタデータを抽出できます。

   この例では、デバイス・エンドポイント、サンプル・ペイロード、およびJQ式を適用してデータを抽出または再形成するインバウンド・エンベロープ・マッピングを示します。

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

2. file://inbound-routes.jsonファイルを作成して、デバイス・メッセージからの特定のペイロード・データをデジタル・ツイン・インスタンスにマッピングおよびルーティングする方法を定義します。

   各ルートには、エンドポイントに一致する条件、参照ペイロード構造、および値を転送または変換するためのマッピング指示が含まれます。

   この例は、定義された2つのペイロード条件を示しています。
   ノート
   
   許可されるインバウンド・ルートの最大数は128です。

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

3. oci iot digital-twin-adapter createコマンドを使用して、デジタル・ツイン・アダプタを作成します。<iot-domain-OCID>をIoTドメインのOCIDに置き換え、<dtmi:com:oracle:example:hvac>を、このデジタル・ツイン・アダプタに関連付けるデジタル・ツイン・モデルのDTMI URIでDTMI URIに置き換えます。

   次の例では、DTMI URIパラメータを使用してデジタルツインモデルを関連付けます。または、このデジタル・ツイン・アダプタに関連付けるデジタル・ツイン・モデルに対して、--digital-twin-model-idパラメータを<digital-twin-model-OCID>とともに使用できます。

   前のステップで作成したファイルfile://inbound-enevelop.jsonおよびfile://inbound-enevelop.jsonを参照します。

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

   このレスポンス例では、jsonファイルを参照して、--inbound-envelopeおよび--inbound-routesオプションで定義されたカスタム・ペイロード・マッピングと、一意のDTMI URIおよびデジタル・ツイン・モデルOCIDを持つ特定のデジタル・ツイン・モデルに関連付けられている特定のデジタル・ツイン・アダプタOCIDを示します。

   dtmi:com:oracle:example:core:hvac: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:hvac;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": "telemetry/health",
         "reference-payload": {
           "data": {
             "time": "2025-09-11T06:09:27.878106Z"
           },
           "data-format": "JSON"
         }
       },
       "inbound-routes": [
         {
           "condition": "${endpoint(2) == \"heartbeat\"}",
           "description": null,
           "payload-mapping": {
             "$.humidity": "${.hum-1}",
             "$.temperature": "$.temp"
           },
           "reference-payload": {
             "data": {
               "hum": 62,
               "temp": 75
             },
             "data-format": "JSON"
           }
         },
         {
           "condition": "${endpoint(2) == \"health\"}",
           "description": null,
           "payload-mapping": {},
           "reference-payload": {
             "data": {
               "batteryPercentage": 60,
               "on": false
             },
             "data-format": "JSON"
           }
         }
       ],
       "iot-domain-id": "<iot-domain-OCID>",
       "lifecycle-state": "ACTIVE",
       "system-tags": {},
       "time-created": "2025-09-30T19:55:36.293000+00:00",
       "time-updated": "2025-09-30T19:55:36.293000+00:00"
     },
     "etag": "<unique-id>"
   }
   

デジタル・ツイン・インスタンスを作成するには、oci iot digital-twin-instance create、<iot-domain-OCID>および<certificate-or-secret-OCID>の必須パラメータを使用します。<certificate-or-secret-OCID>を、使用するボールト・シークレットOCIDに置き換え、<iot-domain-OCID>を環境のIoTドメインのOCIDに置き換えます。

デジタル・ツイン・インスタンスがデバイス・データを受信するように設定されている場合、デジタル・ツインが認証できるように、ボールト・シークレットまたは証明書OCIDとともに認証IDパラメータを使用する必要があります。これを行うには、他の関連するIoTリソースと同じリージョンおよびテナンシにシークレットを作成するか、証明書を作成します。

この例では、--display-nameオプションを使用し、<your-digital-twin-instance-name>をデジタル・ツイン・インスタンスのわかりやすい名前に置き換えます。

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

dtmi:com:oracle:example:hvac;1

{
  "data": {
    "auth-id": "<vault-secret-OCID>",
    "defined-tags": {
      "Oracle-Tags": {
        "CreatedBy": "default/user@oracle.com",
        "CreatedOn": "2025-08-14T17:41:11.973Z"
      }
    },
    "description": null,
    "digital-twin-adapter-id": "<iot-digital-twin-adapter-OCID>",
    "digital-twin-model-id": "<digital-twin-model-OCID>",
    "digital-twin-model-spec-uri": "dtmi:com:oracle:example:hvac;1",
    "display-name": "<your-digital-twin-instance-name>",
    "external-key": "<digital-twin-instance-external-key>",
    "freeform-tags": {},
    "id": "<digital-twin-instance-OCID>",
    "iot-domain-id": "<iot-domain-OCID>",
    "lifecycle-state": "ACTIVE",
    "system-tags": {},
    "time-created": "2025-08-14T17:41:13.638000+00:00",
    "time-updated": "2025-08-14T17:41:13.638000+00:00"
  },
  "etag": "<unique-id>"
}

この例では、HTTPを使用します。または、MQTTおよびMQTTをWebSockets上で使用できます。具体的な例は、シナリオを参照してください。

curl -H "Authorization: Bearer <token>" \
     -X GET "https://<domain-group-short-id>.data.iot.<region>.oci.oraclecloud.com/ords/<domain-short-id>/20250531/rawData?q={\"$and\":[{\"digital_twin_instance_id\":\"<iot-digital-twin-OCID>\"}]}"

select * from <domain-short-id-from-device-host>__IOT.RAW_DATA where digital_twin_instance_id = '<iot-digital-twin-OCID>';

または、このSQL文を使用して、rejectedテレメトリ・データを表示します。<domain-short-id-from-device-host>をIoTドメインのドメイン短縮ID、<iot-digital-twin-OCID>を、拒否されたデータを表示するデジタル・ツインのOCIDに置き換えます。

select * from <domain-short-id-from-device-host>__IOT.REJECTED_DATA where digital_twin_instance_id = '<digital-twin-OCID>';

select * from <domain-short-id-from-device-host>__IOT.HISTORIZED_DATA where digital_twin_id = '<digital-twin-OCID>';