Partilhar via

Notificações de eventos

  • Artigo

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

Eventos diferentes nos Gêmeos Digitais do Azure produzem notificações, que permitem que o back-end da solução esteja ciente quando diferentes ações estão acontecendo. Essas notificações são então roteadas para diferentes locais dentro e fora dos Gêmeos Digitais do Azure que podem usar essas informações para tomar medidas.

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

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

Tipo de notificação Nome da origem do encaminhamento Gerado de...
Notificação de Alteração de Duplo Digital Notificação de Alteração de Duplo Digital qualquer alteração de propriedade de gêmeos digitais
Notificação de Ciclo de Vida de Duplo Digital Notificação de Ciclo de Vida de Duplo Digital qualquer operação de criação ou exclusão de gêmeos digitais
Notificação de Alteração de Relação de Duplo Digital Notificação de Alteração de Relação de Duplo Digital qualquer mudança de relacionamento de gêmeos digitais
Mensagens de Telemetria de Duplo 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 para a Grade de Eventos estão em conformidade com um dos seguintes formatos (dependendo das configurações da Grade de Eventos):

As notificações enviadas para Hubs de Eventos e Service Bus estão em conformidade com a Vinculação de Protocolo AMQP para CloudEvents.

Notificações de alteração de gêmeos digitais

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

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

Propriedades

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

Nome Valor
id Identificador da notificação, como um UUID ou um contador mantido pelo serviço. source + id é único para cada evento distinto
source Nome do hub IoT ou instância do Azure Digital Twins, como myhub.azure-devices.net ou mydigitaltwins.westus2.azuredigitaltwins.net
data Um documento JSON Patch descrevendo a atualização feita para o gêmeo. Para obter detalhes, consulte Detalhes do corpo abaixo.
specversion 1.0
A mensagem está em conformidade 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 de quando a operação ocorreu no gêmeo digital
traceparent Um contexto de rastreamento do W3C para o evento

Detalhes do corpo

Dentro da mensagem, o data campo contém um documento JSON Patch contendo 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>"
}

Nota

Atualmente, o Azure Digital Twins não oferece suporte à filtragem de eventos com base em campos dentro de uma matriz. Isso inclui a filtragem de propriedades dentro de uma patch seção de uma notificação de alteração de gêmeo digital.

Notificações de ciclo de vida de gêmeos digitais

Quer os gêmeos digitais representem dispositivos do Hub IoT nos Gêmeos Digitais do Azure ou não, todos eles emitirão 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 acionadas quando:

  • É criado um gémeo digital
  • Um gêmeo digital é excluído

Propriedades

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

Nome Valor
id Identificador da notificação, como um UUID ou um contador mantido pelo serviço. source + id é único para cada evento distinto.
source Nome do hub IoT ou instância do Azure Digital Twins, como myhub.azure-devices.net ou mydigitaltwins.westus2.azuredigitaltwins.net
data Os dados do gêmeo que experimenta o evento do ciclo de vida. Para obter detalhes, consulte Detalhes do corpo abaixo.
specversion 1.0
A mensagem está em conformidade 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 de quando a operação ocorreu no gêmeo
traceparent Um contexto de rastreamento do 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 de relacionamento de gêmeos digitais

As notificações de alteração de relacionamento são acionadas 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 de relacionamento.

Nome Valor
id Identificador da notificação, como um UUID ou um contador mantido pelo serviço. source + id é único para cada evento distinto
source Nome da instância do Azure Digital Twins, como mydigitaltwins.westus2.azuredigitaltwins.net
data A carga útil da relação que foi alterada. Para obter detalhes, consulte Detalhes do corpo abaixo.
specversion 1.0
A mensagem está em conformidade 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 de quando a operação ocorreu na relação
traceparent Um contexto de rastreamento do W3C para o evento

Detalhes do corpo

Dentro da mensagem, o data campo contém a carga útil de uma relação, no formato JSON. Ele usa o mesmo formato de uma GET solicitação de relacionamento 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 de gêmeos digitais

Os gêmeos digitais podem usar a API SendTelemetry para emitir mensagens de telemetria e enviá-las para 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á em conformidade com esta versão da especificação CloudEvents.
type microsoft.iot.telemetry
data A mensagem de telemetria que está sendo enviada do gêmeo. A carga útil não precisa estar alinhada com nenhum esquema definido em sua instância do Azure Digital Twins.
dataschema O esquema de dados é o 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 do W3C para o evento.

Detalhes do corpo

O corpo contém a medição de telemetria juntamente 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óximos passos

Saiba mais sobre como entregar eventos para diferentes destinos, usando endpoints e rotas: