Criar rotas de eventos e filtros em Gêmeos Digitais do Azure
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 Pontos de extremidade 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
- Para desativar a rota para que nenhum evento seja enviado, use um valor de filtro de
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 ponto de extremidade 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.
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 trueextremidade receberão diferentes tipos de eventos 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.
Para adicionar um filtro de eventos enquanto você cria 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 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 o editor Avançado para ativá-la. Em seguida, você pode escrever seus próprios filtros de evento na caixa Filtro :
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.UpdateMicrosoft.DigitalTwins.Relationship.CreateMicrosoft.DigitalTwins.Relationship.UpdateMicrosoft.DigitalTwins.Relationship.Delete microsoft.iot.telemetry |
| Origem | 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> |
| Assunto | 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 do 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 patch seção de uma notificaçã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 seguintes operadores 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 falhas, 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: