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

Статья
06/01/2023

В этой статье рассматриваются уведомления о событиях, созданные 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. Для связи через 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>"
}

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

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

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

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

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

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

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

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

Свойства

Сведения о тексте

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

Свойства

Сведения о тексте

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

Свойства

Сведения о тексте

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

Свойства

Сведения о тексте

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

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

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