データ処理とユーザー定義関数Data processing and user-defined functions

Azure Digital Twins は高度な計算機能を備えています。Azure Digital Twins offers advanced compute capabilities. 開発者はカスタム関数を定義し、受信したテレメトリ メッセージに対して実行し、事前定義したエンドポイントにイベントを送信できます。Developers can define and run custom functions against incoming telemetry messages to send events to predefined endpoints.

データ処理フローData processing flow

デバイスによって Azure Digital Twins にテレメトリ データが送信された後で、開発者は "検証"、"照合"、"計算"、"ディスパッチ" という 4 つのフェーズでデータを処理できます。After devices send telemetry data to Azure Digital Twins, developers can process data in four phases: validate, match, compute, and dispatch.

Azure Digital Twins のデータ処理フロー

  1. 検証フェーズでは、受信したテレメトリ メッセージが一般的に理解できるデータ転送オブジェクトの形式に変換されます。The validate phase transforms the incoming telemetry message to a commonly understood data transfer object format. このフェーズでは、デバイスとセンサーも検証されます。This phase also executes device and sensor validation.
  2. 照合フェーズでは、実行する適切なユーザー定義関数が検索されます。The match phase finds the appropriate user-defined functions to run. 事前定義したマッチャーによって、受信したテレメトリ メッセージからのデバイス、センサー、空間情報に基づき、ユーザー定義関数が検索されます。Predefined matchers find the user-defined functions based on the device, sensor, and space information from the incoming telemetry message.
  3. 計算フェーズでは、前のフェーズで一致したユーザー定義関数が実行されます。The compute phase runs the user-defined functions matched in the previous phase. これらの関数により、空間グラフノードで計算値が読み取られたり、更新されたりすることがあります。また、これらの関数ではカスタム通知を送信できます。These functions might read and update computed values on spatial graph nodes and can emit custom notifications.
  4. ディスパッチ フェーズでは、計算フェーズからグラフに定義されているエンドポイントにカスタム通知が送信されます。The dispatch phase routes any custom notifications from the compute phase to endpoints defined in the graph.

データ処理オブジェクトData processing objects

Azure Digital Twins のデータ処理は、"マッチャー"、"ユーザー定義関数"、"ロールの割り当て" という 3 つのオブジェクトの定義で構成されています。Data processing in Azure Digital Twins consists of defining three objects: matchers, user-defined functions, and role assignments.

Azure Digital Twins のデータ処理オブジェクト

マッチャーMatchers

マッチャーで定義される一連の条件により、受信したセンサー テレメトリに基づいて実行するアクションが判断されます。Matchers define a set of conditions that evaluate what actions take place based on incoming sensor telemetry. 一致を判断する条件には、センサー、センサーの親デバイス、センサーの親空間からのパラメーターが含まれることがあります。Conditions to determine the match might include properties from the sensor, the sensor's parent device, and the sensor's parent space. 条件は JSON パスに対する比較として表現されます。概要を以下に示します。The conditions are expressed as comparisons against a JSON path as outlined in this example:

  • エスケープされた String 値 \"Temperature\" によって表されるデータ型 Temperature のすべてのセンサーAll sensors of datatype Temperature represented by the escaped String value \"Temperature\"
  • ポートに 01 があるHaving 01 in their port
  • 拡張プロパティ キー Manufacturer がエスケープされた String 値 \"GoodCorp\" に設定されているデバイスに属するWhich belong to devices with the extended property key Manufacturer set to the escaped String value \"GoodCorp\"
  • エスケープされた String \"Venue\" によって指定された型の空間に属するWhich belong to spaces of the type specified by the escaped String \"Venue\"
  • SpaceId DE8F06CA-1138-4AD7-89F4-F782CC6F69FD の子孫であるWhich are descendants of parent SpaceId DE8F06CA-1138-4AD7-89F4-F782CC6F69FD
{
  "SpaceId": "DE8F06CA-1138-4AD7-89F4-F782CC6F69FD",
  "Name": "My custom matcher",
  "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 GoodCorp and that belong to spaces of type Venue that are somewhere below space Id DE8F06CA-1138-4AD7-89F4-F782CC6F69FD",
  "Conditions": [
    {
      "target": "Sensor",
      "path": "$.dataType",
      "value": "\"Temperature\"",
      "comparison": "Equals"
    },
    {
      "target": "Sensor",
      "path": "$.port",
      "value": "01",
      "comparison": "Contains"
    },
    {
      "target": "SensorDevice",
      "path": "$.properties[?(@.name == 'Manufacturer')].value",
      "value": "\"GoodCorp\"",
      "comparison": "Equals"
    },
    {
      "target": "SensorSpace",
      "path": "$.type",
      "value": "\"Venue\"",
      "comparison": "Equals"
    }
  ]
}

重要

  • JSON パスでは大文字と小文字が区別されます。JSON paths are case sensitive.
  • JSON ペイロードは、次によって返されるペイロードと同じです。The JSON payload is the same as the payload that's returned by:
    • センサーの /sensors/{id}?includes=properties,types/sensors/{id}?includes=properties,types for the sensor.
    • センサーの親デバイスの /devices/{id}?includes=properties,types,sensors,sensorsproperties,sensorstypes/devices/{id}?includes=properties,types,sensors,sensorsproperties,sensorstypes for the sensor's parent device.
    • センサーの親空間の /spaces/{id}?includes=properties,types,location,timezone/spaces/{id}?includes=properties,types,location,timezone for the sensor's parent space.
  • 比較では、大文字と小文字は区別されません。The comparisons are case insensitive.

ユーザー定義関数User-defined functions

ユーザー定義関数は、隔離された Azure Digital Twins 環境内で実行されるカスタム関数です。A user-defined function is a custom function executed within an isolated Azure Digital Twins environment. ユーザー定義関数は、生のセンサー テレメトリ メッセージの受信時に、それにアクセスします。User-defined functions have access to raw sensor telemetry message as it gets received. また、ユーザー定義関数は、空間グラフとディスパッチャー サービスにもアクセスします。User-defined functions also have access to the spatial graph and dispatcher service. ユーザー定義関数がグラフ内に登録されたら、(前述の) マッチャーを作成し、ユーザー定義関数の実行タイミングを指定する必要があります。After the user-defined function is registered within a graph, a matcher (detailed above) must be created to specify when the function is executed. たとえば、Azure Digital Twins が特定のセンサーから新しいテレメトリを受信すると、一致したユーザー定義関数では、直前の数回分のセンサー読み取り値から移動平均を計算できます。For example, when Azure Digital Twins receives new telemetry from a given sensor, the matched user-defined function can calculate a moving average of the last few sensor readings.

ユーザー定義関数は、JavaScript で記述できます。User-defined functions can be written in JavaScript. ヘルパー メソッドは、ユーザー定義の実行環境でグラフとやり取りします。Helper methods interact with the graph in the user-defined execution environment. 開発者は、センサー テレメトリ メッセージに対してコードのカスタム スニペットを実行できます。Developers can execute custom snippets of code against sensor telemetry messages. たとえば、次のようになります。Examples include:

  • グラフ内のセンサー オブジェクトに直接、センサー読み取りを設定します。Set the sensor reading directly onto the sensor object within the graph.
  • グラフの空間内でさまざまなセンサー読み取りに基づいてアクションを実行します。Perform an action based on different sensor readings within a space in the graph.
  • 受信したセンサー読み取りについて特定の条件が満たされるとき、通知を作成します。Create a notification when certain conditions are met for an incoming sensor reading.
  • 通知を送信する前に、センサー読み取りにグラフ メタデータを添付します。Attach graph metadata to the sensor reading before sending out a notification.

詳細については、ユーザー定義関数を使用する方法に関するページを参照してください。For more information, see How to use user-defined functions.

Examples

Digital Twins の C# サンプルに関する GitHub リポジトリには、ユーザー定義関数の例がいくつか記載されています。The GitHub repo for the Digital Twins C# sample contains a few examples of the user-defined functions:

  • こちらの関数では、二酸化炭素、モーション、および温度の値を取得し、それらの値が範囲内である部屋が使用可能かどうかを判定します。This function looks for carbon dioxide, motion, and temperature values to determine whether a room is available with these values in range. Digital Twins のチュートリアルでは、この関数について詳しく説明しています。The tutorials for Digital Twins explore this function in more details.
  • こちらの関数では、複数のモーション センサーからデータを取得し、いずれのセンサーからもモーションが検出されなかった場合に、スペースが使用可能であると判定します。This function looks for data from multiple motion sensors, and determines that the space is available if none of them detect any motion. クイック スタート (またはチュートリアル) で使用されているユーザー定義関数は、ファイルのコメント セクションで説明されている変更を加えることで、簡単に置き換えることができます。You can easily replace the user-defined function used in either the quickstart, or the tutorials, by making the changes mentioned in the comments section of the file.

ロール割り当てRole assignment

ユーザー定義関数の動作は、サービス内のデータのセキュリティを保護するために、Azure Digital Twins のロールベースのアクセス制御の対象になります。A user-defined function's actions are subject to Azure Digital Twins role-based access control to secure data within the service. ロールの割り当てによって、どのユーザー定義関数が空間グラフおよびそのエンティティとやり取りする適切なアクセス許可を持つかが定義されます。Role assignments define which user-defined functions have the proper permissions to interact with the spatial graph and its entities. たとえば、ユーザー定義関数は、特定の空間のグラフ データに対する CREATEREADUPDATE、または DELETE の機能とアクセス許可を持つ場合があります。For example, a user-defined function might have the ability and permission to CREATE, READ, UPDATE, or DELETE graph data under a given space. ユーザー定義関数からグラフにデータが要求されるときやユーザー定義関数によってアクションが試行されるとき、ユーザー定義関数のアクセス レベルが確認されます。A user-defined function's level of access is checked when the user-defined function asks the graph for data or attempts an action. 詳細については、ロールベースのアクセス制御に関するページを参照してください。For more information, see Role-based access control.

ロールが割り当てられていないユーザー定義関数がマッチャーによってトリガーされることがあります。It's possible for a matcher to trigger a user-defined function that has no role assignments. その場合、ユーザー定義関数によるグラフからのデータ読み取りは失敗します。In this case, the user-defined function fails to read any data from the graph.

次の手順Next steps