Notificações de eventos

Artigo
06/01/2023

Este artigo aborda as notificações de eventos geradas por Gêmeos Digitais do Azure, a estrutura delas e os detalhes sobre os vários tipos que podem ser gerados.

Os diversos eventos nos Gêmeos Digitais do Azure produzem notificações, que permitem que o back-end da solução seja percebido com a ocorrência de ações distintas. Essas notificações são roteadas para diferentes locais dentro e fora dos Gêmeos Digitais do Azure, que podem usar essas informações para tomar medidas.

Há vários tipos de notificações que podem ser geradas e as mensagens de notificação podem parecer diferentes, dependendo do tipo de evento gerado. Este artigo fornece detalhes sobre os diversos tipos de mensagens e o que elas podem ter.

Este gráfico mostra os diferentes tipos de notificação:

Tipo de notificação	Nome da fonte de roteamento	Gerada por...
Notificação de alteração do gêmeo digital	Notificação de alteração do gêmeo digital	qualquer alteração de propriedade no gêmeo digital
Notificação de ciclo de vida do gêmeo digital	Notificação de ciclo de vida do gêmeo digital	qualquer operação de criação ou exclusão do gêmeo digital
Notificação de alteração de relação do gêmeo digital	Notificação de alteração de relação do gêmeo digital	qualquer alteração de relação do gêmeo digital
Mensagens de telemetria do gêmeo digital	Mensagens de telemetria	qualquer mensagem de telemetria

Estrutura de notificação

A estrutura de uma notificação de evento dos Gêmeos Digitais do Azure depende do destino da notificação.

As notificações enviadas à Grade de Eventos estão em conformidade com um dos seguintes formatos (dependendo das configurações da Grade de Eventos):

Esquema de eventos da Grade de Eventos do Azure
Associação de protocolo HTTP para CloudEvents.

As notificações enviadas aos Hubs de Eventos e ao Barramento de Serviço estão em conformidade com a Associação de Protocolo AMQP para CloudEvents.

Notificações de alteração do gêmeo digital

As notificações de alteração do gêmeo digital são disparadas quando um gêmeo digital está sendo atualizado, como:

Quando os valores de propriedade ou de metadados são alterados.
Quando os metadados de componente ou o gêmeo digital são alterados. Um exemplo desse cenário é a alteração do modelo de um gêmeo digital.

Propriedades

Aqui estão os campos no corpo de uma notificação de alteração do gêmeo digital.

Nome	Valor
`id`	Identificador da notificação, como um UUID ou um contador mantido pelo serviço. `source` + `id` é exclusivo para cada evento distinto
`source`	Nome do hub IoT ou da instância dos Gêmeos Digitais do Azure, como myhub.azure-devices.net ou mydigitaltwins.westus2.azuredigitaltwins.net
`data`	Um documento de Patch JSON que descreve a atualização feita no gêmeo. Para obter detalhes, consulte os detalhes do corpo abaixo.
`specversion`	1.0 A mensagem está de acordo com esta versão da especificação CloudEvents.
`type`	`Microsoft.DigitalTwins.Twin.Update`
`datacontenttype`	`application/json`
`subject`	ID do gêmeo digital
`time`	Carimbo de data/hora do momento de ocorrência da operação no gêmeo digital
`traceparent`	Um contexto de rastreamento W3C para o evento

Detalhes do corpo

Dentro da mensagem, o campo data contém um documento de Patch JSON que contém a atualização para o gêmeo digital.

Abaixo estão exemplos desse tipo de mensagem para cada esquema de notificação possível.

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

Um exemplo mostrando as propriedades na seção application-properties do 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"

Um corpo de mensagem de exemplo, preenchido na seção de dados do AMQP:

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

Observação

Atualmente, os Gêmeos Digitais do Azure não dão suporte à filtragem de eventos com base nos campos de uma matriz. Isso inclui filtrar propriedades de uma seção patch de uma notificação de alteração de gêmeo digital.

Notificações do ciclo de vida do gêmeo digital

Quer os gêmeos digitais representem ou não os dispositivos IoT Hub nos Gêmeos Digitais do Azure, todos eles irão emitir notificações. Eles fazem isso por causa das notificações do ciclo de vida, que são sobre o próprio gêmeo digital.

As notificações do ciclo de vida são disparadas quando:

Um gêmeo digital é criado
Um gêmeo digital é excluído

Propriedades

Aqui estão os campos no corpo de uma notificação do ciclo de vida.

Nome	Valor
`id`	Identificador da notificação, como um UUID ou um contador mantido pelo serviço. `source` + `id` é exclusivo para cada evento distinto.
`source`	Nome do hub IoT ou da instância dos Gêmeos Digitais do Azure, como myhub.azure-devices.net ou mydigitaltwins.westus2.azuredigitaltwins.net
`data`	Os dados do gêmeo experimentando o evento de ciclo de vida. Para obter detalhes, consulte os detalhes do corpo abaixo.
`specversion`	1.0 A mensagem está de acordo com esta versão da especificação CloudEvents.
`type`	`Microsoft.DigitalTwins.Twin.Create` `Microsoft.DigitalTwins.Twin.Delete`
`datacontenttype`	`application/json`
`subject`	ID do gêmeo digital
`time`	Carimbo de data/hora do momento de ocorrência da operação no gêmeo
`traceparent`	Um contexto de rastreamento W3C para o evento

Detalhes do corpo

Abaixo estão exemplos desse tipo de mensagem para cada esquema de notificação possível.

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

Um exemplo mostrando as propriedades na seção application-properties do 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"

Um corpo de mensagem de exemplo, preenchido na seção de dados do 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"
        }
    }
}

Notificações de alteração da relação do gêmeo digital

As notificações de alteração da relação são disparadas quando qualquer relação de um gêmeo digital é criada, atualizada ou excluída.

Propriedades

Aqui estão os campos no corpo de uma notificação de alteração do relacionamento.

Nome	Valor
`id`	Identificador da notificação, como um UUID ou um contador mantido pelo serviço. `source` + `id` é exclusivo para cada evento distinto
`source`	Nome da instância dos Gêmeos Digitais do Azure, como mydigitaltwins.westus2.azuredigitaltwins.net
`data`	O conteúdo do relacionamento que foi alterado. Para obter detalhes, consulte os detalhes do corpo abaixo.
`specversion`	1.0 A mensagem está de acordo com esta versão da especificação CloudEvents.
`type`	`Microsoft.DigitalTwins.Relationship.Create` `Microsoft.DigitalTwins.Relationship.Update` `Microsoft.DigitalTwins.Relationship.Delete`
`datacontenttype`	`application/json`
`subject`	ID da relação, como `<twin-ID>/relationships/<relationshipID>`
`time`	Carimbo de data/hora do momento de ocorrência da operação na relação
`traceparent`	Um contexto de rastreamento W3C para o evento

Detalhes do corpo

Dentro da mensagem, o campo data contém o conteúdo de um relacionamento, no formato JSON. Ele usa o mesmo formato que uma solicitação GET para uma relação por meio da API DigitalTwins.

Abaixo estão exemplos desse tipo de mensagem para cada esquema de notificação possível.

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

Um exemplo mostrando as propriedades na seção application-properties do 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"

Um corpo de mensagem de exemplo, preenchido na seção de dados do AMQP:

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

Mensagens de telemetria do gêmeo digital

Os gêmeos digitais podem usar a API SendTelemetry para emitir mensagens de telemetria e enviá-las para os pontos de extremidade de saída.

Propriedades

Aqui estão os campos no corpo de uma mensagem de telemetria.

Nome	Valor
`id`	Identificador da notificação, que é fornecido pelo cliente ao chamar a API de telemetria.
`source`	Nome totalmente qualificado do gêmeo do qual o evento de telemetria foi enviado. Usa o seguinte formato: `<your-Digital-Twin-instance>.api.<your-region>.digitaltwins.azure.net/<twin-ID>`.
`specversion`	1.0 A mensagem está de acordo com esta versão da especificação CloudEvents.
`type`	`microsoft.iot.telemetry`
`data`	A mensagem de telemetria que está sendo enviada pelo gêmeo. O conteúdo não precisa se alinhar aos esquemas definidos na sua instância dos Gêmeos Digitais do Azure.
`dataschema`	O esquema de dados é a ID do modelo do gêmeo ou do componente que emite a telemetria. Por exemplo, `dtmi:example:com:floor4;2`.
`datacontenttype`	`application/json`
`traceparent`	Um contexto de rastreamento W3C para o evento.

Detalhes do corpo

O corpo contém a medida de telemetria junto com algumas informações contextuais sobre o gêmeo. Abaixo estão exemplos desse tipo de mensagem para cada esquema de notificação possível.

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

Um exemplo mostrando as propriedades na seção application-properties do 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"

Um corpo de mensagem de exemplo, preenchido na seção de dados do AMQP:

{
    "Temperature": 50
}

Próximas etapas

Saiba mais sobre como fornecer eventos para destinos diferentes, usando pontos de extremidade e rotas:

Pontos de extremidade e rotas de eventos

Compartilhar via

Notificações de eventos

Estrutura de notificação

Notificações de alteração do gêmeo digital

Propriedades

Detalhes do corpo

Notificações do ciclo de vida do gêmeo digital

Propriedades

Detalhes do corpo

Notificações de alteração da relação do gêmeo digital

Propriedades

Detalhes do corpo

Mensagens de telemetria do gêmeo digital

Propriedades

Detalhes do corpo

Próximas etapas

Comentários

Recursos adicionais