Уведомления о событиях
В этой статье рассматриваются уведомления о событиях, созданные 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>"
}
Примечание.
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>"
}
Уведомления об изменении связи цифрового двойника
Уведомления об изменении связи активируются при создании, обновлении или удалении любой связи цифрового двойника.
Свойства
Ниже приведены поля в тексте уведомления об изменении связи.
Имя. | Значение |
---|---|
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. Для связи через API DigitalTwins используется тот же формат, что и для запроса 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>"
}
Сообщения телеметрии цифрового двойника
Цифровые двойники могут использовать 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>"
}
Следующие шаги
Ознакомьтесь со сведениями о доставке событий в различные места назначения с помощью конечных точек и маршрутов: