Уведомления о событиях

2025-04-01

В этой статье рассматриваются уведомления о событиях, созданные Azure Digital Twins, их структурой и подробными сведениями о различных типах, которые можно создать.

Различные события в Azure Digital Twins создают уведомления, которые позволяют серверной части решения узнавать о различных действиях. Затем эти уведомления направляются в разные места внутри и за пределами Azure Digital Twins, которые могут использовать эту информацию для принятия мер.

Могут создаваться уведомления нескольких типов. Уведомляющие сообщения отличаются в зависимости от типа создавшего их события. В этой статье приводятся подробные сведения о различных типах сообщений и о том, как они могут выглядеть.

На этой диаграмме представлены различные типы уведомлений.

Тип уведомления	Имя источника маршрутизации	Создано из
Уведомление об изменении цифрового двойника	Уведомление об изменении цифрового двойника	изменение любого свойства цифрового двойника
Уведомление о жизненном цикле цифрового двойника	Уведомление о жизненном цикле цифрового двойника	любая операция создания или удаления цифрового двойника
Уведомление об изменении связи цифрового двойника	Уведомление об изменении связи цифрового двойника	любое изменение отношений цифрового двойника
Сообщения телеметрии цифрового двойника	Сообщения телеметрии	любое сообщение телеметрии

Структура уведомления

Структура уведомления о событии из Azure Digital Twins зависит от назначения уведомления.

Уведомления, отправленные в сетку событий, соответствуют одному из следующих форматов (в зависимости от параметров сетки событий):

Схема событий службы "Сетка событий Azure"
Привязка протокола HTTP для CloudEvents.

Уведомления, отправленные в Центры событий и служебная шина соответствуют привязке протокола AMQP для CloudEvents.

Уведомления об изменениях цифровых двойников

Уведомления об изменениях цифровых двойников активируются при обновлении цифрового двойника, например:

при изменении значений свойств или метаданных;
при изменении метаданных цифрового двойника или компонента. Примером такого сценария является изменение модели цифрового двойника.

Свойства

Ниже приведены поля в тексте уведомления об изменении цифрового двойника.

