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

Статья
06/01/2023

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

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

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

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

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

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

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

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

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

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

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

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

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

Элемент Property

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

Имя	Значение
`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 или нет. Это обусловлено тем, что уведомления о жизненном цикле содержат сведения о самом цифровом двойнике.

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

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

Элемент Property

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

Имя	Значение
`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"
        }
    }
}

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

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

Элемент Property

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

Имя	Значение
`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 для отправки сообщений телеметрии и их отправки в конечные точки исходящего трафика.

Элемент Property

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

Имя	Значение
`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
}

Дальнейшие действия

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

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

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

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

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

Элемент Property

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

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

Элемент Property

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

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

Элемент Property

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

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

Элемент Property

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

Дальнейшие действия

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