Oracle Cloud Infrastructureドキュメント

デジタル・ツイン・アダプタの作成

デジタル・ツイン・アダプタを作成して、物理デバイスまたは外部システムとの間のRAWデータ・ペイロードを、デジタル・ツイン・モデルに基づく正規化されたテレメトリ・データに変換します。

データおよびマッピングを含むJSONオブジェクトとしてデジタル・ツイン・アダプタに渡されるデータ。

主な概念

構造化データを操作する場合は、デジタル・ツイン・アダプタが必要です。

デジタル・ツイン・アダプタを使用するには、データを送信するようにプログラミングできるかどうかに応じて、次の2つの方法があります。

  • デフォルト・アダプタ形式: 操作する形式でデータを送信するようにデバイスをプログラムできる場合は、inbound-envelopeまたはinbound-routesを指定せずにデジタル・ツイン・アダプタを作成します。その結果、データはデバイスのデフォルト形式で送信されます。エンベロープ・マッピングが指定され、timeObservedが含まれている場合は、receivedTimeがtimeObserved値として使用されます。具体的な例は、シナリオ: HTTPを使用した構造化データのデフォルト・フォーマットでの送信を参照してください。
  • カスタム・アダプタ・フォーマット: データを送信するようにプログラムできないデバイスの場合、カスタム・デジタル・ツイン・アダプタを作成するには、ペイロードおよびメタデータを変換して作業する出力を取得するカスタムinbound-envelopeおよびenvelope-mappingを定義します。具体的な例は、シナリオ: HTTPを使用したカスタム・フォーマットでの構造化データの送信を参照してください。

その他の例は、リファレンス: デジタル・ツイン・モデルおよびアダプタのJQ式およびシナリオを参照してください。

  • 認証ID: デバイスを接続する場合にデジタル・ツイン・アダプタを作成する場合、関連付けられたデジタル・ツイン・インスタンスは、デバイスを認証するために証明書またはシークレットとともに認証IDパラメータを使用する必要があります。
  • 外部キー: デジタル・ツイン・アダプタを作成した後、デジタル・ツイン・アダプタを更新して、デバイスを関連付ける外部キーを変更できます。
  • 制限: デジタル・ツイン・アダプタのインバウンド・ルートの最大数は128です。

JQ Playgroundでアダプタ・マッピングを試行するには、ペイロードを問合せ入力として貼り付け、JSONセクションにJSONマッピングを追加して、出力結果を表示します。

デバイス・ペイロードJSONの例:

{ "time": "<timestamp>", "temp": 65, "hum": 55 }

JQ式を使用するか、JsonPath表記法を使用してアダプタ・ペイロードのJSONマッピング出力を作成します。

この例では、JQ式を使用します。 
{ "temperature": ".temp", "humidity": ".hum", "timeObserved": ".time" }
この例では、JsonPath表記法を使用してアダプタ・ペイロードのJSONマッピング出力を作成します。
{ "temperature": "$.temp", "humidity": "$.hum", "timeObserved": "$.time" }
変換された出力結果:
{ "temperature": 65, "humidity": 55, "timeObserved": "<timestamp>" }

  • デジタル・ツイン・アダプタを作成するには、oci iot digital-twin-adapter createコマンドと必要なパラメータを使用します。

    構造化データ用のデジタル・ツイン・アダプタをデフォルト形式で作成する場合: デバイスをプログラムできる場合は、inbound-envelopeまたはenvelope-mappingを指定せずにデジタル・ツイン・アダプタを作成すると、その結果、デバイスからのデフォルト・データがレスポンスで受け入れられます。

    デジタル・ツイン・モデルを関連付けるための2つのオプション:

    • DTMIの使用:

      次の例では、DTMI URIパラメータを使用して、アダプタをデジタル・ツイン・モデルに関連付けます。<digital-twin-model-spec-uri>を、関連付けられたデジタル・ツイン・モデルのDTMI URIに置き換えます。 
      oci iot digital-twin-adapter create --iot-domain-id <iot-domain-OCID> --digital-twin-model-spec-uri '<digital-twin-model-spec-uri>'
    • デジタル・ツイン・モデルOCIDの使用:
      または、次の例では、デジタル・ツイン・アダプタに関連付けるデジタル・ツイン・モデルの<digital-twin-model-OCID>とともに--digital-twin-model-idパラメータを使用します。
      oci iot digital-twin-adapter create --iot-domain-id <iot-domain-OCID> --digital-twin-model-id <digital-twin-model-OCID>

    構造化データのデジタル・ツイン・アダプタをカスタム・フォーマットで作成するには:

    oci iot digital-twin-adapter createコマンドと必要な--iot-domain-idパラメータを使用します。カスタム・デジタル・ツイン・アダプタを作成するには、作業する出力を取得するための特定のinbound-envelopeまたはinbound-route値を定義し、<file://inbound-envelope.json>ファイルとJQ式を使用した<file://inbound-routes.json>ファイルを使用して、デジタル・ツインのカスタム・ペイロード・マッピングを定義します。

    <digital-twin-model-spec-uri>を、関連付けられたデジタル・ツイン・モデルのDTMI URIに置き換え、<iot-domain-OCID>を、このデジタル・ツイン・アダプタに関連付けるIoTドメインOCIDに置き換えます:

    oci iot digital-twin-adapter create --iot-domain-id <iot-domain-OCID> --digital-twin-model-spec-uri '<digital-twin-model-spec-uri>' --inbound-envelope <file://inbound-envelope.json> --inbound-routes <file://inbound-routes.json>

    ファイルの参照の詳細は、複合入力へのJSONファイルの使用を参照してください。

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

  • CreateDigitalTwinAdapter操作を実行して、指定されたIoTドメインにデジタル・ツイン・アダプタを作成します。