Encaminhar eventos do Azure Digital Twins
Este artigo descreve o processo que o Azure Digital Twins utiliza para enviar dados de eventos, tanto para encaminhar eventos internamente no Azure Digital Twins, como para enviar dados de eventos externamente para serviços a jusante ou recursos de computação ligados fora do serviço.
Encaminhar notificações de eventos do Azure Digital Twins é um processo de dois passos: criar pontos finais e, em seguida, criar rotas de eventos para enviar dados para esses pontos finais. Este artigo aborda mais detalhadamente cada um destes conceitos. Também explica o que acontece quando um ponto final não entrega um evento a tempo (um processo conhecido como lettering não entregue).
Descrição geral do encaminhamento de eventos
Existem dois cenários principais para enviar dados do Azure Digital Twins e as rotas de eventos são utilizadas para realizar ambos:
- Enviar dados de eventos de um duplo duplo no grafo do Azure Digital Twins para outro. Por exemplo, quando uma propriedade num duplo digital é alterada, poderá querer notificar e atualizar outro duplo digital com base nos dados atualizados.
- Enviar dados fora do Azure Digital Twins para serviços de dados a jusante para mais armazenamento ou processamento. Por exemplo, se já estiver a utilizar Azure Maps, poderá querer contribuir com dados do Azure Digital Twins para melhorar a sua solução com modelação ou consultas integradas.
Para qualquer destino de evento, uma rota de evento funciona ao enviar dados de eventos do Azure Digital Twins para pontos finais personalizados nas suas subscrições. Atualmente, são suportados três serviços do Azure para pontos finais: Hubs de Eventos, Event Grid e Service Bus. Cada um destes serviços do Azure pode ser ligado a outros serviços e atua como intermediário, enviando dados para destinos finais, como Azure Maps, ou de volta para o Azure Digital Twins para atualizações de grafos dependentes.
O diagrama seguinte ilustra o fluxo de dados de eventos através de uma solução de IoT maior, que inclui o envio de dados do Azure Digital Twins através de pontos finais para outros Serviços do Azure, bem como de volta para o Azure Digital Twins:
Para a saída de dados fora do Azure Digital Twins, os destinos típicos a jusante para rotas de eventos são o Time Series Insights, Azure Maps, armazenamento e soluções de análise. O Azure Digital Twins implementa , pelo menos, uma vez a entrega de dados emitidos para serviços de saída.
Para encaminhar eventos de duplo digital internos na mesma solução do Azure Digital Twins, avance para a secção seguinte.
Encaminhar eventos de duplo digital internos
As rotas de eventos são o mecanismo utilizado para processar eventos no grafo duplo, enviando dados do duplo digital para o duplo digital. Este tipo de processamento de eventos é feito ao ligar rotas de eventos através do Event Grid a recursos de computação, como Funções do Azure. Em seguida, estas funções definem como os duplos devem receber e responder a eventos.
Quando um recurso de computação quer modificar o grafo duplo com base num evento que recebeu através da rota do evento, é útil que saiba antecipadamente que duplo deve modificar. A mensagem de evento também contém o ID do duplo de origem que enviou a mensagem, para que o recurso de computação possa utilizar consultas ou atravessar relações para encontrar um duplo de destino para a operação pretendida.
O recurso de computação também precisa de estabelecer permissões de segurança e acesso de forma independente.
Para percorrer o processo de configuração de uma função do Azure para processar eventos de duplo digital, veja Configurar o processamento de eventos duplos para duplos.
Criar pontos finais
Para definir uma rota de evento, primeiro os programadores têm de definir pontos finais. Um ponto final é um destino fora do Azure Digital Twins que suporta uma ligação de rota. Os destinos suportados incluem:
- Tópicos personalizados do Event Grid
- Hubs de Eventos
- Service Bus
Para criar um ponto final, pode utilizar as APIs REST do Azure Digital Twins, os comandos da CLI ou o portal do Azure.
Ao definir um ponto final, terá de fornecer:
- O nome do ponto final
- O tipo de ponto final (Event Grid, Hubs de Eventos ou Service Bus)
- A cadeia de ligação primária e a cadeia de ligação secundária para autenticar
- O caminho do tópico do ponto final, como
your-topic.westus2.eventgrid.azure.net
Opcionalmente, pode optar por criar o ponto final com autenticação baseada em identidade, para utilizar o ponto final com uma identidade gerida atribuída pelo sistema ou atribuída pelo utilizador. Esta opção só está disponível para os Hubs de Eventos e pontos finais do tipo Service Bus (não é suportada para o Event Grid).
As APIs de ponto final que estão disponíveis no plano de controlo são:
- Criar ponto final
- Obter lista de pontos finais
- Obter ponto final por nome
- Eliminar ponto final por nome
Para obter instruções detalhadas sobre como criar um ponto final, veja Criar pontos finais.
Criar rotas de eventos
Para criar uma rota de eventos, pode utilizar as APIs REST do Azure Digital Twins, os comandos da CLI ou o portal do Azure.
Eis um exemplo de criação de uma rota de eventos numa aplicação cliente, com a CreateOrReplaceEventRouteAsync chamada SDK .NET (C#):
string eventFilter = "$eventType = 'DigitalTwinTelemetryMessages' or $eventType = 'DigitalTwinLifecycleNotification'";
var er = new DigitalTwinsEventRoute("endpointName", eventFilter);
await client.CreateOrReplaceEventRouteAsync("routeId", er);
Primeiro, é criado um
DigitalTwinsEventRouteobjeto e o construtor assume o nome de um ponto final. EsteendpointNamecampo identifica um ponto final, como os Hubs de Eventos, o Event Grid ou o Service Bus. Estes pontos finais têm de ser criados na sua subscrição e anexados ao Azure Digital Twins através de APIs do plano de controlo antes de efetuar esta chamada de registo.O objeto de rota de evento também tem um campo Filtro , que pode ser utilizado para restringir os tipos de eventos que seguem esta rota. Um filtro de
trueativa a rota sem filtragem extra (um filtro defalsedesativa a rota).Em seguida, este objeto de rota de evento é transmitido para
CreateOrReplaceEventRouteAsync, juntamente com um nome para a rota.
Dica
Todas as funções do SDK são incluídas em versões síncronas e assíncronas.
Para obter instruções detalhadas sobre como criar rotas de eventos, veja Criar rotas e filtros.
Eventos de cartas não entregues
Quando um ponto final não consegue entregar um evento num determinado período de tempo ou depois de tentar entregar o evento várias vezes, pode enviar o evento não entregue para uma conta de armazenamento. Este processo é conhecido como mensagens não entregues. O Azure Digital Twins irá apresentar um evento sem mensagens quando uma das seguintes condições for cumprida:
- O evento não é entregue dentro do período de tempo de duração
- O número de tentativas de entrega do evento excedeu o limite
Se qualquer uma das condições for cumprida, o evento é ignorado ou não entregue. Por predefinição, cada ponto final não ativa as letras não entregues. Para a ativar, tem de especificar uma conta de armazenamento para conter eventos não entregues ao criar o ponto final. Em seguida, pode solicitar eventos desta conta de armazenamento para resolver as entregas.
Antes de definir a localização da letra não entregue, tem de ter uma conta de armazenamento com um contentor. Fornece o URL para este contentor ao criar o ponto final. A letra não entregue é fornecida como um URL de contentor com um token de SAS. Esse token só write precisa de permissão para o contentor de destino na conta de armazenamento. O URL totalmente formado estará no formato de: https://<storage-account-name>.blob.core.windows.net/<container-name>?<SAS-token>
Para saber mais sobre os tokens de SAS, veja: Conceder acesso limitado aos recursos do Armazenamento do Azure com assinaturas de acesso partilhado (SAS)
Para saber como configurar um ponto final com mensagens não entregues, consulte Opções de ponto final: Mensagens não entregues.
Tipos de mensagens de evento
Diferentes tipos de eventos no Hub IoT e no Azure Digital Twins produzem diferentes tipos de mensagens de notificação, conforme descrito abaixo.
| 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 duplo digital |
| 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 eliminação de duplo digital |
| Notificação de Alteração de Relação de Duplo Digital | Notificação de Alteração de Relação de Duplo Digital | qualquer alteração de relação de duplo digital |
| Mensagens de Telemetria de Duplo Digital | Mensagens de Telemetria | qualquer mensagem de telemetria |
Passos seguintes
Continue para as instruções passo a passo para configurar pontos finais e rotas de eventos:
Em alternativa, siga estas instruções para configurar uma Função do Azure para processamento de eventos duplos-duplos no Azure Digital Twins: