充当事件网格源的 Azure IoT 中心Azure IoT Hub as an Event Grid source

本文提供 Azure IoT 中心事件的属性和架构。This article provides the properties and schema for Azure IoT Hub events. 有关事件架构的简介,请参阅 Azure 事件网格事件架构For an introduction to event schemas, see Azure Event Grid event schema.

可用事件类型Available event types

Azure IoT 中心发出以下事件类型:Azure IoT Hub emits the following event types:

事件类型Event type 说明Description
Microsoft.Devices.DeviceCreatedMicrosoft.Devices.DeviceCreated 当设备注册到 IoT 中心时发布。Published when a device is registered to an IoT hub.
Microsoft.Devices.DeviceDeletedMicrosoft.Devices.DeviceDeleted 当设备从 IoT 中心删除时发布。Published when a device is deleted from an IoT hub.
Microsoft.Devices.DeviceConnectedMicrosoft.Devices.DeviceConnected 当设备连接到 IoT 中心时发布。Published when a device is connected to an IoT hub.
Microsoft.Devices.DeviceDisconnectedMicrosoft.Devices.DeviceDisconnected 当设备与 IoT 中心断开连接时发布。Published when a device is disconnected from an IoT hub.
Microsoft.Devices.DeviceTelemetryMicrosoft.Devices.DeviceTelemetry 当遥测消息发送到 IoT 中心时发布。Published when a telemetry message is sent to an IoT hub.

示例事件Example event

DeviceConnected 和 DeviceDisconnected 事件的架构具有相同结构。The schema for DeviceConnected and DeviceDisconnected events have the same structure. 此示例事件显示设备连接到 IoT 中心时引发的事件的架构:This sample event shows the schema of an event raised when a device is connected to an IoT hub:

[{
  "id": "f6bbf8f4-d365-520d-a878-17bf7238abd8", 
  "topic": "/SUBSCRIPTIONS/<subscription ID>/RESOURCEGROUPS/<resource group name>/PROVIDERS/MICROSOFT.DEVICES/IOTHUBS/<hub name>", 
  "subject": "devices/LogicAppTestDevice", 
  "eventType": "Microsoft.Devices.DeviceConnected", 
  "eventTime": "2018-06-02T19:17:44.4383997Z", 
  "data": {
    "deviceConnectionStateEventInfo": {
      "sequenceNumber":
        "000000000000000001D4132452F67CE200000002000000000000000000000001"
    },
    "hubName": "egtesthub1",
    "deviceId": "LogicAppTestDevice",
    "moduleId" : "DeviceModuleID"
  }, 
  "dataVersion": "1", 
  "metadataVersion": "1" 
}]

将遥测事件发送到 IoT 中心时,将引发 DeviceTelemetry 事件。The DeviceTelemetry event is raised when a telemetry event is sent to an IoT Hub. 此事件的示例架构如下所示。A sample schema for this event is shown below.

[{
  "id": "9af86784-8d40-fe2g-8b2a-bab65e106785",
  "topic": "/SUBSCRIPTIONS/<subscription ID>/RESOURCEGROUPS/<resource group name>/PROVIDERS/MICROSOFT.DEVICES/IOTHUBS/<hub name>", 
  "subject": "devices/LogicAppTestDevice", 
  "eventType": "Microsoft.Devices.DeviceTelemetry",
  "eventTime": "2019-01-07T20:58:30.48Z",
  "data": {        
      "body": {            
          "Weather": {                
              "Temperature": 900            
          },
          "Location": ""        
      },
        "properties": {            
          "Status": "Active"        
        },
        "systemProperties": {            
            "iothub-content-type": "application/json",
            "iothub-content-encoding": "utf-8",
            "iothub-connection-device-id": "d1",
            "iothub-connection-auth-method": "{\"scope\":\"device\",\"type\":\"sas\",\"issuer\":\"iothub\",\"acceptingIpFilterRule\":null}",
            "iothub-connection-auth-generation-id": "123455432199234570",
            "iothub-enqueuedtime": "2019-01-07T20:58:30.48Z",
            "iothub-message-source": "Telemetry"        
        }    
    },
  "dataVersion": "",
  "metadataVersion": "1"
}]

DeviceCreated 和 DeviceDeleted 事件的架构具有相同结构。The schema for DeviceCreated and DeviceDeleted events have the same structure. 此示例事件显示设备注册到 IoT 中心时引发的事件的架构:This sample event shows the schema of an event raised when a device is registered to an IoT hub:

[{
  "id": "56afc886-767b-d359-d59e-0da7877166b2",
  "topic": "/SUBSCRIPTIONS/<subscription ID>/RESOURCEGROUPS/<resource group name>/PROVIDERS/MICROSOFT.DEVICES/IOTHUBS/<hub name>",
  "subject": "devices/LogicAppTestDevice",
  "eventType": "Microsoft.Devices.DeviceCreated",
  "eventTime": "2018-01-02T19:17:44.4383997Z",
  "data": {
    "twin": {
      "deviceId": "LogicAppTestDevice",
      "etag": "AAAAAAAAAAE=",
      "deviceEtag": "null",
      "status": "enabled",
      "statusUpdateTime": "0001-01-01T00:00:00",
      "connectionState": "Disconnected",
      "lastActivityTime": "0001-01-01T00:00:00",
      "cloudToDeviceMessageCount": 0,
      "authenticationType": "sas",
      "x509Thumbprint": {
        "primaryThumbprint": null,
        "secondaryThumbprint": null
      },
      "version": 2,
      "properties": {
        "desired": {
          "$metadata": {
            "$lastUpdated": "2018-01-02T19:17:44.4383997Z"
          },
          "$version": 1
        },
        "reported": {
          "$metadata": {
            "$lastUpdated": "2018-01-02T19:17:44.4383997Z"
          },
          "$version": 1
        }
      }
    },
    "hubName": "egtesthub1",
    "deviceId": "LogicAppTestDevice"
  },
  "dataVersion": "1",
  "metadataVersion": "1"
}]

事件属性Event properties

所有事件均包含相同的顶级数据:All events contain the same top-level data:

属性Property 类型Type 说明Description
id 字符串string 事件的唯一标识符。Unique identifier for the event.
topic stringstring 事件源的完整资源路径。Full resource path to the event source. 此字段不可写入。This field is not writeable. 事件网格提供此值。Event Grid provides this value.
subject stringstring 事件主题的发布者定义路径。Publisher-defined path to the event subject.
eventType stringstring 此事件源的一个注册事件类型。One of the registered event types for this event source.
eventTime stringstring 基于提供程序 UTC 时间的事件生成时间。The time the event is generated based on the provider's UTC time.
data objectobject IoT 中心事件数据。IoT Hub event data.
dataVersion stringstring 数据对象的架构版本。The schema version of the data object. 发布者定义架构版本。The publisher defines the schema version.
metadataVersion stringstring 事件元数据的架构版本。The schema version of the event metadata. 事件网格定义顶级属性的架构。Event Grid defines the schema of the top-level properties. 事件网格提供此值。Event Grid provides this value.

对于所有 IoT 中心事件,数据对象包含以下属性:For all IoT Hub events, the data object contains the following properties:

属性Property 类型Type 说明Description
hubName stringstring 已创建或已删除设备的 IoT 中心的名称。Name of the IoT Hub where the device was created or deleted.
deviceId stringstring 设备的唯一标识符。The unique identifier of the device. 此区分大小写的字符串最多可长达 128 个字符,并支持 ASCII 7 位字母数字字符加上以下特殊字符:- : . + % _ # * ? ! ( ) , = @ ; $ 'This case-sensitive string can be up to 128 characters long, and supports ASCII 7-bit alphanumeric characters plus the following special characters: - : . + % _ # * ? ! ( ) , = @ ; $ '.

每个事件发布者的数据对象内容是不同的。The contents of the data object are different for each event publisher.

对于 设备已连接设备已断开连接 IoT 中心事件,数据对象包含以下属性:For Device Connected and Device Disconnected IoT Hub events, the data object contains the following properties:

属性Property 类型Type 说明Description
moduleId stringstring 模块的唯一标识符。The unique identifier of the module. 此字段是仅适用于模块设备的输出。This field is output only for module devices. 此区分大小写的字符串最多可长达 128 个字符,并支持 ASCII 7 位字母数字字符加上以下特殊字符:- : . + % _ # * ? ! ( ) , = @ ; $ 'This case-sensitive string can be up to 128 characters long, and supports ASCII 7-bit alphanumeric characters plus the following special characters: - : . + % _ # * ? ! ( ) , = @ ; $ '.
deviceConnectionStateEventInfo objectobject 设备连接状态事件信息Device connection state event information
sequenceNumber stringstring 一个数字,有助于指示设备已连接或设备已断开连接事件的顺序。A number which helps indicate order of device connected or device disconnected events. 最新事件的序列号将大于上一个事件。Latest event will have a sequence number that is higher than the previous event. 此数字可能会变化超过 1,但严格地说,是在增加。This number may change by more than 1, but is strictly increasing. 请参阅如何使用序列号See how to use sequence number.

对于 设备遥测 IoT 中心事件,数据对象包含 IoT 中心消息格式的设备到云消息,并具有以下属性:For Device Telemetry IoT Hub event, the data object contains the device-to-cloud message in IoT hub message format and has the following properties:

属性Property 类型Type 说明Description
body stringstring 来自设备的消息内容。The content of the message from the device.
properties stringstring 应用程序属性是用户定义的字符串,可以添加到消息。Application properties are user-defined strings that can be added to the message. 这些字段是可选的。These fields are optional.
system properties stringstring 系统属性有助于标识消息的内容和源。System properties help identify contents and source of the messages. 设备遥测消息必须采用有效的 JSON 格式,并且在消息系统属性中将 contentType 设置为 JSON,将 contentEncoding 设置为 UTF-8。Device telemetry message must be in a valid JSON format with the contentType set to JSON and contentEncoding set to UTF-8 in the message system properties. 如果未设置此项,则 IoT 中心将以 base 64 编码格式写入消息。If this is not set, then IoT Hub will write the messages in base 64 encoded format.

对于 设备已创建设备已删除 IoT 中心事件,数据对象包含以下属性:For Device Created and Device Deleted IoT Hub events, the data object contains the following properties:

属性Property 类型Type 说明Description
twin objectobject 有关设备孪生(即应用程序设备元数据的云表示形式)的信息。Information about the device twin, which is the cloud representation of application device metadata.
deviceID stringstring 设备孪生的唯一标识符。The unique identifier of the device twin.
etag stringstring 用于确保设备孪生更新一致性的验证程序。A validator for ensuring consistency of updates to a device twin. 每个 etag 保证对于每个设备孪生是唯一的。Each etag is guaranteed to be unique per device twin.
deviceEtag stringstring 用于确保设备注册表更新一致性的验证程序。A validator for ensuring consistency of updates to a device registry. 每个 deviceEtag 保证对于每个设备注册表是唯一的。Each deviceEtag is guaranteed to be unique per device registry.
status stringstring 设备孪生是已启用还是已禁用。Whether the device twin is enabled or disabled.
statusUpdateTime stringstring 上次设备孪生状态更新的 ISO8601 时间戳。The ISO8601 timestamp of the last device twin status update.
connectionState stringstring 设备是已连接还是已断开连接。Whether the device is connected or disconnected.
lastActivityTime stringstring 上次活动的 ISO8601 时间戳。The ISO8601 timestamp of the last activity.
cloudToDeviceMessageCount integerinteger 发送到此设备的云到设备消息数。Count of cloud to device messages sent to this device.
authenticationType stringstring 用于此设备的身份验证类型:SASSelfSignedCertificateAuthorityAuthentication type used for this device: either SAS, SelfSigned, or CertificateAuthority.
x509Thumbprint stringstring 指纹是 x509 证书的唯一值,通常用于在证书存储中查找特定证书。The thumbprint is a unique value for the x509 certificate, commonly used to find a particular certificate in a certificate store. 指纹是使用 SHA1 算法动态生成的,并非在证书中实际存在。The thumbprint is dynamically generated using the SHA1 algorithm, and does not physically exist in the certificate.
primaryThumbprint stringstring x509 证书的主要指纹。Primary thumbprint for the x509 certificate.
secondaryThumbprint stringstring x509 证书的次要指纹。Secondary thumbprint for the x509 certificate.
version integerinteger 一个整数,每次更新设备孪生时递增 1。An integer that is incremented by one each time the device twin is updated.
desired objectobject 只能由应用程序后端写入并且由设备读取的属性部分。A portion of the properties that can be written only by the application back-end, and read by the device.
reported objectobject 只能由设备写入并且由应用程序后端读取的属性部分。A portion of the properties that can be written only by the device, and read by the application back-end.
lastUpdated stringstring 上次设备孪生属性更新的 ISO8601 时间戳。The ISO8601 timestamp of the last device twin property update.

教程和操作指南Tutorials and how-tos

标题Title 说明Description
使用逻辑应用发送有关 Azure IoT 中心事件的电子邮件Send email notifications about Azure IoT Hub events using Logic Apps 每次将设备添加到 IoT 中心时,逻辑应用就会发送一封通知电子邮件。A logic app sends a notification email every time a device is added to your IoT Hub.
使用事件网格来触发操作,对 IoT 中心事件进行响应React to IoT Hub events by using Event Grid to trigger actions 概述 IoT 中心与事件网格的集成。Overview of integrating IoT Hub with Event Grid.
订阅设备已连接和设备已断开连接事件Order device connected and device disconnected events 显示如何订阅设备连接状态事件。Shows how to order device connection state events.

后续步骤Next steps