通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

事件通知

  • 项目

本文介绍 Azure 数字孪生生成的事件通知、其结构，以及有关可生成的各种类型的详细信息。

Azure 数字孪生中不同的事件会生成通知，解决方案后端可以通过这些通知了解何时发生了不同的操作。 然后，这些通知将路由到 Azure 数字孪生内部和外部的、可以使用此信息来采取措施的不同位置。

可以生成多种类型的通知，通知消息可能会根据生成通知的事件类型而显示不同的内容。 本文提供有关不同消息类型的详细信息及其可能显示的内容。

以下图表显示了不同的通知类型：

通知类型 路由源名称 生成自...
数字孪生体更改通知 数字孪生体更改通知 任何数字孪生体属性更改
数字孪生体生命周期通知 数字孪生体生命周期通知 任何数字孪生体的创建或删除操作
数字孪生体关系更改通知 数字孪生体关系更改通知 任何数字孪生体关系更改
数字孪生体遥测消息 遥测消息 任何遥测消息

通知结构

Azure 数字孪生的事件通知的结构取决于通知的目标。

发送到事件网格的通知遵循以下格式之一（取决于事件网格设置）：

发送到事件中心和服务总线的通知遵循 CloudEvents 的 AMQP 协议绑定。

数字孪生更改通知

更新数字孪生时会触发数字孪生更改通知，例如：

  • 属性值或元数据发生更改时。
  • 数字孪生或组件元数据发生更改时。 这种情况的一个例子是更改数字孪生的模型。

属性

下面是数字孪生更改通知正文中的字段。

名称 值
id 通知的标识符，例如一个 UUID，或服务维护的计数器。 source + id 对于每个相异事件都是唯一的
source IoT 中心或 Azure 数字孪生实例的名称，例如 myhub.azure-devices.net 或 mydigitaltwins.westus2.azuredigitaltwins.net
data 描述对孪生体进行的更新的 JSON 修补文档。 有关详细信息，请参阅下面的正文详细信息。
specversion 1.0
消息遵守此版本的 CloudEvents 规范。
type Microsoft.DigitalTwins.Twin.Update
datacontenttype application/json
subject 数字孪生的 ID
time 在数字孪生上发生该操作时的时间戳
traceparent 事件的 W3C 跟踪上下文

正文详细信息

在消息中，data 字段包含 JSON 修补文档，该文档包含对数字孪生体的更新。

下面是每种可能的通知架构的此消息类型的示例。

{
    "id": "39d4abb9-e3ee-4ed5-ad17-2243a9784946",
    "subject": "example-twin1",
    "data": {
      "data": {
        "modelId": "dtmi:examplecom:interfaceName;1",
        "patch": [
          {
            "value": "new name",
            "path": "/room",
            "op": "replace"
          }
        ]
      },
      "contenttype": "application/json",
      "traceparent": "00-2aa957558db348f387ef704b37631a1d-c28d665340fe5045-01"
    },
    "eventType": "Microsoft.DigitalTwins.Twin.Update",
    "dataVersion": "1.0",
    "metadataVersion": "1",
    "eventTime": "2021-12-09T20:28:52.9795363Z",
    "topic": "/subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.EventGrid/topics/<topic-name>"
}

注意

Azure 数字孪生目前不支持基于数组中的字段筛选事件。 这包括对数字孪生更改通知的 patch 部分中的属性进行筛选。

数字孪生体生命周期通知

无论数字孪生是否代表 Azure 数字孪生中的 IoT 中心设备，数字孪生都会发出通知。 数字孪生之所以执行此操作是因为生命周期通知，生命周期通知与数字孪生体本身有关。

出现以下情况时会触发生命周期通知：

  • 创建了数字孪生
  • 删除了数字孪生

属性

下面是生命周期通知正文中的字段。

名称 值
id 通知的标识符，例如一个 UUID，或服务维护的计数器。 source + id 对于每个相异事件都是唯一的。
source IoT 中心或 Azure 数字孪生实例的名称，例如 myhub.azure-devices.net 或 mydigitaltwins.westus2.azuredigitaltwins.net
data 遇到生命周期事件的孪生体数据。 有关详细信息，请参阅下面的正文详细信息。
specversion 1.0
消息遵守此版本的 CloudEvents 规范。
type Microsoft.DigitalTwins.Twin.Create
Microsoft.DigitalTwins.Twin.Delete
datacontenttype application/json
subject 数字孪生的 ID
time 在孪生上发生该操作时的时间戳
traceparent 事件的 W3C 跟踪上下文

正文详细信息

下面是每种可能的通知架构的此消息类型的示例。

{
    "id": "6ccdb1cd-0dc3-450f-8730-ceccda8439be",
    "subject": "example-twin1",
    "data": {
      "data": {
        "$dtId": "example-twin1",
        "$etag": "W/\"ecf81d6c-8c1a-4a95-afd8-13bd4cea436f\"",
        "room": "room name",
        "$metadata": {
          "$model": "dtmi:examplecom:interfaceName;1",
          "room": {
            "lastUpdateTime": "2021-12-09T20:28:52.6651216Z"
          }
        }
      },
      "contenttype": "application/json",
      "traceparent": "00-2aa957558db348f387ef704b37631a1d-51f716e7397ec64b-01"
    },
    "eventType": "Microsoft.DigitalTwins.Twin.Create",
    "dataVersion": "1.0",
    "metadataVersion": "1",
    "eventTime": "2021-12-09T20:28:52.6745538Z",
    "topic": "/subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.EventGrid/topics/<topic-name>"
}

数字孪生关系更改通知

创建、更新或删除数字孪生的任何关系时，都会触发关系更改通知。

属性

下面是关系更改通知正文中的字段。

名称 值
id 通知的标识符，例如一个 UUID，或服务维护的计数器。 source + id 对于每个相异事件都是唯一的
source Azure 数字孪生实例的名称，例如 mydigitaltwins.westus2.azuredigitaltwins.net
data 已更改的关系的有效负载。 有关详细信息，请参阅下面的正文详细信息。
specversion 1.0
消息遵守此版本的 CloudEvents 规范。
type Microsoft.DigitalTwins.Relationship.Create
Microsoft.DigitalTwins.Relationship.Update
Microsoft.DigitalTwins.Relationship.Delete
datacontenttype application/json
subject 关系的 ID，例如 <twin-ID>/relationships/<relationshipID>
time 在关系上发生该操作时的时间戳
traceparent 事件的 W3C 跟踪上下文

正文详细信息

在消息中，data 字段包含关系的有效负载（以 JSON 格式表示）。 其所用格式与通过 DigitalTwins API 对关系发出的 GET 请求的格式相同。

下面是每种可能的通知架构的此消息类型的示例。

{
    "id": "4d850574-0a28-4667-a59e-3b382ff0e74e",
    "subject": "example-twin1/relationships/RuntimeEventsScenario_edge",
    "data": {
    "data": {
        "modelId": "dtmi:examplecom:interfaceName;1",
        "patch": [
        {
            "value": "new value",
            "path": "/prop1",
            "op": "replace"
        }
        ]
    },
    "contenttype": "application/json",
    "traceparent": "00-2aa957558db348f387ef704b37631a1d-c1fcf951f540ec44-01"
    },
    "eventType": "Microsoft.DigitalTwins.Relationship.Update",
    "dataVersion": "1.0",
    "metadataVersion": "1",
    "eventTime": "2021-12-09T20:28:53.2016395Z",
    "topic": "/subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.EventGrid/topics/<topic-name>"
}

数字孪生体遥测消息

数字孪生可以使用 SendTelemetry API 发出遥测消息并将它们发送到出口终结点。

属性

下面是遥测消息正文中的字段。

名称 值
id 通知的标识符，客户在调用遥测 API 时提供该标识符。
source 发送遥测事件的孪生体的完全限定名称。 使用以下格式：<your-Digital-Twin-instance>.api.<your-region>.digitaltwins.azure.net/<twin-ID>。
specversion 1.0
消息遵守此版本的 CloudEvents 规范。
type microsoft.iot.telemetry
data 从孪生体发送的遥测消息。 有效负载不需要与 Azure 数字孪生实例中定义的任何架构保持一致。
dataschema 数据架构是孪生体或发出遥测的组件的模型 ID。 例如 dtmi:example:com:floor4;2。
datacontenttype application/json
traceparent 事件的 W3C 跟踪上下文。

正文详细信息

正文包含遥测度量以及有关孪生体的某些上下文信息。 下面是每种可能的通知架构的此消息类型的示例。

{
    "id": "6f6635d8-f1b8-43ec-80fb-bb9453fc611c",
    "subject": "example-twin1",
    "data": {
        "data": {
        "prop": "hello from telemetry"
        },
        "dataschema": "dtmi:examplecom:interfaceName;1",
        "contenttype": "application/json-patch+json; charset=utf-8",
        "traceparent": "00-2aa957558db348f387ef704b37631a1d-e894098b46243743-01"
    },
    "eventType": "microsoft.iot.telemetry",
    "dataVersion": "1.0",
    "metadataVersion": "1",
    "eventTime": "0001-01-01T00:00:00Z",
    "topic": "/subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.EventGrid/topics/<topic-name>"
}

后续步骤

了解如何使用终结点和路由将事件传递给不同的目标：