Criar rotas e filtros de eventos nos Gêmeos Digitais do Azure

Este artigo orienta você pelo processo de criação de rotas de eventos usando o portal do Azure, comandos de rota az dt da CLI do Azure, APIs de plano de dados de Rotas de Eventos e o SDK do .NET (C#).

Roteamento de notificações de eventos de Gêmeos Digitais do Azure para serviços downstream ou recursos de computação conectados é 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 aborda a segunda etapa, configurar rotas para controlar quais eventos são entregues a quais pontos de extremidade do Gêmeo Digital do Azure. Para prosseguir com este artigo, você deve ter pontos de extremidade já criados.

Pré-requisitos

• Você precisará ter uma conta do Azure, que pode ser configurada gratuitamente

• Você precisará de uma instância dos Gêmeos Digitais do Azure na assinatura do Azure. Se você ainda não tiver uma instância, crie uma seguindo as etapas em Configurar uma instância e uma autenticação. Faça com que os seguintes valores da configuração sejam úteis para uso posterior neste artigo:

  • Nome da instância
  • Grupo de recursos

  Você pode encontrar esses detalhes no portal do Azure depois de configurar a sua instância.

  

• Crie um ponto de extremidade usando as instruções em Criar pontos de extremidade. Neste artigo, você criará uma rota para enviar dados para esse ponto de extremidade.

Em seguida, siga as instruções abaixo se você pretende usar a CLI do Azure ao seguir este guia.

Preparar o ambiente para a CLI do Azure

• Use o ambiente Bash no Azure Cloud Shell. Para obter mais informações, confira Início Rápido para Bash no Azure Cloud Shell.

  

• Se preferir executar os comandos de referência da CLI localmente, instale a CLI do Azure. Para execuções no Windows ou no macOS, considere executar a CLI do Azure em um contêiner do Docker. Para obter mais informações, confira Como executar a CLI do Azure em um contêiner do Docker.

  • Se estiver usando uma instalação local, entre com a CLI do Azure usando o comando az login. Para concluir o processo de autenticação, siga as etapas exibidas no terminal. Para ver outras opções de entrada, confira Conectar-se com a CLI do Azure.

  • Quando solicitado, instale a extensão da CLI do Azure no primeiro uso. Para obter mais informações sobre extensões, confira Usar extensões com a CLI do Azure.

  • Execute az version para localizar a versão e as bibliotecas dependentes que estão instaladas. Para fazer a atualização para a versão mais recente, execute az upgrade.

Criar uma rota de evento

Depois de criar um ponto de extremidade, você precisará definir uma rota de evento para realmente enviar dados para o ponto de extremidade. Essas rotas permitem que os desenvolvedores conectem o fluxo de eventos de todo o sistema e aos serviços downstream. Uma só rota pode permitir a escolha de várias notificações e tipos de eventos. Leia mais sobre as rotas de eventos em Pontos de extremidade e rotas de eventos.

Observação

Verifique se você criou pelo menos um ponto de extremidade, conforme descrito nos Pré-requisitos, antes de passar para a criação de uma rota.

Se você implantou seus pontos de extremidade recentemente, valide se eles terminaram de implantar antes de tentar usá-los para uma nova rota de eventos. Se a implantação da rota falhar porque os pontos de extremidade não estão prontos, aguarde alguns minutos e tente novamente.

Se você estiver fazendo o script deste fluxo, talvez seja necessário levar isso em consideração, criando 2 a 3 minutos de tempo de espera para que o serviço do ponto de extremidade termine a implantação antes de avançar para a configuração da rota.

Uma definição de rota pode conter estes elementos:

• O nome da rota que você deseja usar
• O nome do ponto de extremidade que você deseja usar
• Um filtro que define quais eventos são enviados para o ponto de extremidade
  • Para desabilitar a rota para que nenhum evento seja enviado, use um valor de filtro de false
  • Para habilitar uma rota sem filtragem específica, use um valor de filtro de true
  • Para obter detalhes de outros tipos de filtro, veja a seção Filtrar eventos abaixo

Se não houver nenhum nome de rota, nenhuma mensagem será roteada fora dos Gêmeos Digitais do Azure. Se houver um nome de rota e o filtro for true, todas as mensagens serão roteadas para o ponto de extremidade. Se houver um nome de rota e um filtro distinto for adicionado, as mensagens serão filtradas com base no filtro.

As rotas de eventos podem ser criadas com o portal do Azure, as APIs de plano de dados de EventRoutes ou os comandos az dt route da CLI. O restante desta seção percorre o processo de criação.

Portal

Para criar uma rota de evento, acesse a página de detalhes da sua instância dos Gêmeos Digitais do Azure no portal do Azure (você pode encontrar a instância inserindo o nome dela na barra de pesquisa do portal).

No menu da instância, escolha Rotas de eventos. Então, na página Rotas de eventos a seguir, escolha + Criar uma rota de evento.

Na página Criar uma rota de evento que é exibida, escolha no mínimo:

• Um nome para a sua rota no campo Nome
• O Ponto de extremidade que você quer usar para criar a rota

Para habilitar a rota, você também deve Adicionar um filtro de rota de evento de pelo menos true. (Deixar o valor padrão de false criará a rota, mas nenhum evento será enviado a ela). Para isso, habilite a opção do Editor avançado e escreva true na caixa Filtro.

Quando concluir, clique no botão Salvar para criar a rota de evento.

CLI

As rotas também podem ser gerenciadas usando os comandos az dt route para a CLI dos Gêmeos Digitais do Azure.

Para saber como usar a CLI e quais comandos estão disponíveis, veja Conjunto de comandos da CLI dos Gêmeos Digitais do Azure.

SDK .NET

Esta seção mostra como criar uma rota de evento usando o SDK do .NET (C#).

CreateOrReplaceEventRouteAsync é a chamada do SDK que é usada para adicionar uma rota de evento. Segue abaixo um exemplo do uso dela:

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

Dica

Todas as funções do SDK são fornecidas em versões síncronas e assíncronas.

Código do SDK de exemplo da rota de evento

O seguinte método de exemplo mostra como criar, listar e excluir uma rota de evento com o SDK do C#:

public static async Task CreateEventRouteAsync(DigitalTwinsClient client, string routeId, DigitalTwinsEventRoute er)
{
    try
    {
        Console.WriteLine("Create a route: testRoute1");

        // Make a filter that passes everything
        er.Filter = "true";
        await client.CreateOrReplaceEventRouteAsync(routeId, er);
        Console.WriteLine("Create route succeeded.");

        // List routes
        AsyncPageable<DigitalTwinsEventRoute> results = client.GetEventRoutesAsync();
        await foreach (DigitalTwinsEventRoute route in results)
        {
            Console.WriteLine($"Route {route.Id} to endpoint {route.EndpointName} with filter {route.Filter} ");
        }

        // Delete route created earlier
        Console.WriteLine($"Deleting route {routeId}:");
        await client.DeleteEventRouteAsync(routeId);
    }
    catch (RequestFailedException e)
    {
        Console.WriteLine($"*** Error in event route processing ({e.ErrorCode}):\n${e.Message}");
    }
}

Filtrar eventos

Como descrito acima, as rotas têm um campo de filtro. Se o valor do filtro da rota for false, nenhum evento será enviado ao ponto de extremidade.

Depois de habilitar um filtro mínimo de true, os pontos de extremidade receberão diferentes tipos de eventos dos Gêmeos Digitais do Azure:

• Telemetria acionada por gêmeos digitais usando a API de serviço Gêmeos Digitais do Azure
• Notificações de alteração de propriedade do gêmeo, acionadas em alterações de propriedade para qualquer gêmeo na instância dos Gêmeos Digitais do Azure
• Eventos de ciclo de vida, acionados quando os gêmeos ou os relacionamentos são criados ou excluídos

Você pode restringir os tipos de eventos que estão sendo enviados definindo um filtro mais específico.

Observação

Os filtros diferenciam maiúsculas de minúsculas e precisam corresponder às maiúsculas e minúsculas do conteúdo. Para filtros de telemetria, isso significa que o invólucro precisa corresponder ao invólucro na telemetria enviada pelo dispositivo.

Portal

Para adicionar um filtro de evento ao criar uma rota de evento, use a seção Adicionar um filtro de rota de evento da página Criar uma rota de evento.

Você pode escolher algumas opções básicas de filtro comum ou usar as opções de filtro avançado para escrever os seus próprios filtros personalizados.

Usar os filtros básicos

Para usar os filtros básicos, expanda a opção Tipos de eventos e escolha as caixas de seleção que correspondem aos eventos que você quer enviar para o ponto de extremidade.

Ao fazer isso, preencherá automaticamente a caixa de texto de filtro com o texto do filtro que você escolheu:

Usar os filtros avançados

É possível usar a opção de filtro avançado para escrever os seus próprios filtros personalizados.

Para criar uma rota de evento com opções de filtros avançados, habilite a opção do Editor avançado. Em seguida, você pode escrever os seus próprios filtros de eventos na caixa Filtro:

API

Você pode usar as APIs do plano de dados de Rotas de Eventos para gravar filtros personalizados. Para adicionar um filtro, você pode usar uma solicitação PUT para https://<Your-Azure-Digital-Twins-host-name>/eventRoutes/<event-route-name>?api-version=2020-10-31 com o seguinte corpo:

{
    "endpointName": "<endpoint-name>",
    "filter": "<filter-text>"
}

Filtros de rota com suporte

Aqui estão os filtros de rota compatíveis.

Nome do filtro	Descrição	Filtrar esquema de texto	Valores com suporte
Verdadeiro/Falso	Permite criar uma rota sem filtragem ou desabilitar uma rota para que nenhum evento seja enviado	<true/false>	true = a rota está habilitada sem filtragem false = a rota está desabilitada
Tipo	O tipo de evento que flui pela sua instância dos Gêmeos Digitais	type = '<event-type>'	Aqui estão os valores de tipo de evento possíveis: Microsoft.DigitalTwins.Twin.Create Microsoft.DigitalTwins.Twin.Delete Microsoft.DigitalTwins.Twin.Update Microsoft.DigitalTwins.Relationship.Create Microsoft.DigitalTwins.Relationship.Update Microsoft.DigitalTwins.Relationship.Delete microsoft.iot.telemetry
Origem	Nome da instância dos Gêmeos Digitais do Azure	source = '<host-name>'	Aqui estão os possíveis valores de nome de host: Para notificações: <your-Digital-Twins-instance>.api.<your-region>.digitaltwins.azure.net Para telemetria: <your-Digital-Twins-instance>.api.<your-region>.digitaltwins.azure.net/<twin-ID>
Assunto	Uma descrição do evento no contexto da origem do evento acima	subject = '<subject>'	Aqui estão os possíveis valores de assunto: Para notificações: o assunto é <twin-ID> ou um formato de URI para entidades, que são identificadas exclusivamente por várias partes ou IDs: <twin-ID>/relationships/<relationship-ID> Para telemetria: o assunto é o caminho do componente (se a telemetria é emitida de um componente gêmeo), como comp1.comp2. Se a telemetria não é emitida de um componente, o campo assunto fica em branco.
Esquema de dados	ID do modelo DTDL	dataschema = '<model-dtmi-ID>'	Para telemetria: 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 Para notificações (criar/excluir): o esquema de dados pode ser acessado no corpo da notificação, em $body.$metadata.$model. Para notificações (atualizar): o esquema de dados pode ser acessado no corpo da notificação, em $body.modelId
Tipo de conteúdo	Tipo de conteúdo do valor de dados.	datacontenttype = '<content-type>'	O tipo de conteúdo é application/json.
Versão de especificação	A versão do esquema de evento que você está usando	specversion = '<version>'	A versão deve ser 1.0. Este valor indica o esquema CloudEvents versão 1.0
Corpo da notificação	Referência a qualquer propriedade no campo data de uma notificação.	$body.<property>	Confira Notificações de eventos para ver exemplos de notificações. Qualquer propriedade no campo data pode ser referenciada usando $body

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 de patch de uma notificação de alteração de gêmeo digital.

Os tipos de dados a seguir têm suporte como valores retornados por referências aos dados acima:

Tipo de dados	Exemplo
String	STARTS_WITH($body.$metadata.$model, 'dtmi:example:com:floor') CONTAINS(subject, '<twin-ID>')
Inteiro	$body.errorCode > 200
Double	$body.temperature <= 5.5
Bool	$body.poweredOn = true
Null	$body.prop != null

Os seguintes operadores têm suporte ao definir os filtros de rota:

Família	Operadores	Exemplo
Lógico	AND, OR, ( )	(type != 'microsoft.iot.telemetry' OR datacontenttype = 'application/json') OR (specversion != '1.0')
Comparação	<, <=, >, >=, =, !=	$body.temperature <= 5.5

As funções a seguir têm suporte ao definir os filtros de rota:

Função	descrição	Exemplo
STARTS_WITH(x,y)	Retornará true se o valor x começar com a cadeia de caracteres y.	STARTS_WITH($body.$metadata.$model, 'dtmi:example:com:floor')
ENDS_WITH(x,y)	Retornará true se o valor x terminar com a cadeia de caracteres y.	ENDS_WITH($body.$metadata.$model, 'floor;1')
CONTAINS(x,y)	Retornará true se o valor x contiver a cadeia de caracteres y.	CONTAINS(subject, '<twin-ID>')

Quando você implementa ou atualiza um filtro, a alteração pode levar alguns minutos para ser refletida no pipeline de dados.

Monitorar rotas de eventos

As métricas de roteamento, como contagem, latência e taxa de falha, podem ser exibidas no portal do Azure.

Para informações sobre como exibir e gerenciar métricas com o Azure Monitor, confira Introdução ao Metrics Explorer. Para uma lista completa das métricas de roteamento disponíveis para os Gêmeos Digitais do Azure, confira Métricas de roteamento dos Gêmeos Digitais do Azure.

Próximas etapas

Leia sobre os diversos tipos de mensagens de evento que você pode receber:

• Notificações de eventos