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

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

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

概念

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

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

  • デフォルト・アダプタ・フォーマット: 操作するフォーマットでデータを送信するようにデバイスをプログラムできる場合は、inbound-envelopeまたはinbound-routesを指定せずにデジタル・ツイン・アダプタを作成します。レスポンスには、デバイスのデフォルト形式のデータが含まれます。エンベロープ・マッピングが指定され、timeObservedが含まれている場合は、receivedTimetimeObserved値として使用されます。具体的な例は、シナリオ: HTTPを使用した構造化データのデフォルト・フォーマットでの送信を参照してください。
  • カスタム・アダプタ・フォーマット: データを送信するようにプログラムできないデバイスの場合、カスタム・デジタル・ツイン・アダプタを作成するには、ペイロードおよびメタデータを変換して作業する出力を取得するカスタムinbound-envelopeおよびenvelope-mappingを定義します。具体的な例は、シナリオ: HTTPを使用したカスタム・フォーマットでの構造化データの送信を参照してください。
  • 認証ID: デバイスを接続する場合にデジタル・ツイン・アダプタを作成する場合、関連付けられたデジタル・ツイン・インスタンスは、デバイスを認証するために証明書またはシークレットのいずれかとともに認証IDパラメータを使用する必要があります。
  • 外部キー: デジタル・ツイン・アダプタを作成した後、デジタル・ツイン・アダプタを更新してデバイスの外部キーを変更できます。データを送信する場合は、デバイスのユーザー名として外部キーを使用します。
  • 制限: デジタル・ツイン・アダプタのインバウンド・ルートの最大数は128です。
デバイス・ペイロード入力、JSONマッピングおよび変換された結果の例

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

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

  • デバイスが非構造化データを送受信する場合は、デジタルツインアダプタを指定する必要はありません。

    1. 「IoTドメイン」リスト・ページで、操作するIoTドメインを選択します。IoTドメイン・リスト・ページの検索に関するヘルプが必要な場合は、IoTドメインのリストを参照してください。
    2. 「デジタル・ツイン・アダプタ」タブを選択し、「作成」を選択します。
    3. 「名前」およびオプションで「説明」を入力します。機密情報は入力しないでください。
    4. 関連付けるデジタル・ツイン・モデルを検索するには:
      • モデルの選択: 名前でデジタル・ツイン・モデルを検索します。
      • モデル仕様URIを使用して選択: DTMIを使用してデジタル・ツイン・モデルを検索します。たとえば、dtmi:com:example:iot:demo;1
    5. 作業中のデバイスが、特定の形式でデータを送信するようにプログラムできるかどうかによって異なります。
      • 特定の形式でデータを送信するためにデバイスをプログラムできる場合は、アダプタのエンベロープとルートを指定する必要はなく、アダプタはデバイスペイロードから生成されます。
      • 必要な形式でデータを送信するためにデバイスをプログラムできない場合は、受信ペイロードを作業するデータ形式に変換するアダプタを指定します。「インバウンド・エンベロープおよびルートの指定」オプションをオンにします。
        • インバウンド・エンベロープ.jsonファイルのアップロード: このアダプタのインバウンド・エンベロープを含む.jsonファイルをアップロードします。
        • インバウンド・エンベロープJSONの貼付け: インバウンド・エンベロープJSONをこのアダプタに追加します。
    6. インバウンド・ルート仕様: 条件およびオプションのペイロード・マッピングを含むルート定義のリストを追加します。ルートは順番に評価される。
      • インバウンド・ルートの.jsonファイルのアップロード: インバウンド・ルートを.jsonファイルにアップロードします。
      • インバウンド・ルートの貼付けJSON: JSON形式でインバウンド・ルートを追加します。
    7. タグ: (オプション)デジタル・ツイン・アダプタに1つ以上のタグを追加します。リソースを作成する権限がある場合、そのリソースにフリーフォーム・タグを適用する権限もあります。定義済タグを適用するには、タグ・ネームスペースを使用する権限が必要です。タグ付けの詳細は、リソース・タグを参照してください。タグを適用するかどうかわからない場合は、このオプションをスキップするか、管理者に問い合せてください。後でタグを適用できます。
    8. 「作成」を選択します。
  • デジタル・ツイン・アダプタを作成するには、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ドメインにデジタル・ツイン・アダプタを作成します。