Rotear eventos de Gêmeos Digitais do Azure
Este artigo descreve o processo que os Gêmeos Digitais do Azure usam para enviar dados de evento, tanto para roteamento de eventos internamente dentro dos Gêmeos Digitais do Azure, quanto para enviar dados de eventos externamente para serviços downstream ou recursos de computação conectados fora do serviço.
O roteamento de notificações de eventos dos Gêmeos Digitais do Azure é um processo de duas etapas: criar pontos de extremidade e, em seguida, criar rotas de evento para enviar dados para esses pontos de extremidade. Este artigo entra em mais detalhes sobre cada um desses conceitos. Ele também explica o que acontece quando um ponto de extremidade falha em entregar um evento a tempo (um processo conhecido como mensagens mortas).
Visão geral do roteamento de eventos
Há dois cenários principais para enviar dados dos Gêmeos Digitais do Azure e as rotas de evento são usadas para realizar ambos:
- Envio de dados de evento de um gêmeo no grafo dos Gêmeos Digitais do Azure para outro. Por exemplo, quando uma propriedade em um gêmeo digital é alterada, convém notificar e atualizar outro gêmeo digital com base nos dados atualizados.
- Enviar dados para fora dos Gêmeos Digitais do Azure para serviços de dados downstream para mais armazenamento ou processamento. Por exemplo, se você já estiver usando Azure Mapas, convém contribuir com os dados dos Gêmeos Digitais do Azure para aprimorar sua solução com modelagem ou consultas integradas.
Para qualquer destino de evento, uma rota de evento funciona enviando dados de evento dos Gêmeos Digitais do Azure para pontos de extremidade personalizados em suas assinaturas. No momento, há suporte a três serviços do Azure para pontos de extremidade: Hubs de eventos, Grade de Eventos e Barramento de Serviço. Cada um desses serviços do Azure pode ser conectado a outros serviços e atua como o intermediário, enviando dados para os destinos finais, como Azure Mapas, ou de volta para os Gêmeos Digitais do Azure para atualizações de grafo independentes.
O diagrama a seguir ilustra o fluxo de dados de evento por meio de uma solução de IoT maior, que inclui o envio de dados dos Gêmeos Digitais do Azure por meio de pontos de extremidade para outros Serviços do Azure, bem como de volta aos Gêmeos Digitais do Azure:
Para saída de dados fora dos Gêmeos Digitais do Azure, os destinos típicos downstream para rotas de evento são Azure Mapas, armazenamento e soluções de análise. Os Gêmeos Digitais do Azure implementam pelo menos uma vez a entrega de dados emitidos para serviços de saída.
Para roteamento de eventos de gêmeos digitais internos na mesma solução dos Gêmeos Digitais do Azure, continue para a próxima seção.
Rotear eventos internos do gêmeo digital
As rotas de evento são o mecanismo usado para lidar com eventos dentro do grafo gêmeo, enviando dados de gêmeo digital para gêmeo digital. Este tipo de tratamento de evento é feito conectando rotas de eventos pela Grade de Eventos a recursos de computação, como o Azure Functions. Essas funções definem como os gêmeos devem receber e responder aos eventos.
Quando um recurso de computação deseja modificar o grafo gêmeo com base em um evento recebido por meio da rota de evento, é útil saber com antecedência qual gêmeo ele deve modificar. A mensagem de evento também contém a ID do gêmeo de origem que enviou a mensagem, para que o recurso de computação possa usar consultas ou percorrer relações para localizar um gêmeo de destino para a operação desejada.
O recurso de computação também precisa estabelecer permissões de segurança e de acesso de maneira independente.
Para seguir o processo de configuração de uma função do Azure a fim de processar eventos de gêmeos digitais, veja Configurar o tratamento de eventos de gêmeos para gêmeos.
Criando pontos de extremidade
Para definir uma rota de evento, primeiro os desenvolvedores precisam definir pontos de extremidade. Um ponto de extremidade é um destino fora dos Gêmeos Digitais do Azure com suporte para uma conexão de rota. Os destinos com suporte incluem:
- Tópicos personalizados da Grade de Eventos
- Hubs de Eventos
- Barramento de Serviço
Para criar um ponto de extremidade, você pode usar as APIs REST dos Gêmeos Digitais do Azure, comandos da CLI ou o portal do Azure.
Ao definir um ponto de extremidade, você precisará fornecer:
- O nome do ponto de extremidade
- O tipo de ponto de extremidade (Grade de Eventos, Hubs de Eventos ou Barramento de Serviço)
- A cadeia de conexão primária e a cadeia de conexão secundária para autenticar
- O caminho do tópico do ponto de extremidade, como
your-topic.westus2.eventgrid.azure.net
Opcionalmente, você pode optar por criar seu ponto de extremidade com autenticação baseada em identidade, para usá-lo com uma identidade gerenciada atribuída pelo sistema ou atribuída pelo usuário. Essa opção está disponível apenas para os pontos de extremidade do Hub de Eventos e do tipo de Barramento de Serviço (não tem suporte pela Grade de Eventos).
As APIs de ponto de extremidade que estão disponíveis no plano de controle são:
- Criar ponto de extremidade
- Obter a lista de pontos de extremidade
- Obter ponto de extremidade por nome
- Excluir o ponto de extremidade por nome
Para obter instruções detalhadas sobre como criar um ponto de extremidade, consulte Criar pontos de extremidade.
Criação de rotas de evento
Para criar uma rota de evento, você pode usar as APIs REST dos Gêmeos Digitais do Azure, comandos da CLI ou o portal do Azure.
Veja um exemplo de criação de uma rota de evento dentro de um aplicativo cliente, usando a chamada do SDK do .NET (C#) CreateOrReplaceEventRouteAsync:
string eventFilter = "$eventType = 'DigitalTwinTelemetryMessages' or $eventType = 'DigitalTwinLifecycleNotification'";
var er = new DigitalTwinsEventRoute("endpointName", eventFilter);
await client.CreateOrReplaceEventRouteAsync("routeId", er);
Primeiro, um objeto
DigitalTwinsEventRouteé criado e o construtor usa o nome de um ponto de extremidade. Este campoendpointNameidentifica um ponto de extremidade como Hubs de eventos, Grade de Eventos ou Barramento de Serviço. Esses pontos de extremidade devem ser criados em sua assinatura e anexados aos Gêmeos Digitais do Azure usando as APIs do plano de controle antes de fazer essa chamada de registro.O objeto da rota de evento também tem um campo Filtro, que pode ser usado para restringir os tipos de eventos que seguem essa rota. Um filtro de
truehabilita a rota sem filtragem extra (um filtro defalsedesabilita a rota).Esse objeto de rota de evento é passado para
CreateOrReplaceEventRouteAsync, junto com um nome para a rota.
Dica
Todas as funções do SDK são fornecidas em versões síncronas e assíncronas.
Para obter instruções detalhadas sobre criação de rotas de evento, consulte Criar rotas e filtros.
Eventos de mensagens mortas
Quando um ponto de extremidade não puder entregar um evento várias vezes ou depois de tentar entregar o evento um determinado número de vezes, ela poderá enviar o evento não entregue a uma conta de armazenamento. Esse processo é conhecido como armazenamento de mensagens mortas. Os Gêmeos Digitais do Azure armazenarão um evento como mensagem morta quando uma das condições a seguir for atendida:
- O evento não é entregue dentro do período de vida útil
- O número de tentativas de entregar o evento excedeu o limite
Se qualquer uma das condições for atendida, o evento será removido ou armazenado como mensagem morta. Por padrão, cada ponto de extremidade não ativa as mensagens mortas. Para habilitá-lo, você deve especificar uma conta de armazenamento para reter eventos que não foram entregues ao criar o ponto de extremidade. Você pode, então, extrair eventos dessa conta de armazenamento para resolver as entregas.
Antes de configurar o local de mensagens mortas, você deve ter uma conta de armazenamento com um contêiner. Você fornece a URL para esse contêiner ao criar o ponto de extremidade. A mensagem morta é fornecida como uma URL de contêiner com um token SAS. Esse token precisa apenas da permissão write para o contêiner de destino dentro da conta de armazenamento. A URL totalmente formada estará no formato de: https://<storage-account-name>.blob.core.windows.net/<container-name>?<SAS-token>
Para saber mais sobre tokens SAS, confira: Conceder acesso limitado aos recursos de Armazenamento do Azure usando SAS (assinaturas de acesso compartilhado)
Para saber como configurar um ponto de extremidade com mensagens mortas, consulte Opções de ponto de extremidade: mensagens mortas.
Tipos de mensagens de evento
Tipos diferentes de eventos no Hub IoT e nos Gêmeos Digitais do Azure produzem diferentes tipos de mensagens de notificação, conforme descrito abaixo.
| 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 |
Próximas etapas
Continue com as instruções passo a passo para configurar pontos de extremidade e rotas de evento:
Ou siga este passo a passo para configurar um tratamento de evento do Azure Function gêmeo a gêmeo nos Gêmeos Digitais do Azure: