Gerir pontos finais e rotas em Azure Digital Twins (portal)

Em Azure Digital Twins, você pode encaminhar notificações de eventos para serviços a jusante ou recursos de computação conectados. Isto é feito ao, em primeiro lugar, configurar pontos finais que podem receber os eventos. Em seguida, pode criar rotas de evento que especifiquem que eventos gerados pelo Azure Digital Twins são entregues a que pontos finais.

Este artigo acompanha-o através do processo de criação de pontos finais e rotas utilizando o portal Azure.

Em alternativa, também pode gerir pontos finais e rotas com as APIs rotasde eventos, os SDKs,ou o Azure Digital Twins CLI. Para uma versão deste artigo que utiliza estes mecanismos em vez do portal, consulte Como-a-fazer: Gerir pontos finais e rotas (APIs e CLI).

Pré-requisitos

  • Você vai precisar de uma conta Azure, que pode ser configurada gratuitamente
  • Você precisará de uma instância Azure Digital Twins na sua assinatura Azure. Se ainda não tiver um caso, pode criar um utilizando os passos em Como-a-: Configurar um caso e autenticação. Ter os seguintes valores da configuração útil para usar mais tarde neste artigo:
    • Nome da instância
    • Grupo de recursos

Pode encontrar estes detalhes no portal Azure depois de configurar o seu caso. Inicie sessão no portal e procure o nome do seu caso na barra de pesquisa do portal.

Screenshot da barra de pesquisa do portal Azure.

Selecione a sua instância a partir dos resultados para ver estes detalhes na Visão Geral, para o seu exemplo:

Screenshot da página Overview para uma instância Azure Digital Twins no portal Azure. O nome e o grupo de recursos estão em destaque.

Criar um ponto final para a Azure Digital Twins

Estes são os tipos suportados de pontos finais que pode criar, para o seu exemplo:

Para obter mais informações sobre os diferentes tipos de pontos finais, consulte Escolha entre os serviços de mensagens Azure.

Esta secção explica como criar um destes pontos finais no portal Azure.

Pré-requisito: Criar recursos de ponto final

Para ligar um ponto final à Azure Digital Twins, o tópico da grelha de eventos, o centro de eventos ou o tópico do Service Bus que está a usar para o ponto final já precisa de existir.

Utilize o gráfico seguinte para ver que recursos devem ser criados antes de criar o seu ponto final.

Tipo de ponto final Recursos necessários (ligados às instruções de criação)
Ponto final da Grelha de Eventos tópico de grelha de evento
Ponto final do Event Hubs Espaço   de nomes de Centros de   Eventos

centro de eventos

(Opcional) regra de autorização para a autenticação baseada em chaves
Ponto final do ônibus de serviço Espaço de nome de ônibus de serviço

Tópico de ônibus de serviço

(Opcional) regra de autorização para a autenticação baseada em chaves

Criar o ponto final

Uma vez criados os recursos do ponto final, podes usá-los para um ponto final da Azure Digital Twins. Para criar um novo ponto final, aceda à página do seu caso no portal Azure (pode encontrar a instância introduzindo o seu nome na barra de pesquisa do portal).

  1. A partir do menu de exemplos, selecione Endpoints. Em seguida, a partir da página Endpoints que se segue, selecione + Crie um ponto final. Isto abrirá a página 'Criar' um ponto final, onde preencherá os campos nos seguintes passos.

    Screenshot de criar um ponto final de grade de evento tipo no portal Azure.

  2. Insira um Nome para o seu ponto final e escolha o tipo ponto final.

  3. Complete os outros detalhes necessários para o seu tipo de ponto final, incluindo a sua subscrição e os recursos de ponto final acima descritos.

    1. Apenas para pontos finais do Event Hub e do Service Bus, tem de selecionar um tipo de autenticação. Pode utilizar a autenticação baseada em chaves com uma regra de autorização pré-criada ou autenticação baseada na identidade se utilizar o ponto final com uma identidade gerida para a sua instância Azure Digital Twins.
  4. Termine de criar o seu ponto final selecionando Save.

Importante

Para utilizar com sucesso a autenticação baseada na identidade para o seu ponto final, terá de criar uma identidade gerida para o seu exemplo, seguindo os passos em Como-a: Habilitar uma identidade gerida para eventos de encaminhamento (pré-visualização).

Depois de criar o seu ponto final, pode verificar se o ponto final foi criado com sucesso, verificando o ícone de notificação na barra superior do portal Azure:

Screenshot da notificação para verificar a criação de um ponto final no portal Azure.

Se a criação do ponto final falhar, observe a mensagem de erro e redaça após alguns minutos.

