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

Artigo
01/04/2024

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

Rotear notificações de eventos dos 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, configurando 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á de uma conta do Azure, que pode ser configurada gratuitamente
Você precisará de uma instância do Azure Digital Twins em sua assinatura do Azure. Se você ainda não tiver uma instância, poderá criar uma usando as etapas em Configurar uma instância e autenticação. Tenha os seguintes valores da configuração à mão para usar mais adiante neste artigo:
- Nome da instância
- Grupo de recursos
Você pode encontrar esses detalhes no portal do Azure depois de configurar 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 enquanto segue este guia.

Prepare o seu ambiente para o CLI do Azure

Use o ambiente Bash no Azure Cloud Shell. Para obter mais informações, consulte Guia de início rápido para Bash no Azure Cloud Shell.
Se preferir executar comandos de referência da CLI localmente, instale a CLI do Azure. Se estiver a utilizar o Windows ou macOS, considere executar a CLI do Azure num contentor Docker. Para obter mais informações, consulte Como executar a CLI do Azure em um contêiner do Docker.
- Se estiver a utilizar uma instalação local, inicie sessão no CLI do Azure ao utilizar o comando az login. Para concluir o processo de autenticação, siga os passos apresentados no seu terminal. Para outras opções de entrada, consulte Entrar com a CLI do Azure.
- Quando solicitado, instale a extensão da CLI do Azure na primeira utilização. Para obter mais informações sobre as extensões, veja Utilizar extensões com o CLI do Azure.
- Execute o comando az version para localizar a versão e as bibliotecas dependentes instaladas. Para atualizar para a versão mais recente, execute o comando 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 em todo o sistema e aos serviços downstream. Uma única rota pode permitir a seleção de várias notificações e tipos de eventos. Leia mais sobre rotas de eventos em Endpoints e rotas de eventos.

Nota

Certifique-se de ter criado 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 a implantação antes de tentar usá-los para uma nova rota de evento. 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 criando scripts para esse fluxo, convém levar isso em conta criando de 2 a 3 minutos de tempo de espera para que o serviço de ponto de extremidade termine a implantação antes de passar para a configuração de 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 desativar a rota para que nenhum evento seja enviado, use um valor de filtro de false
- Para habilitar uma rota que não tenha filtragem específica, use um valor de filtro de true
- Para obter detalhes sobre qualquer outro tipo de filtro, consulte a seção Filtrar eventos abaixo

Se não houver um 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 diferente for adicionado, as mensagens serão filtradas com base no filtro.

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

Para criar uma rota de evento, vá para a página de detalhes da sua instância do Azure Digital Twins no portal do Azure (você pode encontrar a instância inserindo seu nome na barra de pesquisa do portal ).

No menu de instâncias, selecione Rotas de eventos. Em seguida, na página Rotas de eventos a seguir, selecione + Criar uma rota de evento.

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

Um nome para a sua rota no campo Nome
O Endpoint que você deseja usar para criar a rota

Para que a rota seja habilitada, 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 para ela.) Para fazer isso, alterne o interruptor para o editor avançado para ativá-lo e escreva true na caixa Filtro .

Quando terminar, selecione o botão Salvar para criar a rota do evento.

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

CreateOrReplaceEventRouteAsync é a chamada SDK usada para adicionar uma rota de evento. Aqui está um exemplo de seu uso:

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

Gorjeta

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

Código SDK de exemplo de rota de evento

O método de exemplo a seguir 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 na sua rota for false, nenhum evento será enviado para o seu ponto de extremidade.

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

Telemetria acionada por gêmeos digitais usando a API de serviço do Azure Digital Twins
Notificações de alteração de propriedade gêmea, disparadas em alterações de propriedade para qualquer gêmeo na instância do Azure Digital Twins
Eventos do ciclo de vida, disparados quando gêmeos ou 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.

Nota

Os filtros diferenciam maiúsculas de minúsculas e precisam corresponder ao caso da carga útil. Para filtros de telemetria, isso significa que o invólucro precisa corresponder ao invólucro na telemetria enviada pelo dispositivo.

Portal
API

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

Você pode selecionar entre algumas opções básicas de filtro comuns ou usar as opções de filtro avançadas para escrever seus próprios filtros personalizados.

Use os filtros básicos

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

Isso preencherá automaticamente a caixa de texto do filtro com o texto do filtro selecionado:

Utilize os filtros avançados

Você também pode usar a opção de filtro avançado para escrever seus próprios filtros personalizados.

Para criar uma rota de eventos com opções avançadas de filtro, alterne a opção para que o editor Avançado a habilite. Em seguida, você pode escrever seus próprios filtros de evento na caixa Filtro :

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

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

Filtros de rota suportados

Aqui estão os filtros de rota suportados.

Nome do filtro	Description	Filtrar esquema de texto	Valores suportados
Verdadeiro / Falso	Permite criar uma rota sem filtragem ou desativar uma rota para que nenhum evento seja enviado	`<true/false>`	`true` = a rota está ativada sem filtragem `false` = a rota está desativada
Type	O tipo de evento que flui através de sua instância de gêmeo digital	`type = '<event-type>'`	Aqui estão os valores possíveis de tipo de evento: `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`
Source	Nome da instância do Azure Digital Twins	`source = '<host-name>'`	Aqui estão os possíveis valores de nome de host: Para as notificações: `<your-Digital-Twins-instance>.api.<your-region>.digitaltwins.azure.net` Para a telemetria: `<your-Digital-Twins-instance>.api.<your-region>.digitaltwins.azure.net/<twin-ID>`
Subject	Uma descrição do evento no contexto da fonte do evento acima	`subject = '<subject>'`	Aqui estão os valores de assunto possíveis: Para notificações: O assunto é `<twin-ID>` ou um formato URI para assuntos, que são identificados exclusivamente por várias partes ou IDs: `<twin-ID>/relationships/<relationship-ID>` Para telemetria: O assunto é o caminho do componente (se a telemetria for emitida por um componente gêmeo), como `comp1.comp2`. Se a telemetria não for emitida por um componente, seu campo de assunto estará vazio.
Esquema de dados	ID do modelo DTDL	`dataschema = '<model-dtmi-ID>'`	Para telemetria: 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` Para notificações (criar/excluir): O esquema de dados pode ser acessado no corpo da notificação em `$body.$metadata.$model`. Para notificações (atualização): 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 spec	A versão do esquema de eventos que você está usando	`specversion = '<version>'`	A versão deve ser `1.0`. Esse valor indica o esquema CloudEvents versão 1.0
Organismo de notificação	Fazer referência a `data` qualquer propriedade no campo de uma notificação	`$body.<property>`	Consulte Notificações de eventos para obter exemplos de notificações. Qualquer propriedade no campo pode ser referenciada `data` usando `$body`

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

Os seguintes tipos de dados são suportados 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>')`
Número inteiro	`$body.errorCode > 200`
Duplo	`$body.temperature <= 5.5`
Bool	`$body.poweredOn = true`
Nulo	`$body.prop != null`

Os operadores a seguir são suportados ao definir filtros de rota:

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

As seguintes funções são suportadas ao definir filtros de rota:

Function	Description	Exemplo
STARTS_WITH(x,y)	Retorna 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)	Retorna true se o valor `x` terminar com a cadeia de caracteres `y`.	`ENDS_WITH($body.$metadata.$model, 'floor;1')`
CONTÉM(x,y)	Retorna 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 obter informações sobre como exibir e gerenciar métricas com o Azure Monitor, consulte Introdução ao explorador de métricas. Para obter uma lista completa das métricas de roteamento disponíveis para os Gêmeos Digitais do Azure, consulte Métricas de roteamento dos Gêmeos Digitais do Azure.

Próximos passos

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

Notificações de eventos

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

Pré-requisitos

Prepare o seu ambiente para o CLI do Azure

Criar uma rota de evento

Filtrar eventos

Use os filtros básicos

Utilize os filtros avançados

Filtros de rota suportados

Monitorar rotas de eventos

Próximos passos

Recursos adicionais