Имя.	Значение
`id`	Идентификатор уведомления, например UUID или счетчик, поддерживаемый службой. `source` + `id` уникален для каждого отдельного события.
`source`	Имя центра Интернета вещей или экземпляра Azure Digital Twins, например myhub.azure-devices.net или mydigitaltwins.westus2.azuredigitaltwins.net
`data`	Документ исправлений JSON, описывающий обновление, внесенное в двойник. Дополнительные сведения см. в разделе Сведения о тексте ниже.
`specversion`	1.0 Сообщение соответствует этой версии спецификации CloudEvents.
`type`	`Microsoft.DigitalTwins.Twin.Update`
`datacontenttype`	`application/json`
`subject`	Идентификатор цифрового двойника
`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>"
}

{
    "specversion": "1.0",
    "id": "39d4abb9-e3ee-4ed5-ad17-2243a9784946",
    "type": "Microsoft.DigitalTwins.Twin.Update",
    "source": "my-example-digital-twin.api.sea.digitaltwins.azure.net",
    "data": {
      "modelId": "dtmi:examplecom:interfaceName;1",
      "patch": [
        {
          "value": "new name",
          "path": "/room",
          "op": "replace"
        }
      ]
    },
    "subject": "example-twin1",
    "time": "2021-12-09T20:28:52.9795363Z",
    "datacontenttype": "application/json",
    "traceparent": "00-2aa957558db348f387ef704b37631a1d-590d733a1b798149-01"
}

Пример, показывающий свойства в разделе свойств приложения AMQP:

    "cloudEvents:id": "39d4abb9-e3ee-4ed5-ad17-2243a9784946",
    "cloudEvents:source": "my-example-digital-twin.api.sea.digitaltwins.azure.net",
    "cloudEvents:specversion": "1.0",
    "cloudEvents:type": "Microsoft.DigitalTwins.Twin.Update",
    "cloudEvents:time": "2021-12-09T20:28:52.9795363Z",
    "cloudEvents:subject": "example-twin1",
    "cloudEvents:traceparent": "00-2aa957558db348f387ef704b37631a1d-e66f14eb07b50d40-01"

Пример текста сообщения, заполненного в разделе данных AMQP:

{
    "modelId": "dtmi:examplecom:interfaceName;1",
    "patch": [
      {
        "value": "new name",
        "path": "/room",
        "op": "replace"
      }
    ]
}

Примечание.

Azure Digital Twins в настоящее время не поддерживает фильтрацию событий на основе полей в массиве. Это подразумевает фильтрацию по свойствам, находящихся в patch разделе уведомления об изменении цифрового двойника.

Уведомления о жизненном цикле цифрового двойника

Все цифровые двойники выдают уведомления независимо от того, представляют ли они устройства Центра Интернета вещей в Azure Digital Twins или нет. Это обусловлено тем, что уведомления о жизненном цикле содержат сведения о самом цифровом двойнике.

Уведомления о жизненном цикле активируются в следующих случаях:

создание цифрового двойника;
Цифровой двойник удалён.

Свойства

Ниже приведены поля в тексте уведомления о жизненном цикле.

Имя.	Значение
`id`	Идентификатор уведомления, например UUID или счетчик, поддерживаемый службой. `source` + `id` уникален для каждого отдельного события.
`source`	Имя центра Интернета вещей или экземпляра Azure Digital Twins, например 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`	Идентификатор цифрового двойника
`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>"
}

{
    "specversion": "1.0",
    "id": "6ccdb1cd-0dc3-450f-8730-ceccda8439be",
    "type": "Microsoft.DigitalTwins.Twin.Create",
    "source": "my-example-digital-twin.api.sea.digitaltwins.azure.net",
    "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"
        }
      }
    },
    "subject": "example-twin1",
    "time": "2021-12-09T20:28:52.6745538Z",
    "datacontenttype": "application/json",
    "traceparent": "00-2aa957558db348f387ef704b37631a1d-96f834571bf4fe45-01"
}

Пример, показывающий свойства в разделе свойств приложения AMQP:

    "cloudEvents:id": "6ccdb1cd-0dc3-450f-8730-ceccda8439be",
    "cloudEvents:source": "my-example-digital-twin.api.sea.digitaltwins.azure.net",
    "cloudEvents:specversion": "1.0",
    "cloudEvents:type": "Microsoft.DigitalTwins.Twin.Create",
    "cloudEvents:time": "2021-12-09T20:28:52.6745538Z",
    "cloudEvents:subject": "example-twin1",
    "cloudEvents:traceparent": "00-2aa957558db348f387ef704b37631a1d-a158c39c72ec1049-01"

Пример текста сообщения, заполненного в разделе данных AMQP:

{
    "$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"
        }
    }
}

Уведомления об изменении связи цифрового двойника

Уведомления об изменении связи активируются при создании, обновлении или удалении любой связи цифрового двойника.

Свойства

Ниже приведены поля в тексте уведомления об изменении связи.

Имя.	Значение
`id`	Идентификатор уведомления, например UUID или счетчик, поддерживаемый службой. `source` + `id` уникален для каждого отдельного события.
`source`	Имя экземпляра Azure Digital Twins, например 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`	Идентификатор связи, например `<twin-ID>/relationships/<relationshipID>`
`time`	Метка времени, когда операция была выполнена в отношении связи
`traceparent`	Контекст трассировки W3C для события

Детали корпуса

Внутри сообщения поле data содержит нагрузку связи в формате JSON. Для связи через 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>"
}

{
    "specversion": "1.0",
    "id": "4d850574-0a28-4667-a59e-3b382ff0e74e",
    "type": "Microsoft.DigitalTwins.Relationship.Update",
    "source": "my-example-digital-twin.api.sea.digitaltwins.azure.net",
    "data": {
    "modelId": "dtmi:examplecom:interfaceName;1",
    "patch": [
        {
        "value": "new value",
        "path": "/prop1",
        "op": "replace"
        }
    ]
    },
    "subject": "example-twin1/relationships/RuntimeEventsScenario_edge",
    "time": "2021-12-09T20:28:53.2016395Z",
    "datacontenttype": "application/json",
    "traceparent": "00-2aa957558db348f387ef704b37631a1d-723b3f49efd2e445-01"
}

Пример, показывающий свойства в разделе свойств приложения AMQP:

    "cloudEvents:id": "4d850574-0a28-4667-a59e-3b382ff0e74e",
    "cloudEvents:source": "my-example-digital-twin.api.sea.digitaltwins.azure.net",
    "cloudEvents:specversion": "1.0",
    "cloudEvents:type": "Microsoft.DigitalTwins.Relationship.Update",
    "cloudEvents:time": "2021-12-09T20:28:53.2016395Z",
    "cloudEvents:subject": "example-twin1/relationships/RuntimeEventsScenario_edge",
    "cloudEvents:traceparent": "00-2aa957558db348f387ef704b37631a1d-6f3805aab2b73e49-01"

Пример текста сообщения, заполненного в разделе данных AMQP:

{
    "modelId": "dtmi:examplecom:interfaceName;1",
    "patch": [
      {
        "value": "new value",
        "path": "/prop1",
        "op": "replace"
      }
    ]
}

Сообщения телеметрии цифрового двойника

Цифровые двойники могут использовать API SendTelemetry для отправки сообщений телеметрии и их передачи во внешние конечные точки.

Свойства

Ниже приведены поля из текста сообщения телеметрии.

Имя.	Значение
`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 Digital Twins.
`dataschema`	Схема данных — это идентификатор модели двойника или компонента, генерирующего данные телеметрии. Например, `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>"
}

{
    "specversion": "1.0",
    "id": "622e6818-f042-4be8-96df-1a77ee9caf9b",
    "type": "microsoft.iot.telemetry",
    "source": "my-example-digital-twin.api.sea.digitaltwins.azure.net/digitaltwins/RuntimeEventsScenario_componentTwin_6f6635d8-f1b8-43ec-80fb-bb9453fc611c",
    "data": {
        "prop": "hello from telemetry"
    },
    "dataschema": "dtmi:examplecom:interfaceName;1",
    "subject": "component1",
    "datacontenttype": "application/json-patch+json; charset=utf-8",
    "traceparent": "00-2aa957558db348f387ef704b37631a1d-f58ef0c31162c548-01"
}

Пример, показывающий свойства в разделе свойств приложения AMQP:

    "cloudEvents:id": "6f6635d8-f1b8-43ec-80fb-bb9453fc611c",
    "cloudEvents:source": "my-example-digital-twin.api.sea.digitaltwins.azure.net/digitaltwins/example-twin1",
    "cloudEvents:specversion": "1.0",
    "cloudEvents:type": "microsoft.iot.telemetry",
    "cloudEvents:dataschema": "dtmi:examplecom:interfaceName;1",
    "cloudEvents:traceparent": "00-2aa957558db348f387ef704b37631a1d-ce042d67cbbfd948-01"

Пример текста сообщения, заполненного в разделе данных AMQP:

{
    "Temperature": 50
}

Следующие шаги

Ознакомьтесь со сведениями о доставке событий в различные места назначения с помощью конечных точек и маршрутов:

Конечные точки и маршруты событий

Поделиться через

Уведомления о событиях

Структура уведомления

Уведомления об изменениях цифровых двойников

Свойства

Детали корпуса

Уведомления о жизненном цикле цифрового двойника

Свойства

Детали корпуса

Уведомления об изменении связи цифрового двойника

Свойства

Детали корпуса

Сообщения телеметрии цифрового двойника

Свойства

Детали корпуса

Следующие шаги

Обратная связь

Дополнительные ресурсы