IoT 中心的 Azure 事件网格事件架构Azure Event Grid event schema for IoT Hub

本文提供 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.

有关示例脚本和教程的列表,请参阅 IoT 中心事件源For a list of sample scripts and tutorials, see IoT Hub event source.

可用事件类型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.

示例事件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" 
}]

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
idid stringstring 事件的唯一标识符。Unique identifier for the event.
主题topic stringstring 事件源的完整资源路径。Full resource path to the event source. 此字段不可写入。This field is not writeable. 事件网格提供此值。Event Grid provides this value.
subjectsubject stringstring 事件主题的发布者定义路径。Publisher-defined path to the event subject.
eventTypeeventType stringstring 此事件源的一个注册事件类型。One of the registered event types for this event source.
EventTimeeventTime stringstring 基于提供程序 UTC 时间的事件生成时间。The time the event is generated based on the provider's UTC time.
数据data objectobject IoT 中心事件数据。IoT Hub event data.
dataVersiondataVersion stringstring 数据对象的架构版本。The schema version of the data object. 发布者定义架构版本。The publisher defines the schema version.
metadataVersionmetadataVersion 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
hubNamehubName stringstring 已创建或已删除设备的 IoT 中心的名称。Name of the IoT Hub where the device was created or deleted.
deviceIddeviceId 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
moduleIdmoduleId 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: - : . + % _ # * ? ! ( ) , = @ ; $ '.
deviceConnectionStateEventInfodeviceConnectionStateEventInfo objectobject 设备连接状态事件信息Device connection state event information
sequenceNumbersequenceNumber 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.

每个事件发布者的数据对象内容是不同的。The contents of the data object are different for each event publisher. 对于设备已创建设备已删除 IoT 中心事件,数据对象包含以下属性:For Device Created and Device Deleted IoT Hub events, the data object contains the following properties:

属性Property 类型Type 说明Description
twintwin objectobject 有关设备孪生(即应用程序设备元数据的云表示形式)的信息。Information about the device twin, which is the cloud representation of application device metadata.
deviceIDdeviceID stringstring 设备孪生的唯一标识符。The unique identifier of the device twin.
etagetag stringstring 用于确保设备孪生更新一致性的验证程序。A validator for ensuring consistency of updates to a device twin. 每个 etag 保证对于每个设备孪生是唯一的。Each etag is guaranteed to be unique per device twin.
deviceEtagdeviceEtag 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.
statusUpdateTimestatusUpdateTime stringstring 上次设备孪生状态更新的 ISO8601 时间戳。The ISO8601 timestamp of the last device twin status update.
connectionStateconnectionState stringstring 设备是已连接还是已断开连接。Whether the device is connected or disconnected.
lastActivityTimelastActivityTime stringstring 上次活动的 ISO8601 时间戳。The ISO8601 timestamp of the last activity.
cloudToDeviceMessageCountcloudToDeviceMessageCount integerinteger 发送到此设备的云到设备消息数。Count of cloud to device messages sent to this device.
authenticationTypeauthenticationType stringstring 用于此设备的身份验证类型:SASSelfSignedCertificateAuthorityAuthentication type used for this device: either SAS, SelfSigned, or CertificateAuthority.
x509Thumbprintx509Thumbprint 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.
primaryThumbprintprimaryThumbprint stringstring x509 证书的主要指纹。Primary thumbprint for the x509 certificate.
secondaryThumbprintsecondaryThumbprint 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.
desireddesired objectobject 只能由应用程序后端写入并且由设备读取的属性部分。A portion of the properties that can be written only by the application back-end, and read by the device.
reportedreported objectobject 只能由设备写入并且由应用程序后端读取的属性部分。A portion of the properties that can be written only by the device, and read by the application back-end.
lastUpdatedlastUpdated stringstring 上次设备孪生属性更新的 ISO8601 时间戳。The ISO8601 timestamp of the last device twin property update.

后续步骤Next steps