Tutorial: Crie uma solução completa

Este tutorial do Azure Digital Twins descreve como criar uma solução de ponta a ponta que demonstra a funcionalidade do serviço. Para configurar uma solução completa de ponta a ponta orientada por dados em tempo real do seu ambiente, você pode conectar sua instância do Azure Digital Twins a outros serviços do Azure para gerenciamento de dispositivos e dados.

Neste tutorial, você irá...

• Configurar uma instância do Azure Digital Twins
• Saiba mais sobre o cenário de criação de exemplo e instancie os componentes pré-escritos
• Usar um aplicativo do Azure Functions para rotear telemetria simulada de um dispositivo do Hub IoT para propriedades de gêmeos digitais
• Propagar alterações através do gráfico gêmeo processando notificações de gêmeos digitais com o Azure Functions, pontos de extremidade e rotas

Pré-requisitos

Antes de começar este tutorial, comece com estes pré-requisitos:

• Se não tiver uma subscrição do Azure, crie uma conta gratuita antes de começar.
• Este tutorial usa o .NET. Você pode baixar a versão mais recente do SDK do .NET para várias plataformas em Download .NET.

Em seguida, continue pelo restante desta seção para configurar os pré-requisitos restantes.

Obter recursos de exemplo

O tutorial é conduzido por um projeto de exemplo de ponta a ponta do Azure Digital Twins escrito em C#. Obtenha o projeto de exemplo em sua máquina navegando até o link de exemplo e selecionando o botão Procurar código abaixo do título.

Isso levará você ao repositório GitHub para as amostras, que você pode baixar como um .zip selecionando o botão Código seguido de Baixar ZIP.

Isso fará o download de uma pasta .zip para sua máquina como digital-twins-samples-main.zip. Descompacte a pasta e extraia os arquivos.

Preparar uma instância do Azure Digital Twins

Para trabalhar com Gêmeos Digitais do Azure neste artigo, você precisará de uma instância de Gêmeos Digitais do Azure e as permissões necessárias para usá-la. Se você já tiver uma instância do Azure Digital Twins configurada, poderá usar essa instância e pular para a próxima seção. Caso contrário, siga as instruções em Configurar uma instância e autenticação. As instruções contêm informações para ajudá-lo a verificar se você concluiu cada etapa com êxito.

Depois de configurar sua instância, anote o nome do host da instância. Você pode encontrar o nome do host no portal do Azure.

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.

Configurar sessão CLI

Para começar a trabalhar com os Gêmeos Digitais do Azure na CLI, a primeira coisa a fazer é fazer logon e definir o contexto da CLI para sua assinatura para esta sessão. Execute estes comandos na janela da CLI:

az login
az account set --subscription "<your-Azure-subscription-ID>"

Gorjeta

Também pode utilizar o nome da sua subscrição em vez do ID no comando acima.

Se esta for a primeira vez que você usa essa assinatura com os Gêmeos Digitais do Azure, execute este comando para se registrar com o namespace Gêmeos Digitais do Azure. (Se você não tiver certeza, não há problema em executá-lo novamente, mesmo que você já tenha feito isso em algum momento no passado.)

az provider register --namespace 'Microsoft.DigitalTwins'

Em seguida, você adicionará a Extensão IoT do Microsoft Azure para CLI do Azure para habilitar comandos para interagir com Gêmeos Digitais do Azure e outros serviços de IoT. Execute este comando para se certificar de que tem a versão mais recente da extensão:

az extension add --upgrade --name azure-iot

Agora você está pronto para trabalhar com os Gêmeos Digitais do Azure na CLI do Azure.

Você pode verificar isso executando az dt --help a qualquer momento para ver uma lista dos comandos de nível superior do Azure Digital Twins que estão disponíveis.

Configurar o projeto de exemplo

Em seguida, configure um aplicativo cliente de exemplo que interagirá com sua instância do Azure Digital Twins.

Navegue em sua máquina até a pasta que você baixou anteriormente dos exemplos de ponta a ponta do Azure Digital Twins (e descompacte-a se ainda não tiver feito).

Uma vez dentro da pasta, navegue até digital-twins-samples-main\AdtSampleApp\SampleClientApp e abra o arquivo appsettings.json . Este arquivo JSON contém uma variável de configuração que é necessária para executar o projeto.

No corpo do arquivo, altere a instanceUrl URL do nome do host da instância do Azure Digital Twins (adicionando https:// na frente do nome do host, conforme mostrado abaixo).

{
  "instanceUrl": "https://<your-Azure-Digital-Twins-instance-host-name>"
}

Guarde e feche o ficheiro.

Configurar credenciais locais do Azure

Este exemplo usa DefaultAzureCredential (parte da Azure.Identity biblioteca) para autenticar usuários com a instância do Azure Digital Twins quando você a executa em sua máquina local. Para obter mais informações sobre diferentes maneiras pelas quais um aplicativo cliente pode se autenticar com Gêmeos Digitais do Azure, consulte Escrever código de autenticação de aplicativo.

Com DefaultAzureCredentialo , o exemplo procurará credenciais em seu ambiente local, como uma entrada do Azure em uma CLI do Azure local ou no Visual Studio ou Visual Studio Code. Por esse motivo, você deve entrar no Azure localmente por meio de um desses mecanismos para configurar credenciais para o exemplo.

Se estiver a utilizar o Visual Studio ou o Visual Studio Code para executar exemplos de código, certifique-se de que tem sessão iniciada nesse editor com as mesmas credenciais do Azure que pretende utilizar para aceder à sua instância do Azure Digital Twins. Se você estiver usando uma janela de CLI local, execute o az login comando para entrar em sua conta do Azure. Depois disso, quando você executa seu exemplo de código, você deve ser autenticado automaticamente.

Introdução ao cenário de construção

O projeto de exemplo usado neste tutorial representa um cenário de construção do mundo real, contendo um piso, uma sala e um dispositivo de termostato. Esses componentes serão representados digitalmente em uma instância do Azure Digital Twins, que será conectada ao Hub IoT, à Grade de Eventos e a duas funções do Azure para habilitar a movimentação de dados.

Abaixo está um diagrama que representa o cenário completo.

Primeiro, você criará a instância dos Gêmeos Digitais do Azure (seção A no diagrama), depois configurará o fluxo de dados de telemetria do dispositivo para os gêmeos digitais (seta B) e, em seguida, configurará a propagação de dados por meio do gráfico de gêmeos (seta C).

Para trabalhar no cenário, você interagirá com componentes do aplicativo de exemplo pré-escrito baixado anteriormente.

Aqui estão os componentes implementados pelo aplicativo de exemplo AdtSampleApp do cenário de construção:

• Autenticação do dispositivo
• Exemplos de uso do SDK .NET (C#) ( encontrados em CommandLoop.cs)
• Interface de console para chamar a API do Azure Digital Twins
• SampleClientApp - Uma solução de exemplo do Azure Digital Twins
• SampleFunctionsApp - Um aplicativo do Azure Functions que atualiza seu gráfico do Azure Digital Twins com base na telemetria do dispositivo dos eventos do Hub IoT e do Azure Digital Twins

Instanciar o gráfico gêmeo pré-criado

Primeiro, você usará a solução AdtSampleApp do projeto de exemplo para criar a parte dos Gêmeos Digitais do Azure do cenário de ponta a ponta (seção A):

Abra uma janela do console local e navegue até a pasta digital-twins-samples-main\AdtSampleApp\SampleClientApp. Execute o projeto SampleClientApp com este comando dotnet:

dotnet run

O projeto começará a ser executado, executará a autenticação e aguardará um comando. Neste console, execute o próximo comando para instanciar a solução de exemplo Azure Digital Twins.

Importante

Se você já tiver gêmeos digitais e relacionamentos em sua instância de Gêmeos Digitais do Azure, executar este comando os excluirá e os substituirá pelos gêmeos e relacionamentos para o cenário de exemplo.

SetupBuildingScenario

A saída deste comando é uma série de mensagens de confirmação à medida que três gêmeos digitais são criados e conectados em sua instância de Gêmeos Digitais do Azure: um andar chamado floor1, uma sala chamada room21 e um sensor de temperatura chamado termostato67. Esses gêmeos digitais representam as entidades que existiriam em um ambiente do mundo real.

Eles são conectados através de relacionamentos no gráfico gêmeo a seguir. O gráfico gêmeo representa o ambiente como um todo, incluindo como as entidades interagem e se relacionam entre si.

Você pode verificar os gêmeos que foram criados executando o seguinte comando, que consulta a instância de Gêmeos Digitais do Azure conectada para todos os gêmeos digitais que ela contém:

Query

Agora você pode parar de executar o projeto. No entanto, mantenha a janela do console aberta neste local, pois você usará esse aplicativo novamente mais tarde no tutorial.

Configurar o aplicativo de função de exemplo

A próxima etapa é configurar um aplicativo do Azure Functions que será usado ao longo deste tutorial para processar dados. O aplicativo de função, SampleFunctionsApp, contém duas funções:

• ProcessHubToDTEvents: processa dados de entrada do Hub IoT e atualiza os Gêmeos Digitais do Azure de acordo
• ProcessDTRoutedData: processa dados de gêmeos digitais e atualiza os gêmeos pais nos Gêmeos Digitais do Azure de acordo

Nesta seção, você publicará o aplicativo de função pré-escrito e garantirá que o aplicativo de função possa acessar os Gêmeos Digitais do Azure atribuindo-lhe uma identidade do Microsoft Entra.

O aplicativo de função faz parte do projeto de exemplo que você baixou, localizado na pasta digital-twins-samples-main\AdtSampleApp\SampleFunctionsApp .

Publicar a aplicação

Para publicar o aplicativo de função no Azure, você precisará criar uma conta de armazenamento, criar o aplicativo de função no Azure e, finalmente, publicar as funções no aplicativo de função do Azure. Esta seção conclui essas ações usando a CLI do Azure. Em cada comando, substitua todos os espaços reservados entre colchetes angulares pelos detalhes dos seus próprios recursos.

1. Crie uma conta de armazenamento do Azure executando o seguinte comando:

   az storage account create --name <name-for-new-storage-account> --location <location> --resource-group <resource-group> --sku Standard_LRS
   

2. Crie um aplicativo de função do Azure executando o seguinte comando:

   az functionapp create --name <name-for-new-function-app> --storage-account <name-of-storage-account-from-previous-step> --functions-version 4 --consumption-plan-location <location> --runtime dotnet-isolated --resource-group <resource-group>
   

3. Em seguida, você compactará as funções e as publicará em seu novo aplicativo de função do Azure.

   1. Abra uma janela de console em sua máquina (se você estiver usando a CLI do Azure local, pode ser a mesma janela) e navegue até a pasta digital-twins-samples-main\AdtSampleApp\SampleFunctionsApp dentro do seu projeto de exemplo baixado.

   2. No console, execute o seguinte comando para publicar o projeto localmente:

      dotnet publish -c Release -o publish
      

      Este comando publica o projeto no diretório digital-twins-samples-main\AdtSampleApp\SampleFunctionsApp\publishing .

   3. Usando seu método preferido, crie um zip dos arquivos publicados que estão localizados dentro do diretório digital-twins-samples-main\AdtSampleApp\SampleFunctionsApp\publishing . Nomeie a pasta compactada publish.zip.

      Importante

      Verifique se a pasta compactada não inclui uma camada extra para a própria pasta de publicação . Ele deve conter apenas o conteúdo que estava dentro da pasta de publicação .

      Aqui está uma imagem de como o conteúdo zip pode parecer (pode mudar dependendo da sua versão do .NET).

      

   A última etapa será feita na CLI do Azure.

4. Na CLI do Azure, execute o seguinte comando para implantar as funções publicadas e compactadas em seu aplicativo de função do Azure:

   az functionapp deployment source config-zip --resource-group <resource-group> --name <name-of-your-function-app> --src "<full-path-to-publish.zip>"
   

   Gorjeta

   Se você estiver usando a CLI do Azure localmente, poderá acessar o arquivo ZIP em seu computador diretamente usando seu caminho em sua máquina.

   Se você estiver usando o Azure Cloud Shell, carregue o arquivo ZIP no Cloud Shell com este botão antes de executar o comando:

   

   Nesse caso, o arquivo será carregado para o diretório raiz do seu armazenamento do Cloud Shell, para que você possa se referir ao arquivo diretamente pelo seu nome para o --src parâmetro do comando (como em, --src publish.zip).

   Uma implantação bem-sucedida responderá com o código de status 202 e produzirá um objeto JSON contendo detalhes de sua nova função. Você pode confirmar a implantação bem-sucedida procurando este campo no resultado:

   "provisioningState": "Succeeded",
   

As funções agora devem ser publicadas em um aplicativo de função no Azure. Você pode usar os seguintes comandos da CLI para verificar se ambas as funções foram publicadas com êxito. Cada comando tem espaços reservados para seu grupo de recursos e o nome do seu aplicativo de função. Os comandos imprimirão informações sobre as funções ProcessDTRoutedData e ProcessHubToDTEvents que foram publicadas.

az functionapp function show --resource-group <your-resource-group> --name <your-function-app> --function-name ProcessDTRoutedData
az functionapp function show --resource-group <your-resource-group> --name <your-function-app> --function-name ProcessHubToDTEvents

Em seguida, seu aplicativo de função precisará ter a permissão certa para acessar sua instância do Azure Digital Twins. Você configurará esse acesso na próxima seção.

Configurar permissões para o aplicativo de função

Há duas configurações que precisam ser definidas para que o aplicativo de função acesse sua instância do Azure Digital Twins, ambas podem ser feitas usando a CLI do Azure.

Atribuir função de acesso

A primeira configuração dá ao aplicativo de função a função Proprietário de Dados dos Gêmeos Digitais do Azure na instância dos Gêmeos Digitais do Azure. Essa função é necessária para qualquer usuário ou função que queira executar muitas atividades do plano de dados na instância. Você pode ler mais sobre segurança e atribuições de função em Segurança para soluções de Gêmeos Digitais do Azure.

1. Use o comando a seguir para criar uma identidade atribuída ao sistema para a função. A saída exibirá detalhes da identidade que foi criada. Anote o campo principalId na saída a ser usado na próxima etapa.

   az functionapp identity assign --resource-group <your-resource-group> --name <your-function-app-name>
   

2. Utilize o valor principalId no seguinte comando para atribuir a identidade da aplicação de funções à função Proprietário dos Dados do Azure Digital Twins para a sua instância do Azure Digital Twins.

   az dt role-assignment create --resource-group <your-resource-group> --dt-name <your-Azure-Digital-Twins-instance> --assignee "<principal-ID>" --role "Azure Digital Twins Data Owner"
   

O resultado desse comando são informações geradas sobre a atribuição de função que você criou. O aplicativo de função agora tem permissões para acessar dados em sua instância do Azure Digital Twins.

Definir configuração do aplicativo

A segunda configuração cria uma variável de ambiente para a função com a URL da sua instância do Azure Digital Twins. O código da função usará o valor dessa variável para se referir à sua instância. Para obter mais informações sobre variáveis de ambiente, consulte Gerenciar seu aplicativo de função.

Execute o comando abaixo, preenchendo os espaços reservados com os detalhes dos seus recursos.

az functionapp config appsettings set --resource-group <your-resource-group> --name <your-function-app-name> --settings "ADT_SERVICE_URL=https://<your-Azure-Digital-Twins-instance-host-name>"

A saída é a lista de configurações para a Função do Azure, que agora deve conter uma entrada chamada ADT_SERVICE_URL.

Telemetria simulada de processo a partir de um dispositivo Hub IoT

Um gráfico de Gêmeos Digitais do Azure deve ser acionado por telemetria de dispositivos reais.

Nesta etapa, você conectará um dispositivo de termostato simulado registrado no Hub IoT ao gêmeo digital que o representa nos Gêmeos Digitais do Azure. À medida que o dispositivo simulado emite telemetria, os dados serão direcionados por meio da função ProcessHubToDTEvents Azure que dispara uma atualização correspondente no gêmeo digital. Desta forma, o gémeo digital mantém-se atualizado com os dados reais do dispositivo. Nos Gêmeos Digitais do Azure, o processo de direcionar dados de eventos de um local para outro é chamado de eventos de roteamento.

O processamento da telemetria simulada acontece nesta parte do cenário de ponta a ponta (seta B):

Aqui estão as ações que você concluirá para configurar essa conexão de dispositivo:

1. Crie um hub IoT que gerenciará o dispositivo simulado
2. Conecte o hub IoT à função apropriada do Azure configurando uma assinatura de evento
3. Registrar o dispositivo simulado no hub IoT
4. Execute o dispositivo simulado e gere telemetria
5. Consulte os Gêmeos Digitais do Azure para ver os resultados ao vivo

Criar uma instância do Hub IoT

Os Gêmeos Digitais do Azure foram projetados para trabalhar ao lado do Hub IoT, um serviço do Azure para gerenciar dispositivos e seus dados. Nesta etapa, você configurará um hub IoT que gerenciará o dispositivo de exemplo neste tutorial.

Na CLI do Azure, use este comando para criar um novo hub IoT:

az iot hub create --name <name-for-your-IoT-hub> --resource-group <your-resource-group> --sku S1

A saída desse comando são informações sobre o hub IoT que foi criado.

Salve o nome que você deu ao seu hub IoT. Vai utilizá-lo mais tarde.

Conectar o hub IoT à função do Azure

Em seguida, conecte seu hub IoT à função ProcessHubToDTEvents Azure no aplicativo de função que você publicou anteriormente, para que os dados possam fluir do dispositivo no Hub IoT por meio da função, que atualiza os Gêmeos Digitais do Azure.

Para fazer isso, você criará uma assinatura de evento em seu Hub IoT, com a função do Azure como um ponto de extremidade. Isso "inscreve" a função para eventos que acontecem no Hub IoT.

Use o seguinte comando da CLI para criar a assinatura do evento. Há um espaço reservado para você inserir um nome para a assinatura do evento e também há espaços reservados para você inserir sua ID de assinatura, grupo de recursos, nome do hub IoT e o nome do seu aplicativo de função.

az eventgrid event-subscription create --name <name-for-hub-event-subscription> --event-delivery-schema eventgridschema --source-resource-id /subscriptions/<your-subscription-ID>/resourceGroups/<your-resource-group>/providers/Microsoft.Devices/IotHubs/<your-IoT-hub> --included-event-types Microsoft.Devices.DeviceTelemetry --endpoint-type azurefunction --endpoint /subscriptions/<your-subscription-ID>/resourceGroups/<your-resource-group>/providers/Microsoft.Web/sites/<your-function-app>/functions/ProcessHubToDTEvents

A saída mostrará informações sobre a assinatura de evento que foi criada. Você pode confirmar que a operação foi concluída com êxito verificando o provisioningState valor no resultado:

"provisioningState": "Succeeded",

Gorjeta

Se o comando retornar um erro do provedor de recursos, adicione Microsoft.EventGrid como um provedor de recursos à sua assinatura. Você pode fazer isso no portal do Azure seguindo as instruções em Registrar provedor de recursos.

Registrar o dispositivo simulado com o Hub IoT

Esta seção cria uma representação de dispositivo no Hub IoT com o termostato de ID67. O dispositivo simulado se conectará a essa representação, que é como os eventos de telemetria passarão do dispositivo para o Hub IoT. O hub IoT é onde a função do Azure inscrita na etapa anterior está ouvindo, pronta para pegar os eventos e continuar o processamento.

Na CLI do Azure, crie um dispositivo no Hub IoT com o seguinte comando:

az iot hub device-identity create --device-id thermostat67 --hub-name <your-IoT-hub-name> --resource-group <your-resource-group>

A saída é informações sobre o dispositivo que foi criado.

Configurar e executar a simulação

Importante

Este artigo inclui etapas para conectar um dispositivo usando uma assinatura de acesso compartilhado, também chamada de autenticação de chave simétrica. Esse método de autenticação é conveniente para testes e avaliações, mas autenticar um dispositivo usando certificados X.509 é uma abordagem mais segura. Para saber mais, consulte Práticas > recomendadas de segurança Segurança de conexão.

Em seguida, configure o simulador de dispositivos para enviar dados para a instância do Hub IoT.

Comece obtendo a cadeia de conexão do hub IoT com o comando a seguir. O valor da cadeia de conexão começará com HostName=.

az iot hub connection-string show --hub-name <your-IoT-hub-name>

Em seguida, obtenha a cadeia de ligação de dispositivo com este comando:

az iot hub device-identity connection-string show --device-id thermostat67 --hub-name <your-IoT-hub-name>

Em seguida, conecte esses valores ao código do simulador de dispositivo em seu projeto local para conectar o simulador a esse hub IoT e dispositivo de hub IoT.

Navegue em sua máquina local até a pasta de exemplo baixada e para a pasta digital-twins-samples-main\DeviceSimulator\DeviceSimulator . Abra o arquivo de AzureIoTHub.cs para edição. Altere os seguintes valores de cadeia de conexão para os valores coletados acima:

private const string iotHubConnectionString = "<your-hub-connection-string>";
//...
private const string deviceConnectionString = "<your-device-connection-string>";

Guarde o ficheiro.

Agora, para ver os resultados da simulação de dados que você configurou, abra uma nova janela do console local e navegue até digital-twins-samples-main\DeviceSimulator\DeviceSimulator.

Nota

Agora você deve ter duas janelas de console abertas: uma que está aberta para a pasta DeviceSimulator\DeviceSimulator e uma anterior que ainda está aberta para a pasta AdtSampleApp\SampleClientApp .

Use o seguinte comando dotnet para executar o projeto de simulador de dispositivo:

dotnet run

O projeto começará a ser executado e começará a exibir mensagens simuladas de telemetria de temperatura. Essas mensagens estão sendo enviadas para o Hub IoT, onde são coletadas e processadas pela função do Azure.

Você não precisa fazer mais nada neste console, mas deixá-lo em execução enquanto conclui as próximas etapas.

Veja os resultados em Gêmeos Digitais do Azure

A função ProcessHubToDTEvents que você publicou anteriormente ouve os dados do Hub IoT e chama uma API de Gêmeos Digitais do Azure para atualizar a Temperature propriedade no gêmeo termostato67.

Para ver os dados do lado dos Gêmeos Digitais do Azure, alterne para a outra janela do console aberta para a pasta AdtSampleApp\SampleClientApp . Execute o projeto SampleClientApp com dotnet runo .

dotnet run

Quando o projeto estiver em execução e aceitar comandos, execute o seguinte comando para obter as temperaturas que estão sendo relatadas pelo termostato gêmeo digital67:

ObserveProperties thermostat67 Temperature

Você deve ver as temperaturas atualizadas ao vivo da sua instância do Azure Digital Twins sendo registradas no console a cada dois segundos. Eles devem refletir os valores que o simulador de dados está gerando (você pode colocar as janelas do console lado a lado para verificar se os valores se coordenam).

Nota

Pode levar alguns segundos para que os dados do dispositivo se propaguem para o gêmeo. As primeiras leituras de temperatura podem aparecer como 0 antes que os dados comecem a chegar.

Depois de verificar se o registro de temperatura ao vivo está funcionando com êxito, você pode parar de executar ambos os projetos. Mantenha as janelas do console abertas, pois você as usará novamente mais adiante no tutorial.

Propagar eventos do Azure Digital Twins através do gráfico

Até agora, neste tutorial, você viu como os Gêmeos Digitais do Azure podem ser atualizados a partir de dados de dispositivos externos. Em seguida, você verá como as alterações em um gêmeo digital podem se propagar por meio do gráfico de Gêmeos Digitais do Azure — em outras palavras, como atualizar gêmeos a partir de dados internos do serviço.

Para fazer isso, você usará a função do Azure ProcessDTRoutedData para atualizar um gêmeo de sala quando o gêmeo termostato conectado for atualizado. A funcionalidade de atualização acontece nesta parte do cenário de ponta a ponta (seta C):

Aqui estão as ações que você concluirá para configurar esse fluxo de dados:

1. Criar um tópico de Grade de Eventos para habilitar a movimentação de dados entre os serviços do Azure
2. Criar um ponto de extremidade no Azure Digital Twins que conecta a instância ao tópico Grade de Eventos
3. Configurar uma rota nos Gêmeos Digitais do Azure que envia eventos de alteração de propriedade gêmea para o ponto de extremidade
4. Configure uma função do Azure que escuta o tópico Grade de Eventos no ponto de extremidade, recebe os eventos de alteração de propriedade gêmeos que são enviados para lá e atualiza outros gêmeos no gráfico de acordo

Criar o tópico Grade de Eventos

A Grade de Eventos é um serviço do Azure que ajuda a rotear e entregar eventos dos serviços do Azure para outros locais no Azure. Você pode criar um tópico de Grade de Eventos para coletar determinados eventos de uma fonte e, em seguida, os assinantes podem ouvir o tópico para receber os eventos à medida que eles aparecem.

Na CLI do Azure, execute o seguinte comando para criar um tópico de Grade de Eventos:

az eventgrid topic create --resource-group <your-resource-group> --name <name-for-your-event-grid-topic> --location <region>

A saída deste comando é informações sobre o tópico Grade de Eventos que você criou. Salve o nome que você deu ao seu tópico Grade de Eventos, pois você o usará mais tarde.

Criar o ponto de extremidade

Em seguida, crie um ponto de extremidade de Grade de Eventos no Azure Digital Twins, que conectará sua instância ao tópico Grade de Eventos. Use o comando abaixo, preenchendo o nome do tópico da Grade de Eventos da etapa anterior e os outros campos de espaço reservado, conforme necessário.

az dt endpoint create eventgrid --dt-name <Azure-Digital-Twins-instance> --eventgrid-resource-group <your-resource-group> --eventgrid-topic <your-event-grid-topic> --endpoint-name <name-for-your-Azure-Digital-Twins-endpoint>

A saída deste comando é informações sobre o ponto de extremidade que você criou.

Procure o provisioningState campo na saída e verifique se o valor é "Êxito".

Ele também pode dizer "Provisionamento", o que significa que o ponto de extremidade ainda está sendo criado. Em caso afirmativo, aguarde alguns segundos e execute o seguinte comando para verificar o status do ponto de extremidade. Repita até que os provisioningState shows "Succeeded".

az dt endpoint show --dt-name <your-Azure-Digital-Twins-instance> --endpoint-name <your-Azure-Digital-Twins-endpoint> 

Salve o nome do seu ponto de extremidade, porque você o usará mais tarde.

Criar a rota

Em seguida, crie uma rota de Gêmeos Digitais do Azure que envie eventos para o ponto de extremidade da Grade de Eventos que você criou.

Use o seguinte comando da CLI, preenchendo o nome do seu ponto de extremidade da etapa anterior e os outros campos de espaço reservado conforme necessário. Este comando encaminha todos os eventos que ocorrem no gráfico gêmeo.

Gorjeta

Você pode limitar os eventos a apenas eventos específicos, se desejar, usando filtros.

az dt route create --dt-name <your-Azure-Digital-Twins-instance> --endpoint-name <your-Azure-Digital-Twins-endpoint> --route-name <name-for-your-Azure-Digital-Twins-route>

A saída deste comando é algumas informações sobre a rota que você criou.

Nota

Os pontos de extremidade (da etapa anterior) devem ser concluídos antes que você possa configurar uma rota de evento que os use. Se a criação da rota falhar porque os pontos de extremidade não estão prontos, aguarde alguns minutos e tente novamente.

Conectar a função do Azure

Em seguida, inscreva a função ProcessDTRoutedData Azure no tópico Grade de Eventos criado anteriormente, para que os dados de telemetria possam fluir do gêmeo termostato67 através do tópico Grade de Eventos para a função, que volta para os Gêmeos Digitais do Azure e atualiza o gêmeo room21 de acordo.

Para fazer isso, você criará uma assinatura de Grade de Eventos que envia dados do tópico Grade de Eventos criado anteriormente para sua função do Azure ProcessDTRoutedData .

Use o seguinte comando da CLI para criar a assinatura do evento. Há um espaço reservado para você inserir um nome para essa assinatura de evento e também há espaços reservados para você inserir sua ID de assinatura, grupo de recursos, o nome do tópico Grade de Eventos e o nome do aplicativo de função.

az eventgrid event-subscription create --name <name-for-topic-event-subscription> --event-delivery-schema eventgridschema --source-resource-id /subscriptions/<your-subscription-ID>/resourceGroups/<your-resource-group>/providers/Microsoft.EventGrid/topics/<your-event-grid-topic> --endpoint-type azurefunction --endpoint /subscriptions/<your-subscription-ID>/resourceGroups/<your-resource-group>/providers/Microsoft.Web/sites/<your-function-app>/functions/ProcessDTRoutedData

Execute a simulação e veja os resultados

Agora, os eventos devem ter a capacidade de fluir do dispositivo simulado para os Gêmeos Digitais do Azure e, por meio do gráfico dos Gêmeos Digitais do Azure, atualizar os gêmeos conforme apropriado. Nesta seção, você executará o simulador de dispositivo novamente para iniciar o fluxo de eventos completo que configurou e consultará os Gêmeos Digitais do Azure para ver os resultados ao vivo

Vá para a janela do console que está aberta para a pasta DeviceSimulator\DeviceSimulator e execute o projeto de simulador de dispositivo com dotnet run.

Como na primeira vez que você executou o simulador de dispositivo, o projeto começará a ser executado e exibirá mensagens simuladas de telemetria de temperatura. Esses eventos estão passando pelo fluxo que você configurou anteriormente para atualizar o termostato gêmeo 67 e, em seguida, passando pelo fluxo que você configurou recentemente para atualizar o gêmeo room21 para corresponder.

Você não precisa fazer mais nada neste console, mas deixá-lo em execução enquanto conclui as próximas etapas.

Para ver os dados do lado dos Gêmeos Digitais do Azure, vá para a outra janela do console aberta para a pasta AdtSampleApp\SampleClientApp e execute o projeto SampleClientApp com dotnet run.

Quando o projeto estiver em execução e aceitar comandos, execute o seguinte comando para obter as temperaturas que estão sendo relatadas pelo termostato de gêmeos digitais67 e pela sala de gêmeos digitais21.

ObserveProperties thermostat67 Temperature room21 Temperature

Você deve ver as temperaturas atualizadas ao vivo da sua instância do Azure Digital Twins sendo registradas no console a cada dois segundos. Observe que a temperatura da sala21 está sendo atualizada para corresponder às atualizações do termostato67.

Depois de verificar se o registro de temperaturas em tempo real da sua instância está funcionando com êxito, você pode parar de executar ambos os projetos. Você também pode fechar ambas as janelas do console, pois o tutorial está concluído.

Rever

Aqui está uma revisão do cenário que você criou neste tutorial.

1. Uma instância do Azure Digital Twins representa digitalmente um andar, uma sala e um termostato (representado pela seção A no diagrama abaixo)
2. A telemetria de dispositivo simulada é enviada para o Hub IoT, onde a função ProcessHubToDTEvents do Azure está escutando eventos de telemetria. A função do Azure ProcessHubToDTEvents usa as informações nesses eventos para definir a Temperature propriedade no termostato67 (seta B no diagrama).
3. Os eventos de alteração de propriedade nos Gêmeos Digitais do Azure são roteados para um tópico da Grade de Eventos, onde a função ProcessDTRoutedData do Azure está escutando eventos. A função ProcessDTRoutedData do Azure usa as informações nesses eventos para definir a Temperature propriedade na sala21 (seta C no diagrama).

Clean up resources (Limpar recursos)

Depois de concluir este tutorial, você pode escolher quais recursos deseja remover, dependendo do que deseja fazer em seguida.

• Se você não precisar de nenhum dos recursos criados neste tutorial, poderá excluir a instância do Azure Digital Twins e todos os outros recursos deste artigo com o comando az group delete CLI. Isso exclui todos os recursos do Azure em um grupo de recursos, bem como o próprio grupo de recursos.

  Importante

  A eliminação de um grupo de recursos é irreversível. O grupo de recursos e todos os recursos nele contidos são eliminados permanentemente. Confirme que não elimina acidentalmente o grupo de recursos ou recursos errados.

  Abra o Azure Cloud Shell ou uma janela da CLI local e execute o seguinte comando para excluir o grupo de recursos e tudo o que ele contém.

  az group delete --name <your-resource-group>
  

• Se quiser continuar usando a instância do Azure Digital Twins configurada neste artigo, mas limpar alguns ou todos os seus modelos, gêmeos e relacionamentos, você pode usar os comandos az dt CLI para excluir os elementos que deseja remover.

  Essa opção não removerá nenhum dos outros recursos do Azure criados neste tutorial (Hub IoT, aplicativo Azure Functions e assim por diante). Você pode excluí-los individualmente usando os comandos dt apropriados para cada tipo de recurso.

Você também pode querer excluir a pasta do projeto de sua máquina local.

Próximos passos

Neste tutorial, você criou um cenário de ponta a ponta que mostra os Gêmeos Digitais do Azure sendo conduzidos por dados de dispositivo em tempo real.

Em seguida, comece a examinar a documentação do conceito para saber mais sobre os elementos com os quais você trabalhou no tutorial:

Modelos à medida