您现在访问的是微软AZURE全球版技术文档网站,若需要访问由世纪互联运营的MICROSOFT AZURE中国区技术文档网站,请访问 https://docs.azure.cn.

数据处理和用户定义的函数Data processing and user-defined functions

Azure 数字孪生提供高级计算功能。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 数字孪生后,开发人员可以分四个阶段处理数据:验证匹配计算调度After devices send telemetry data to Azure Digital Twins, developers can process data in four phases: validate, match, compute, and dispatch.

Azure 数字孪生数据处理流Azure Digital Twins data processing flow

  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 数字孪生中的数据处理包括定义三个对象:匹配程序用户定义的函数角色分配Data processing in Azure Digital Twins consists of defining three objects: matchers, user-defined functions, and role assignments.

Azure 数字孪生数据处理对象Azure Digital Twins data processing objects

匹配程序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:

  • 所有数据类型为 Temperature 的传感器,由转义的字符串值 \"Temperature\" 表示All sensors of datatype Temperature represented by the escaped String value \"Temperature\"
  • 其端口中包含 01Having 01 in their port
  • 属于扩展属性键 Manufacturer 设置为转义字符串值 \"Contoso\" 的设备Which belong to devices with the extended property key Manufacturer set to the escaped String value \"Contoso\"
  • 属于转义字符串 \"Venue\" 指定的类型的空间Which belong to spaces of the type specified by the escaped String \"Venue\"
  • 这是父SpaceId的后代 DE8F06CA-1138-4AD7-89F4-F782CC6F69FDWhich are descendants of parent 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 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 数字孪生环境中执行的自定义函数。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 数字孪生从给定传感器收到新的遥测数据时,匹配的用户定义的函数可以计算最后几个传感器读数的移动平均值。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, read How to use user-defined functions.

示例Examples

数字孪生 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. 数字孪生教程更详细地探究了此函数。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 数字孪生基于角色的访问控制的约束,以保护服务中的数据。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. 例如,用户定义的函数可能具有在给定空间创建、读取、更新或删除图形数据的功能和权限。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, read 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