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


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

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

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

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

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

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

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

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

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

Уведомления, отправленные в Центры событий и служебная шина соответствуют привязке протокола 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>"
}

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

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