Também pode ver o ponto final que foi criado de volta na página Endpoints para a sua instância Azure Digital Twins.

Agora, a grelha de eventos, o centro de eventos ou o tópico Service Bus estão disponíveis como ponto final dentro da Azure Digital Twins, com o nome que escolheu para o ponto final. Normalmente, você usará esse nome como alvo de uma rota de eventos, que irá criar mais tarde neste artigo.

Criar um ponto final com letras mortas

Quando um ponto final não consegue entregar um evento dentro de um determinado período de tempo ou depois de tentar entregar o evento um certo número de vezes, pode enviar o evento não entregue para uma conta de armazenamento. Este processo é conhecido como letra morta.

Para criar um ponto final com letras mortas ativadas, deve utilizar os comandos CLI ou aviões de controlo APIs para criar o seu ponto final, em vez do portal Azure.

Para obter instruções sobre como fazê-lo com estas ferramentas, consulte as APIs e a versão CLI deste artigo.

Criar uma rota de eventos

Para enviar dados da Azure Digital Twins para um ponto final, terá de definir uma rota de eventos. Estas rotas permitem que os desenvolvedores liguem o fluxo de eventos, em todo o sistema e para os serviços a jusante. Leia mais sobre as rotas de eventos em Conceitos: Eventos de Roteamento Azure Digital Twins.

Pré-requisito: É necessário criar pontos finais, conforme descrito anteriormente neste artigo, antes de poder passar a criar uma rota. Pode proceder à criação de uma rota de eventos assim que os seus pontos finais terminarem a sua configuração.

Nota

Se implementou recentemente os seus pontos finais, valide que terminaram de ser implementados antes de tentar usá-los para uma nova rota de eventos. Se não conseguir configurar a rota porque os pontos finais não estão prontos, aguarde alguns minutos e tente novamente.

Etapas de criação com o portal Azure

Uma definição de rota de evento contém estes elementos:

  • O nome da rota que pretende usar
  • O nome do ponto final que quer usar
  • Um filtro que define que eventos são enviados para o ponto final
    • Para desativar a rota para que não sejam enviados eventos, use um valor de filtro de false
    • Para ativar uma rota que não tenha filtragem específica, use um valor de filtro de true
    • Para obter mais informações sobre qualquer outro tipo de filtro, consulte a secção de eventos do Filtro abaixo.

Uma única rota pode permitir a seleção de várias notificações e tipos de eventos.

Para criar uma rota de eventos, aceda à página de detalhes para a sua instância Azure Digital Twins no portal Azure (pode encontrar a instância introduzindo o seu nome na barra de pesquisa do portal).

A partir do menu de instâncias, selecione rotas de Eventos. Em seguida, a partir da página de rotas do Evento que se segue, selecione + Crie uma rota de eventos.

Na página de rota de eventos Create que se abre, escolha no mínimo:

  • Um nome para o seu percurso no campo Nome
  • O Ponto Final que pretende utilizar para criar a rota

Para que o percurso seja ativado, também deve adicionar um filtro de rota de eventos de pelo menos true . (Deixar o valor padrão de false irá criar a rota, mas nenhum evento será enviado para ele.) Para isso, alternar o interruptor para o editor Avançado para o ativar e escrever na true caixa Filtro.

Screenshot de criar uma rota de eventos para o seu exemplo no portal Azure.

Quando terminar, selecione o botão Guardar para criar a sua rota de evento.

Filtrar eventos

Como descrito acima, as rotas têm um campo de filtro. Se o valor do filtro na sua rota false for, não serão enviados eventos para o seu ponto final.

Depois de permitir o filtro mínimo true de, os pontos finais receberão uma variedade de eventos da Azure Digital Twins:

  • Telemetria disparada por gémeos digitais usando o serviço Azure Digital Twins API
  • Notificações de mudança de propriedade gémea, disparadas sobre alterações de propriedade para qualquer gémeo no caso Azure Digital Twins
  • Eventos de ciclo de vida, disparados quando gémeos ou relacionamentos são criados ou eliminados

Pode restringir os tipos de eventos que são enviados definindo um filtro mais específico.

Para adicionar um filtro de eventos enquanto está a criar uma rota de eventos, utilize a secção "Adicionar um filtro de rota de evento" da página Criar uma página de rota de evento.

Pode selecionar a partir de algumas opções básicas de filtro comum ou utilizar as opções avançadas de filtro para escrever os seus próprios filtros personalizados.

Nota

Os filtros são sensíveis ao caso e precisam de coincidir com a caixa de carga útil.

Para os filtros de telemetria, isto significa que o invólucro precisa de corresponder ao invólucro na telemetria enviada pelo dispositivo, e não necessariamente o invólucro definido no modelo do gémeo.

Use os filtros básicos

Para utilizar os filtros básicos, expanda a opção de tipos de Eventos e selecione as caixas de verificação correspondentes aos eventos que pretende enviar para o seu ponto final.

Screenshot de criar uma rota de eventos com um filtro básico no portal Azure, destacando as caixas de verificação dos eventos.

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

Screenshot de criar uma rota de eventos com um filtro básico no portal Azure, destacando o texto do filtro auto-povoado após a seleção dos eventos.

Use os filtros avançados

Em alternativa, pode utilizar a opção de filtro avançado para escrever os seus próprios filtros personalizados.

Para criar uma rota de eventos com opções avançadas de filtro, altere o interruptor para o editor Avançado para o ativar. Em seguida, pode escrever os seus próprios filtros de eventos na caixa filtro:

Screenshot de criar uma rota de eventos com um filtro avançado no portal Azure.

Aqui estão os filtros de rota suportados. O detalhe na coluna de esquema de texto do filtro é o texto que pode ser introduzido na caixa do filtro.

Nome do filtro Description Esquema de texto do filtro Valores suportados
Verdadeiro / Falso Permite criar uma rota sem filtragem, ou desativar uma rota para que nenhum evento sejam enviados <true/false> true = rota está ativada sem filtragem
false = rota é desativada
Tipo O tipo de evento que flui através da sua instância digital gémea type = '<event-type>' Aqui estão os possíveis valores do 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
Origem Nome da instância Azure Digital Twins source = '<host-name>' Aqui estão os possíveis valores do nome do anfitrião:
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 fonte do evento acima subject = '<subject>' Aqui estão os valores possíveis:
Para notificações: O assunto é <twin-ID>
ou um formato URI para sujeitos, que são identificados exclusivamente por múltiplas partes ou IDs:
<twin-ID>/relationships/<relationship-ID>
Para a telemetria: O sujeito é o caminho do componente (se a telemetria for emitida a partir de um componente gémeo), tais como comp1.comp2 . Se a telemetria não for emitida a partir de um componente, então o seu campo de objetos está vazio.
Esquema de dados ID modelo DTDL dataschema = '<model-dtmi-ID>' Para a telemetria: O esquema de dados é o ID do modelo do gémeo ou o componente que emite a telemetria. Por exemplo, dtmi:example:com:floor4;2
Para notificações (criar/excluir): O esquema de dados pode ser acedido no organismo de notificação em $body.$metadata.$model .
Para notificações (atualização): O esquema de dados pode ser acedido no organismo de notificação $body.modelId
Tipo do conteúdo Tipo de conteúdo do valor dos dados datacontenttype = '<content-type>' O tipo de conteúdo é application/json
Versão spec A versão do esquema de evento que está a usar specversion = '<version>' A versão deve 1.0 ser. Isto indica que o esquema do CloudEvents versão 1.0
Organismo de notificação Referenciar qualquer propriedade no data campo de uma notificação $body.<property> Ver Conceitos: Notificações de eventos para exemplos de notificações. Qualquer propriedade no data campo pode ser referenciada usando $body

Os seguintes tipos de dados são suportados como valores devolvidos 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
Rio Bool $body.poweredOn = true
Null $body.prop != null

Os seguintes operadores são suportados na definição de 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:

Função Descrição Exemplo
STARTS_WITH(x,y) Retorna verdadeira se o valor x começar com a cadeia y . STARTS_WITH($body.$metadata.$model, 'dtmi:example:com:floor')
ENDS_WITH(x,y) Retorna verdadeira se o valor x termina com a corda y . ENDS_WITH($body.$metadata.$model, 'floor;1')
CONTÉM (x,y) Retorna verdadeira se o valor x contiver a y cadeia. CONTAINS(subject, '<twin-ID>')

Quando implementar ou atualizar um filtro, a alteração pode demorar alguns minutos a ser refletida no pipeline de dados.

Monitorizar rotas de eventos

Métricas de encaminhamento como contagem, latência e taxa de insucesso podem ser vistas no portal Azure.

A partir da página inicial do portal, procure a sua instância Azure Digital Twins para obter os seus detalhes. Selecione a opção Métricas a partir do menu de navegação da instância Azure Digital Twins no lado esquerdo para trazer a página Métricas.

Screenshot mostrando a página de métricas para Azure Digital Twins.

A partir daqui, você pode ver as métricas para o seu exemplo e criar vistas personalizadas.

Para mais informações sobre a visualização das métricas Azure Digital Twins, consulte Como fazer: Ver métricas com o Azure Monitor.

Passos seguintes

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