データ処理とユーザー定義関数

[アーティクル]
01/03/2020

重要

Azure Digital Twins サービスの新しいバージョンがリリースされました。新しいサービスの拡張機能に照らして、元の Azure Digital Twins サービス (このドキュメントセットで説明) は廃止されました。

新しいサービスのドキュメントを表示するには、アクティブな Azure Digital Twins のドキュメントを参照してください。

Azure Digital Twins は高度な計算機能を備えています。開発者はカスタム関数を定義し、受信したテレメトリメッセージに対して実行し、事前定義したエンドポイントにイベントを送信できます。

データ処理フロー

デバイスによって Azure Digital Twins にテレメトリデータが送信された後で、開発者は "検証"、"照合"、"計算"、"ディスパッチ" という 4 つのフェーズでデータを処理できます。

検証フェーズでは、受信したテレメトリメッセージが一般的に理解できるデータ転送オブジェクトの形式に変換されます。このフェーズでは、デバイスとセンサーも検証されます。
照合フェーズでは、実行する適切なユーザー定義関数が検索されます。事前定義したマッチャーによって、受信したテレメトリメッセージからのデバイス、センサー、空間情報に基づき、ユーザー定義関数が検索されます。
計算フェーズでは、前のフェーズで一致したユーザー定義関数が実行されます。これらの関数により、空間グラフノードで計算値が読み取られたり、更新されたりすることがあります。また、これらの関数ではカスタム通知を送信できます。
ディスパッチフェーズでは、計算フェーズからグラフに定義されているエンドポイントにカスタム通知が送信されます。

データ処理オブジェクト

Azure Digital Twins のデータ処理は、"マッチャー"、"ユーザー定義関数"、"ロールの割り当て" という 3 つのオブジェクトの定義で構成されています。

マッチャー

マッチャーで定義される一連の条件により、受信したセンサーテレメトリに基づいて実行するアクションが判断されます。一致を判断する条件には、センサー、センサーの親デバイス、センサーの親空間からのパラメーターが含まれることがあります。条件は JSON パスに対する比較として表現されます。概要を以下に示します。

エスケープされた String 値 \"Temperature\" によって表されるデータ型 Temperature のすべてのセンサー
ポートに 01 がある
拡張プロパティキー Manufacturer がエスケープされた String 値 \"Contoso\" に設定されているデバイスに属する
エスケープされた String \"Venue\" によって指定された型の空間に属する
親 SpaceId DE8F06CA-1138-4AD7-89F4-F782CC6F69FD の子孫である

{
  "id": "23535afafd-f39b-46c0-9b0c-0dd3892a1c30",
  "name": "My custom matcher",
  "spaceId": "DE8F06CA-1138-4AD7-89F4-F782CC6F69FD",
  "description": "All sensors of datatype Temperature with 01 in their port that belong to devices with the extended property key Manufacturer set to the value Contoso and that belong to spaces of type Venue that are somewhere below space Id DE8F06CA-1138-4AD7-89F4-F782CC6F69FD",
  "conditions": [
    {
      "id": "43898sg43-e15a-4e9c-abb8-2gw464364",
      "target": "Sensor",
      "path": "$.dataType",
      "value": "\"Temperature\"",
      "comparison": "Equals"
    },
    {
      "id": "wt3th44-e15a-35sg-seg3-235wf3ga463",
      "target": "Sensor",
      "path": "$.port",
      "value": "01",
      "comparison": "Contains"
    },
    {
      "id": "735hs33-e15a-37jj-23532-db901d550af5",
      "target": "SensorDevice",
      "path": "$.properties[?(@.name == 'Manufacturer')].value",
      "value": "\"Contoso\"",
      "comparison": "Equals"
    },
    {
      "id": "222325-e15a-49fg-5744-463643644",
      "target": "SensorSpace",
      "path": "$.type",
      "value": "\"Venue\"",
      "comparison": "Equals"
    }
  ]
}

重要

JSON パスでは大文字と小文字が区別されます。
JSON ペイロードは、次によって返されるペイロードと同じです。
- センサーの /sensors/{id}?includes=properties,types。
- センサーの親デバイスの /devices/{id}?includes=properties,types,sensors,sensorsproperties,sensorstypes。
- センサーの親空間の /spaces/{id}?includes=properties,types,location,timezone。
比較では、大文字と小文字は区別されません。

ユーザー定義関数

ユーザー定義関数は、隔離された Azure Digital Twins 環境内で実行されるカスタム関数です。ユーザー定義関数は、生のセンサーテレメトリメッセージの受信時に、それにアクセスします。また、ユーザー定義関数は、空間グラフとディスパッチャーサービスにもアクセスします。ユーザー定義関数がグラフ内に登録されたら、(前述の) マッチャーを作成し、ユーザー定義関数の実行タイミングを指定する必要があります。たとえば、Azure Digital Twins が特定のセンサーから新しいテレメトリを受信すると、一致したユーザー定義関数では、直前の数回分のセンサー読み取り値から移動平均を計算できます。

ユーザー定義関数は、JavaScript で記述できます。ヘルパーメソッドは、ユーザー定義の実行環境でグラフとやり取りします。開発者は、センサーテレメトリメッセージに対してコードのカスタムスニペットを実行できます。以下に例を示します。

グラフ内のセンサーオブジェクトに直接、センサー読み取りを設定します。
グラフの空間内でさまざまなセンサー読み取りに基づいてアクションを実行します。
受信したセンサー読み取りについて特定の条件が満たされるとき、通知を作成します。
通知を送信する前に、センサー読み取りにグラフメタデータを添付します。

詳細については、ユーザー定義関数を使用する方法に関するページを参照してください。

例

Digital Twins の C# サンプルに関する GitHub リポジトリには、ユーザー定義関数の例がいくつか記載されています。

こちらの関数では、二酸化炭素、モーション、および温度の値を取得し、それらの値が範囲内である部屋が使用可能かどうかを判定します。 Digital Twins のチュートリアルでは、この関数について詳しく説明しています。
こちらの関数では、複数のモーションセンサーからデータを取得し、いずれのセンサーからもモーションが検出されなかった場合に、スペースが使用可能であると判定します。クイックスタート (またはチュートリアル) で使用されているユーザー定義関数は、ファイルのコメントセクションで説明されている変更を加えることで、簡単に置き換えることができます。

ロール割り当て

ユーザー定義関数の動作は、サービス内のデータのセキュリティを保護するために、Azure Digital Twins のロールベースのアクセス制御の対象になります。ロールの割り当てによって、どのユーザー定義関数が空間グラフおよびそのエンティティとやり取りする適切なアクセス許可を持つかが定義されます。たとえば、ユーザー定義関数は、特定の空間のグラフデータに対する CREATE、READ、UPDATE、または DELETE の機能とアクセス許可を持つ場合があります。ユーザー定義関数からグラフにデータが要求されるときやユーザー定義関数によってアクションが試行されるとき、ユーザー定義関数のアクセスレベルが確認されます。詳細については、ロールベースのアクセス制御に関するページを参照してください。

ロールが割り当てられていないユーザー定義関数がマッチャーによってトリガーされることがあります。その場合、ユーザー定義関数によるグラフからのデータ読み取りは失敗します。

次のステップ

他の Azure サービスにイベントやテレメトリメッセージをルーティングする方法の詳細については、イベントとメッセージのルーティングに関するページを参照してください。
マッチャー、ユーザー定義関数、ロールの割り当ての作成方法の詳細については、ユーザー定義関数の使用ガイドに関するページを参照してください。
ユーザー定義関数クライアントライブラリリファレンスドキュメントを参照してください。

次の方法で共有