Compartilhar via

Notificações de eventos

  • Artigo

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):

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

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

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

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

Próximas etapas

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