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

重要

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

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

Azure Digital Twins には、高度なコンピューティング機能が用意されています。開発者は、受信テレメトリメッセージに対してカスタム関数を定義して実行し、定義済みのエンドポイントにイベントを送信できます。

データ処理フロー

デバイスがテレメトリデータを Azure Digital Twins に送信した後、開発者はデータを検証、照合、 コンピューティング、 ディスパッチの 4 つのフェーズで処理できます。

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

データ処理オブジェクト

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

マッチャー

マッチャーは、受信センサーテレメトリに基づいて実行されるアクションを評価する一連の条件を定義します。一致を判断する条件には、センサーからのプロパティ、センサーの親デバイス、センサーの親空間が含まれる場合があります。条件は、次の例で説明するように JSON パスとの比較として表されます。

エスケープされた文字列値で表されるデータ型 Temperature のすべてのセンサー \"Temperature\"
ポートに01を持っている
拡張プロパティキー Manufacturer がエスケープされた文字列値に設定されているデバイスに属するデバイス \"Contoso\"
エスケープされた文字列で指定された型のスペースに属するもの \"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 サービスにルーティングする方法の詳細については、「イベントとメッセージのルーティング」を参照してください。
マッチャー、ユーザー定義関数、ロールの割り当てを作成する方法の詳細については、ユーザー定義関数を使用するためのガイドを参照してください。
ユーザー定義関数クライアントライブラリのリファレンスドキュメントを確認します。

Last updated on 2020-01-03