Rotear eventos do Azure Digital Twins

Este artigo descreve o processo que os Gêmeos Digitais do Azure usam para enviar dados de eventos, tanto para rotear 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 eventos para enviar dados para esses pontos de extremidade. Este artigo detalha cada um desses conceitos. Ele também explica o que acontece quando um ponto de extremidade não consegue entregar um evento no tempo (um processo conhecido como letras mortas).

Visão geral do roteamento de eventos

Há dois cenários principais para enviar dados do Azure Digital Twins e as rotas de eventos são usadas para realizar ambos:

• Enviar dados de eventos de um gêmeo no gráfico de Gêmeos Digitais do Azure para outro. Por exemplo, quando uma propriedade em um gêmeo digital muda, você pode querer notificar e atualizar outro gêmeo digital com base nos dados atualizados.
• Enviar dados fora dos Gêmeos Digitais do Azure para serviços de dados downstream para mais armazenamento ou processamento. Por exemplo, se já estiver a utilizar o 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 enviando dados de eventos dos Gêmeos Digitais do Azure para pontos de extremidade personalizados em suas assinaturas. Atualmente, há suporte para 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 intermediário, enviando dados para destinos finais, como o Azure Maps, ou de volta para os Gêmeos Digitais do Azure para atualizações de gráficos dependentes.

O diagrama a seguir ilustra o fluxo de dados de eventos por meio de uma solução de IoT maior, que inclui o envio de dados de Gêmeos Digitais do Azure por meio de pontos de extremidade para outros Serviços do Azure, bem como de volta para os Gêmeos Digitais do Azure:

Para saída de dados fora dos Gêmeos Digitais do Azure, os destinos downstream típicos para rotas de eventos são o 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 roteamento de eventos internos de gêmeos digitais dentro da mesma solução de Gêmeos Digitais do Azure, continue para a próxima seção.

Encaminhar eventos internos de gêmeos digitais

As rotas de eventos são o mecanismo usado para manipular eventos dentro do gráfico gêmeo, enviando dados do gêmeo digital para o gêmeo digital. Esse tipo de manipulação de eventos é feito conectando rotas de eventos por meio da Grade de Eventos para 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 gráfico gêmeo com base em um evento que recebeu por meio da rota do evento, é útil que ele saiba 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 atravessar relações para encontrar 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 acesso de forma independente.

Para percorrer o processo de configuração de uma função do Azure para processar eventos de gêmeos digitais, consulte Configurar a manipulação de eventos de gêmeo para gêmeo.

Criação de pontos de extremidade

Para definir uma rota de evento, primeiro os programadores têm de definir pontos finais. Um ponto de extremidade é um destino fora dos Gêmeos Digitais do Azure que dá suporte a uma conexão de rota. Os destinos suportados incluem:

• Tópicos personalizados da Grelha de Eventos
• Hubs de Eventos do
• Service Bus

Para criar um ponto de extremidade, você pode usar as APIs REST do Azure Digital Twins, os 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 Service Bus)
• 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 usar o ponto de extremidade com uma identidade gerenciada atribuída pelo sistema ou pelo usuário. Essa opção só está disponível para Hubs de Eventos e pontos de extremidade do tipo Service Bus (não há suporte para Grade de Eventos).

As APIs de ponto de extremidade disponíveis no plano de controle são:

• Criar ponto de extremidade
• Obter lista de pontos finais
• Obter ponto de extremidade por nome
• Excluir 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 eventos

Para criar uma rota de evento, você pode usar as APIs REST do Azure Digital Twins, os comandos da CLI ou o portal do Azure.

Aqui está um exemplo de criação de uma rota de evento dentro de um aplicativo cliente, usando a CreateOrReplaceEventRouteAsync chamada .NET (C#) SDK :

string eventFilter = "$eventType = 'DigitalTwinTelemetryMessages' or $eventType = 'DigitalTwinLifecycleNotification'";
var er = new DigitalTwinsEventRoute("endpointName", eventFilter);
await client.CreateOrReplaceEventRouteAsync("routeId", er);

1. Primeiro, um DigitalTwinsEventRoute objeto é criado e o construtor toma o nome de um ponto de extremidade. Este endpointName campo identifica 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 APIs de plano de controle antes de fazer essa chamada de registro.

2. O objeto de 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 true habilita a rota sem filtragem extra (um filtro de false desativa a rota).

3. Esse objeto de rota de evento é então passado para CreateOrReplaceEventRouteAsync, juntamente com um nome para a rota.

Gorjeta

Todas as funções do SDK vêm em versões síncronas e assíncronas.

Para obter instruções detalhadas sobre como criar rotas de eventos, consulte Criar rotas e filtros.

Eventos de letra morta

Quando um ponto de extremidade não consegue entregar um evento dentro de um determinado período de tempo ou depois de tentar entregar o evento várias vezes, ele pode enviar o evento não entregue para uma conta de armazenamento. Este processo é conhecido como dead-lettering. Os Gêmeos Digitais do Azure darão letra morta a um evento quando uma das seguintes condições for atendida:

• O evento não é entregue dentro do período de tempo de vida
• O número de tentativas de entrega do evento excedeu o limite

Se qualquer uma das condições for cumprida, o evento é descartado ou colocado em letra morta. Por padrão, cada ponto de extremidade não ativa letras mortas. Para habilitá-lo, você deve especificar uma conta de armazenamento para manter eventos não entregues ao criar o ponto de extremidade. Em seguida, você pode extrair eventos dessa conta de armazenamento para resolver entregas.

Antes de definir o local de letra morta, 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 letra morta é fornecida como uma URL de contêiner com um token SAS. Esse token precisa apenas write de permissão para o contêiner de destino dentro da conta de armazenamento. O URL totalmente formado será no formato de: https://<storage-account-name>.blob.core.windows.net/<container-name>?<SAS-token>

Para saber mais sobre tokens SAS, consulte: Conceder acesso limitado aos recursos do Armazenamento do Azure usando assinaturas de acesso compartilhado (SAS)

Para saber como configurar um ponto de extremidade com letras mortas, consulte Opções de ponto de extremidade: letras mortas.

Tipos de mensagens de evento

Diferentes tipos 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 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

Próximos passos

Continue para as instruções passo a passo para configurar pontos de extremidade e rotas de eventos:

• Criar pontos de extremidade e Criar rotas e filtros

Ou, siga este passo a passo para configurar uma Função do Azure para manipulação de eventos de gêmeo para gêmeo nos Gêmeos Digitais do Azure:

• Configure o tratamento de eventos duplo-para-gêmeos.