设置 IoT 提供程序操作

项目
09/04/2024

设置 IoT（物联网）提供商后，您可以根据从组织的 IoT 设备捕获的数据指定要扳机键的一组操作。除了五个预定义操作外，您还可以创建与提供程序相关联的自定义操作，以自动化 Connected Field Service 操作的各个方面。

Connected Field Service 附带以下操作：

拉取设备数据
注册设备
聚合设备读数
查询设备读数
获取设备事件

拉取设备数据

拉取设备数据操作从 IoT 提供程序提取一个设备或一组设备的最新数据。它将显示在设备数据历史记录选项卡中。

因为数据可以来自多个设备，所以拉取设备数据操作需要 EntityCollection 作为输入。下表介绍了 EntityCollection 的参数。

参数	类型	Details
msdyn_iotdeviceid	string	Connected Field Service 中的 GUID 设备 ID (msdyn_iotdevice)，已转换为字符串
msdyn_name	string	设备的名称
@odata.type	string	实体的 OData 类型

示例输入：

{
  "EntityCollection":[
      {
    "msdyn_iotdeviceid":"B25B5E21-326E-4C36-9296-C195286DGEC9",
    "msdyn_name":" HVAC 32443",
    "@odata.type":"Microsoft.Dynamics.CRM.msdyn_iotdevice"
      },
      {
    "msdyn_iotdeviceid":"B25B5E21-326E-4C36-9296-C195286DGEE9",
    "msdyn_name":" HVAC 92232",
    "@odata.type":"Microsoft.Dynamics.CRM.msdyn_iotdevice"
      }
  ]
}

拉取设备数据操作以序列化 JSON 格式返回提取的数据。下表介绍了 PullDeviceDataResultsJSON 输出的参数。

JSON 属性	类型	Details
ID	string	Connected Field Service 中的 GUID 设备 ID (msdyn_iotdevice)，已转换为字符串
ConnectionState	boolean	设备是断开连接 (false) 还是已连接 (true)
ConnectionStateUpdatedTime	datetime	来自 IoT 提供程序的上次连接状态更新的时间戳
DeviceReportedProperties	string	设备的报告属性，格式为 JSON 字符串
LastActivityTime	datetime	设备的上次报告活动的时间戳

示例输出：

{
  "PullDeviceDataResultsJSON":[
     {
    "Id":"B25B5E21-326E-4C36-9296-C195286DGEC9",
    "ConnectionState":true,
    "ConnectionStateUpdatedTime":"2019-08-2911:00:00",
    "DeviceReportedProperties":{
      "temperature":65.6366305680316,
      "humidity":21.3333366666
      },
    "LastActivityTime": "2019-08-2011:00:00"
    },
    {
    "Id":"B25B5E21-326E-4C36-9296-C195286DGEE9",
    "ConnectionState":true,
    "ConnectionStateUpdatedTime":"2019-08-2911:00:00",
    "DeviceReportedProperties":{
      "temperature":62.8366305680316,
      "humidity":19.5333366666
    },
    "LastActivityTime": "2019-08-2011:00:00"
     }
  ]
}

注册设备

注册设备操作在设备或设备集合与 IoT 提供程序之间创建关联。可以注册技术人员更换的新设备和设备或组件。注册设备后，它会出现在 IoT 设备记录的注册历史记录选项卡中。

因为一次可以注册多个设备，所以注册设备操作需要 EntityCollection 作为输入。下表介绍了 EntityCollection 的参数。

参数	类型	Details
msdyn_iotdeviceid	string	Connected Field Service 中的 GUID 设备 ID (msdyn_iotdevice)，已转换为字符串
msdyn_name	string	设备的名称
@odata.type	string	实体的 OData 类型

示例输入：

{
  "EntityCollection": [
    {
      "msdyn_iotdeviceid": "5754578D-1F9A-4720-BC21-3C3042C05B2F",
      "msdyn_name": "Coffee maker 1",
      "@odata.type": "Microsoft.Dynamics.CRM.msdyn_iotdevice"
    },
    {
      "msdyn_iotdeviceid": "5754578D-1F9A-4720-BC21-3C3042C06C5F",
      "msdyn_name": "Coffee maker 2",
      "@odata.type": "Microsoft.Dynamics.CRM.msdyn_iotdevice"
    }
  ]
}

注册设备操作以序列化 JSON 格式返回注册结果。下表介绍了 RegistrationResultsJSON 输出的参数。

JSON 属性	类型	Details
ID	string	Connected Field Service 中的 GUID 设备 ID (msdyn_iotdevice)，已转换为字符串
RegistrationStatus	OptionSetValue	从 IoT 提供程序注册回 Connected Field Service 的状态值和标签： - 192350000：未知 - 192350001：未注册 - 192350002：正在进行 - 192350003：已注册 - 192350004：错误注意：OptionSet 是具有标签值映射的选项列表，如 drop-down list 控件。
DeviceId	string	IoT 提供程序系统中设备的 ID
邮件	string	向 Connected Field Service 用户发送的有关注册的详细消息

示例输出：

{
   "RegistrationResultsJSON":[
      {
         "Id":"5754578D-1F9A-4720-BC21-3C3042C05B2F",
         "RegistrationStatus":{"Value":192350003},
         "DeviceId":"DeviceIdFromThirdPartyOrUserDefined",
         "Message":"Registration info/warning/error message"   
      },
      {
         "Id":"5754578D-1F9A-4720-BC21-3C3042C06C5F",
         "RegistrationStatus":{"Value":192350003},
         "DeviceId":"DeviceIdFromThirdPartyOrUserDefined",
         "Message":"Registration info/warning/error message"   
      }   
  ]
}

聚合设备读数

聚合设备读数操作从 IoT 提供程序获取聚合设备数据。聚合数据提供 Connected Field Service 中摘要磁贴上设备状况的快速快照。

Field Service 中的 IoT 设备的屏幕截图，显示聚合读数。

下表介绍了聚合设备读数操作的输入参数。

参数	类型	Details
deviceId	string	Connected Field Service 中的 GUID 设备 ID (msdyn_iotdevice)，已转换为字符串
measures	string	JSON 格式的度量列表；示例请参见以下代码片段

示例输入：

[
    {
        "Measure":"Humidity",
        "Aggregate":"Min",
        "TimeRangeType":"Days",
        "TimeRangeValue":7
    },
    {
        "Measure":"Temperature",
        "Aggregate":"Avg",
        "TimeRangeType":"Days",
        "TimeRangeValue":14
    }
]

聚合设备读数操作以序列化 JSON 格式返回度量。下表显示了输出参数。

JSON 属性	类型	Details
measuresOutput	string	JSON 格式的返回的度量的值；示例请参见以下代码片段

示例输出：

[
    {
        "Name":"Humidity",
        "Aggregate":"Min",
        "Unit":"F",
        "TimeRangeValue":7,
        "TimeRangeType":"Days",
        "Position":1,
        "Value":"39.13334"
    },
    {
        "Name":"Temperature",
        "Aggregate":"Avg",
        "Unit":"F",
        "TimeRangeValue":14,
        "TimeRangeType":"Days",
        "Position":2,
        "Value":"65.13334"
    }
]

如果您未使用聚合设备读数操作，聚合设备读数基于设备数据历史记录实体。

查询设备读数

查询设备读数操作从 IoT 提供程序获取历史设备数据（如温度和湿度），并将其显示为时间序列图。

一段时间的设备温度和湿度的屏幕截图。

下表介绍了查询设备读数操作的输入参数。

参数	类型	Details
From	datetime	ISO 格式的读取（度量）开始时间；例如，“2020-04-10T13:51:55.781Z”
操作	datetime	ISO 格式的读取（度量）结束时间
IoTDeviceId	string	Connected Field Service 中的 GUID 设备 ID (msdyn_iotdevice)，已转换为字符串
间隔	string	以 ISO-8601 持续时间格式指定的绘图点的间隔大小；例如，1 分钟是“PT1M”，1 毫秒是“PT0.001S” 所有间隔都具有相同大小。一个月始终需要转换为 30 天，一年始终为 365 天。

示例输入：

{
    "From":"2023-04-01T18:05:37.661Z", 

    "To":"2023-05-31T18:05:37.661Z", 

    "IotDeviceId":"50fce36f-9e3e-ed11-bba3-000d3a8b1de9", 

    "Interval":"P1D"
}

查询设备读数操作以序列化 JSON 格式返回数据。下表显示了输出参数。

JSON 属性	类型	Details
AggregatedDeviceReadings	String	JSON 格式的返回的度量的值；示例请参见以下代码片段

示例输出：

{
  "HVAC Unit 123": {
    "Temperature": {
      "2017-04-01T06:00:00Z": {
        "min": -29,
        "max": 62.59,
        "avg": 16.89,
        "sum": 4054.14,
        "count": 240
      },
      "2017-04-01T08:00:00Z": {
        "min": -29,
        "max": 62.59,
        "avg": 16.89,
        "sum": 4054.14,
        "count": 480
      }
    },
    "Humidity": {
      "2017-04-01T06:00:00Z": {
        "min": 10,
        "max": 48.3,
        "avg": 29.25,
        "sum": 7020.62,
        "count": 240
      },
      "2017-04-01T08:00:00Z": {
        "min": 10,
        "max": 48.3,
        "avg": 29.25,
        "sum": 7020.62,
        "count": 480
      }
    }
  }
}

获取设备事件

“获取设备事件”操作从设备服务历史记录提取事件，并将它们显示为“查询设备读数”操作创建的图表底部的图钉。您可以包括任何自定义实体，如上次执行资产升级的时间。

在一段时间的设备温度和湿度图下显示为图钉的事件的屏幕截图。

备注

您不需要创建新操作。在 msdyn_IoTGetDeviceEvents 操作上注册自定义插件，如创建事件的插件。

下表介绍了获取设备事件操作的输入参数。

JSON 属性	类型	Details
From	datetime	ISO 格式的读取（度量）开始时间；例如，“2020-04-10T13:51:55.781Z”
操作	datetime	ISO 格式的读取（度量）结束时间
IoTDeviceId	string	Connected Field Service 中的 GUID 设备 ID (msdyn_iotdevice)，已转换为字符串

示例输入：

{ 
    "IotDeviceId": "50fce36f-9e3e-ed11-bba3-000d3a8b1de9", 
    "From": "2023-06-12T18:57:54.864Z", 
    "To": "2023-06-12T19:57:54.864Z" 
}

获取设备事件操作以序列化 JSON 格式返回数据。下表显示了输出参数。

JSON 属性	类型	Details
EventsName	string	事件类别的简短说明；使用它可以显示或隐藏该类别中的所有事件
时间戳	string	格式为 ISO 格式的字符串的事件的时间戳；事件图钉的 x 轴时间戳
Color	string	以十六进制代码字符串形式提供的事件图钉的颜色
说明	string	事件的简短说明，在用户将鼠标悬停在图钉上或选择图钉以查看详细信息时显示
ID	string	事件的 ID；可以是名称或其他用户友好值，如工作订单编号或预订确认码
Entity	string	与事件相关的 Dataverse 实体名称；例如，“msdyn_workorder”
URL	string	事件的详细信息页面的 URL，如工作订单窗体的链接如果您传递实体和 GUID，系统会自动生成超链接。
GUID	string	Dataverse 中实体记录的 GUID，转换为字符串

示例输出：

{
  "Service History": {
    "2019-08-07T19:14:53Z": {
      "color": "#FF6300",
      "description": "Work Order Created",
      "id": "00001",
      "entity": "msdyn_workorder",
      "url": "",
      "guid": "952a7592-8818-ea11-a811-000d3a5466d7"
    },
    "2019-08-08T19:14:53Z": {
      "color": "#ECC5AC",
      "description": "Work Order Created",
      "id": "00002",
      "entity": "msdyn_workorder",
      "url": "",
      "guid": "952a7592-8818-ea11-a811-000d3a5466d9"
    },
    "2019-09-21T09:34:53Z": {
      "color": "#ECC5AC",
      "description": "Case Created",
      "id": "000121",
      "entity": "msdyn_incident",
      "url": "",
      "guid": "952a7592-8818-ea11-a811-000d3a5466d0"
    }
  },
  "Asset History": {
    "2019-08-07T19:14:53Z": {
      "color": "#FF6400",
      "description": "Asset Model Upgraded",
      "id": "001223",
      "entity": "new_assetupgraded",
      "url": "",
      "guid": "952a7592-8818-ea11-a811-000d3a5466d7"
    }
  }
}

通过

设置 IoT 提供程序操作

拉取设备数据

注册设备

聚合设备读数

查询设备读数

获取设备事件

后续步骤

反馈

其他资源