Tutorial: Criar uma solução de ponta a ponta
Este tutorial dos Gêmeos Digitais do Azure descreve como criar uma solução de ponta a ponta que demonstra a funcionalidade do serviço. Para configurar uma solução de ponta a ponta completa baseada em dados dinâmicos de seu ambiente, você pode conectar sua instância dos Gêmeos Digitais do Azure a outros serviços do Azure para o gerenciamento de dispositivos e de dados.
Neste tutorial, você vai...
- Configurar uma instância dos Gêmeos Digitais do Azure
- Aprender sobre o cenário de criação de exemplo e criar instâncias dos componentes pré-gravados
- Usar um aplicativo do Azure Functions para rotear a telemetria simulada de um dispositivo do Hub IoT para propriedades dos gêmeos digitais
- Propagar alterações por meio do gráfico gêmeo, processando notificações dos gêmeos digitais com o Azure Functions, pontos de extremidade e rotas
Pré-requisitos
Antes de iniciar este tutorial, comece com estes pré-requisitos:
- Se você não tiver uma assinatura do Azure, crie uma conta gratuita antes de começar.
- Este tutorial usa .NET. Baixe esta versão do SDK do .NET Core para várias plataformas em Baixar o .NET.
Em seguida, prossiga com o restante desta seção para configurar os pré-requisitos que faltam.
Obter exemplos de recursos
O tutorial é controlado por um projeto de amostra de ponta a ponta dos Gêmeos Digitais do Azure escrito em C#. Obtenha um projeto de exemplo em seu computador acessando o link de exemplo e clicando no botão Procurar códigos abaixo do título.
Isso levará você ao repositório do GitHub para obter exemplos que poderão ser baixados como um .zip clicando no botão Código e em Baixar ZIP.
Isso baixará uma pasta .zip chamada digital-twins-samples-main.zip no computador. Descompacte a pasta e extraia os arquivos.
Preparar uma instância dos Gêmeos Digitais do Azure
Para trabalhar com os Gêmeos Digitais do Azure neste artigo, você precisará ter uma instância dos Gêmeos Digitais do Azure e as permissões necessárias para usá-la. Se você já tiver uma instância dos Gêmeos Digitais do Azure configurada, use essa instância e vá direto para a próxima seção. Caso contrário, siga as instruções descritas em Configurar uma instância e uma autenticação. As instruções contêm informações que ajudarão você a verificar se cada etapa foi concluída com êxito.
Após configurar a instância, anote o nome do host da instância. Encontre o nome do host no portal do Azure.
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.
Configurar sessão da CLI
Para começar a trabalhar com os Gêmeos Digitais do Azure na CLI, faça logon e defina o contexto da CLI da sua assinatura para esta sessão. Execute estes comandos na janela da CLI:
az login
az account set --subscription "<your-Azure-subscription-ID>"
Dica
Você também pode usar o nome da sua assinatura em vez da ID no comando acima.
Se esta é a primeira vez que você usa essa assinatura com os Gêmeos Digitais do Azure, execute este comando para se registrar no namespace dos Gêmeos Digitais do Azure. (Se você não tiver certeza disso, não haverá problemas em executá-lo novamente mesmo que já tenha feito isso no passado.)
az provider register --namespace 'Microsoft.DigitalTwins'
Em seguida, você adicionará a Extensão de IoT do Microsoft Azure para a CLI do Azure para habilitar comandos para interagir com os Gêmeos Digitais do Azure e com outros serviços de IoT. Execute este comando para verificar se você tem a última versão 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.
É possível verificar isso executando az dt --help a qualquer momento para ver uma lista dos comandos dos Gêmeos Digitais do Azure de nível superior que estão disponíveis.
Configurar o projeto de exemplo
A seguir, configure um aplicativo cliente de exemplo que vai interagir com sua instância dos Gêmeos Digitais do Azure.
Navegue no computador até a pasta baixada anteriormente de Amostras de ponta a ponta dos Gêmeos Digitais do Azure (e descompacte-o se ainda não tiver feito isso).
Após entrar na pasta, navegue até digital-twins-samples-main\AdtSampleApp\SampleClientApp e abra o arquivo appsettings.json. Esse arquivo JSON contém uma variável de configuração necessária para executar o projeto.
No corpo do arquivo, altere o instanceUrl para a URL do nome do host da sua instância dos Gêmeos Digitais do Azure (adicionando https://na frente do nome do host, conforme mostrado abaixo).
{
"instanceUrl": "https://<your-Azure-Digital-Twins-instance-host-name>"
}
Salve e feche o arquivo.
Configurar credenciais locais do Azure
Quando você o executa em seu computador local, este exemplo usa o DefaultAzureCredential (parte da biblioteca Azure.Identity) para autenticar usuários com uma instância dos Gêmeos Digitais do Azure. Para obter mais informações sobre as diferentes maneiras como um aplicativo cliente pode se autenticar com os Gêmeos Digitais do Azure, confira Escrever o código de autenticação do aplicativo.
Com DefaultAzureCredential, o exemplo pesquisará as credenciais no ambiente local, como uma conexão do Azure em uma DefaultAzureCredential local ou no Visual Studio ou Visual Studio Code. Por isso, será necessário entrar no Azure localmente por meio de um desses mecanismos para configurar as credenciais do exemplo.
Caso esteja usando o Visual Studio ou o Visual Studio Code para executar exemplos de código, verifique se está conectado a esse editor com as mesmas credenciais do Azure que deseja usar para acessar a instância dos Gêmeos Digitais do Azure. Se estiver usando uma janela da CLI local, execute o comando az login para entrar na sua conta do Azure. Depois disso, quando você executar o exemplo de código, será autenticado automaticamente.
Introdução ao cenário de criação
O projeto de exemplo usado neste tutorial representa um cenário de construção do mundo real, que contém um andar, uma sala e um dispositivo de termostato. Esses componentes serão representados digitalmente em uma instância dos Gêmeos Digitais do Azure que será conectada ao Hub IoT, à Grade de Eventos e a duas funções do Azure para habilitar a movimentação de dados.
Abaixo, temos 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), configurará o fluxo de dados de telemetria do dispositivo nos 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 com o cenário, você vai interagir com os componentes do aplicativo de exemplo pré-escrito que baixou anteriormente.
Estes são os componentes implementados pelo aplicativo de exemplo AdtSampleApp do cenário de construção:
- Autenticação de dispositivo
- Exemplos de uso do SDK do .NET (C#) (encontrados em CommandLoop.cs)
- Interface de console para chamar a API dos Gêmeos Digitais do Azure
- SampleClientApp – uma solução de exemplo dos Gêmeos Digitais do Azure
- SampleFunctionsApp - Um aplicativo do Azure Functions que atualiza seu gráfico de Gêmeos Digitais do Azure com base na telemetria do dispositivo a partir de eventos do Hub IoT e do Gêmeos Digitais do Azure
Criar uma instância do gráfico gêmeo pré-criado
Primeiro, você usará a solução AdtSampleApp do projeto de exemplo para criar a parte referente aos Gêmeos Digitais do Azure do cenário de ponta a ponta (seção A):
Abra uma janela de console local e navegue até a pasta digital-twins-samples-main\AdtE2ESample\SampleClientApp. Execute o projeto SampleClientApp com este comando dotnet:
dotnet run
O projeto começará a ser executado, realizará a autenticação e aguardará um comando. Neste console, execute o comando seguinte para criar uma instância da solução de exemplo dos Gêmeos Digitais do Azure.
Importante
Se você já tiver gêmeos digitais e relações em sua instância dos Gêmeos Digitais do Azure, a execução desse comando os excluirá e os substituirá pelos gêmeos e pelas relações do cenário de exemplo.
SetupBuildingScenario
A saída desse comando é uma série de mensagens de confirmação, conforme três gêmeos digitais são criados e conectados em sua instância dos Gêmeos Digitais do Azure: um andar chamado floor1, uma sala chamada room21 e um sensor de temperatura chamado thermostat67. Esses gêmeos digitais representam as entidades que existiriam em um ambiente do mundo real.
Elas são conectadas por relações no seguinte grafo de gêmeos. O gráfico gêmeo representa o ambiente como um todo, incluindo como as entidades interagem e se relacionam entre si.
Você pode verificar que os gêmeos foram criados executando o comando a seguir, que consulta a instância conectada dos Gêmeos Digitais do Azure para todos os gêmeos digitais que ela contém:
Query
Agora você pode interromper a execução do projeto. Mantenha a janela do console aberta neste local, pois você usará este aplicativo novamente mais tarde no tutorial.
Configurar o aplicativo de funções de exemplo
A etapa seguinte é configurar um aplicativo do Azure Functions que será usado em todo este tutorial para processar dados. O aplicativo de funções, SampleFunctionsApp, contém duas funções:
- ProcessHubToDTEvents: processa dados de entrada do Hub IoT e atualiza os Gêmeos Digitais do Azure adequadamente
- ProcessDTRoutedData: processa dados dos gêmeos digitais e atualiza o gêmeos pai nos Gêmeos Digitais do Azure adequadamente
Nesta seção, você publicará o aplicativo de funções pré-escrito e garantirá que ele possa acessar os Gêmeos Digitais do Azure atribuindo a ele uma identidade do Microsoft Entra.
O aplicativo de funções faz parte do projeto de exemplo que você baixou, localizado na pasta digital-twins-samples-main\AdtE2ESample\SampleFunctionsApp.
Publicar o aplicativo
Para publicar o aplicativo de funções no Azure, será necessário criar uma conta de armazenamento e, em seguida, criar o aplicativo de funções no Azure, Por fim, você deverá publicar as funções no aplicativo de funções do Azure. Esta seção conclui essas ações usando o CLI do Azure. Em cada comando, substitua todos os espaços reservados entre colchetes angulares pelos detalhes de seus próprios recursos.
Crie uma conta de armazenamento do Azure executando o comando a seguir:
az storage account create --name <name-for-new-storage-account> --location <location> --resource-group <resource-group> --sku Standard_LRSCrie um aplicativo de funções do Azure executando o comando a seguir:
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 --runtime-version 7 --resource-group <resource-group>Em seguida, você compactará as funções e as publicará em seu novo aplicativo de funções do Azure.
Abra uma janela de console no seu computador e navegue até a pasta digital-twins-samples-main\AdtE2ESample\SampleFunctionsApp dentro do projeto de exemplo que você baixou.
No console, execute o seguinte comando para publicar o projeto localmente:
dotnet publish -c Release -o publishEsse comando publica o projeto no diretório digital-twins-samples-main\AdtSampleApp\SampleFunctionsApp\publish.
Usando seu método preferencial, crie um zip dos arquivos publicados localizados dentro do diretório digital-twins-samples-main\AdtSampleApp\SampleFunctionsApp\publish. Nomeie a pasta compactada como publish.zip.
Importante
Verifique se a pasta compactada não inclui uma camada extra para a pasta Publicar. Ela deve conter apenas o conteúdo que estava na pasta Publicar.
Aqui está uma imagem da aparência que o conteúdo zip pode ter (pode mudar dependendo da sua versão do .NET).
Agora você pode fechar a janela do console local usada para preparar o projeto. A última etapa será feita na CLI do Azure.
Na CLI do Azure, execute o seguinte comando para implantar as funções publicadas e compactadas em seu aplicativo de funções do Azure:
az functionapp deployment source config-zip --resource-group <resource-group> --name <name-of-your-function-app> --src "<full-path-to-publish.zip>"Dica
Se você estiver usando a CLI do Azure localmente, poderá acessar o arquivo ZIP no computador diretamente usando seu caminho em seu computador.
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 no diretório raiz do armazenamento do Cloud Shell. Assim, você poderá consultar o arquivo diretamente pelo nome em busca do parâmetro do comando
--src(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 da sua nova função. Confirme o sucesso da implantação procurando este campo no resultado:
"provisioningState": "Succeeded",
As funções agora devem ser publicadas em um aplicativo de funções no Azure. Você pode usar os comandos da CLI a seguir para verificar se ambas as funções foram publicadas com êxito. Cada comando tem espaços reservados para o grupo de recursos e o nome do aplicativo de funções. 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, o aplicativo de funções precisa das permissões necessárias para acessar a instância dos Gêmeos Digitais do Azure. Você configurará esse acesso na próxima seção.
Configurar permissões para o aplicativo de funções
Duas configurações precisam ser definidas para que o aplicativo de funções acesse a instância de Gêmeos Digitais do Azure, e ambas podem ser feitas usando o CLI do Azure.
Atribuir função de acesso
A primeira configuração fornece a função de proprietário de dados dos Gêmeos Digitais do Azure ao aplicativo de funções 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 de plano de dados na instância. Leia mais sobre atribuições de função e de segurança em Segurança para soluções dos Gêmeos Digitais do Azure.
Use o comando a seguir para criar uma identidade atribuída pelo sistema para a função. A saída exibirá os detalhes da identidade que foi criada. Anote o campo principalId na saída para usá-lo na próxima etapa.
az functionapp identity assign --resource-group <your-resource-group> --name <your-function-app-name>Use o valor de principalId no comando a seguir para atribuir a identidade do aplicativo de funções à função de Proprietário de Dados dos Gêmeos Digitais do Azure para sua instância dos Gêmeos Digitais do Azure.
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 de saída sobre a atribuição de função que você criou. Agora, o aplicativo de funções tem permissões para acessar dados em sua instância dos Gêmeos Digitais do Azure.
Definir a configuração de aplicativo
A segunda configuração cria uma variável de ambiente para a função com a URL da instância dos Gêmeos Digitais do Azure. O código de função usará o valor dessa variável para fazer referência à sua instância. Para obter mais informações sobre variáveis de ambiente, confira Gerenciar o seu aplicativo de funções.
Execute o comando a seguir, preenchendo os espaços reservados com os detalhes dos 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.
Processar telemetria simulada de um dispositivo do Hub IoT
Um gráfico dos Gêmeos Digitais do Azure deve ser controlado pela 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. Conforme o dispositivo simulado emite telemetria, os dados serão direcionados pela função d o Azure ProcessHubToDTEvents, que dispara uma atualização correspondente no gêmeo digital. Dessa forma, o gêmeo digital se mantém atualizado com os dados do dispositivo real. Nos Gêmeos Digitais do Azure, o processo de direcionamento de dados de eventos de um local para outro é chamado de roteamento de eventos.
O processamento da telemetria simulada ocorre neste bloco do cenário de ponta a ponta (seta B):
Estas são as ações que você realizará para configurar esta conexão do dispositivo:
- Criar um hub IoT que gerenciará o dispositivo simulado
- Conectar o hub IoT à função do Azure apropriada configurando uma assinatura de evento
- Registrar o dispositivo simulado no Hub IoT
- Executar o dispositivo simulado e gerar telemetria
- Consultar 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 criados para trabalhar com o Hub IoT, um serviço do Azure para gerenciar dispositivos e seus dados. Nesta etapa, você vai configurar um hub IoT que gerenciará o dispositivo de exemplo neste tutorial.
Na CLI do Azure, use este comando para criar um 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 hub IoT. Você o usará mais tarde.
Conectar o hub IoT à função do Azure
Em seguida, conecte o Hub IoT à função do Azure ProcessHubToDTEvents no aplicativo de funções publicado anteriormente, de modo que os dados possam fluir do dispositivo no Hub IoT para a função, que atualiza os Gêmeos Digitais do Azure.
Para fazer isso, você criará uma assinatura de evento no Hub IoT, com a função do Azure como um ponto de extremidade. Isso "assina" a função para eventos que ocorrem 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 aplicativo de funções.
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 do evento que foi criada. Você pode confirmar que a operação foi concluída com êxito verificando o valor provisioningState no resultado:
"provisioningState": "Succeeded",
Dica
Se o comando retornar um erro de provedor de recursos, adicione Microsoft.EventGrid como um provedor de recursos na sua assinatura. Você pode fazer isso no portal do Azure seguindo as instruções em Registrar um provedor de recursos.
Registrar o dispositivo simulado no Hub IoT
Esta seção cria uma representação do dispositivo no Hub IoT com a ID thermostat67. O dispositivo simulado se conectará a essa representação, que é a maneira como os eventos de telemetria passarão do dispositivo para o Hub IoT. O hub IoT é onde a função do Azure assinada estará escutando, pronta para coletar 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 são informações sobre o dispositivo criado.
Configurar e executar a simulação
Em seguida, configure o simulador do dispositivo 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 conexão do dispositivo com este comando:
az iot hub device-identity connection-string show --device-id thermostat67 --hub-name <your-IoT-hub-name>
Em seguida, use esses valores no código do simulador de dispositivo no projeto local para conectar o simulador ao hub IoT e ao dispositivo do hub IoT.
Navegue no computador local até a pasta de exemplo baixada e entre na pasta digital-twins-samples-main\DeviceSimulator\DeviceSimulator. Abra o arquivo AzureIoTHub.cs para edição. Altere os seguintes valores de cadeia de conexão para os valores que você coletou acima:
private const string iotHubConnectionString = "<your-hub-connection-string>";
//...
private const string deviceConnectionString = "<your-device-connection-string>";
Salve o arquivo.
Agora, para ver os resultados da simulação de dados que você configurou, abra uma nova janela de console local e acesse digital-twins-samples-main\DeviceSimulator\DeviceSimulator.
Observação
Você deve ter duas janelas de console abertas: uma aberta para a pasta DeviceSimulator\DeviceSimulator e outra de antes que ainda esteja aberta na pasta AdtSampleApp\SampleClientApp.
Use o seguinte comando dotnet para executar o projeto do simulador de dispositivo:
dotnet run
O projeto começará a ser executado e exibir mensagens de telemetria de temperatura simuladas. Elas estão sendo enviadas ao hub IoT, onde são coletadas e processadas pela função do Azure.
Você não precisa fazer mais nada neste console, mas deixe-o em execução enquanto conclui as próximas etapas.
Ver os resultados nos Gêmeos Digitais do Azure
A função ProcessHubToDTEvents que você publicou anteriormente escuta os dados do Hub IoT e chama uma API dos Gêmeos Digitais do Azure para atualizar a propriedade Temperature no gêmeo thermostat67.
Para ver os dados do lado dos Gêmeos Digitais do Azure, passe para a outra janela do console aberta na pasta AdtSampleApp\SampleClientApp. Execute o projeto SampleClientApp com dotnet run.
dotnet run
Quando o projeto estiver sendo executado e aceitando comandos, execute o seguinte comando para ver as temperaturas sendo relatadas pelo gêmeo digital thermostat67:
ObserveProperties thermostat67 Temperature
Você deve ver as temperaturas atualizadas de maneira dinâmica de sua instância dos Gêmeos Digitais do Azure 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 estão coordenados).
Observação
Pode levar alguns segundos para que os dados do dispositivo se propaguem até 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 em log ao vivo de temperatura está funcionando corretamente, você pode parar de executar os dois projetos. Mantenha as janelas do console abertas, pois você as usará novamente mais tarde no tutorial.
Propagar eventos dos Gêmeos Digitais do Azure pelo grafo
Até agora neste tutorial, você viu como os Gêmeos Digitais do Azure podem ser atualizados usando dados de um dispositivo externo. A seguir, você verá como as alterações feitas em um gêmeo digital podem ser propagadas pelo grafo dos Gêmeos Digitais do Azure – em outras palavras, como atualizar gêmeos usando dados internos do serviço.
Para fazer isso, você usará a função do Azure ProcessDTRoutedData para atualizar um gêmeo de Room quando o gêmeo do Termostato conectado for atualizado. A funcionalidade de atualização acontece nesta parte do cenário de ponta a ponta (seta C):
Estas são as ações que você realizará para configurar este fluxo de dados:
- Criar um tópico de Grade de Eventos para habilitar a movimentação de dados entre os serviços do Azure
- Criar um ponto de extremidade nos Gêmeos Digitais do Azure que conecta a instância ao tópico da Grade de Eventos
- Configurar uma rota nos Gêmeos Digitais do Azure para enviar eventos de alteração de propriedade do gêmeo para o ponto de extremidade
- Configurar uma função do Azure que escuta o tópico da Grade de Eventos no ponto de extremidade, recebe os eventos de alteração de propriedade do gêmeo que são enviados para lá e atualiza outros gêmeos no grafo da maneira adequada
Criar o tópico da Grade de Eventos
A Grade de Eventos é um serviço do Azure que ajuda você a encaminhar e entregar eventos dos serviços do Azure para outros locais no Azure. Você pode criar um tópico da Grade de Eventos para coletar determinados eventos de uma fonte e, então, os assinantes podem escutar o tópico para receber os eventos à medida que eles chegam.
Na CLI do Azure, execute o comando a seguir para criar um tópico da Grade de Eventos:
az eventgrid topic create --resource-group <your-resource-group> --name <name-for-your-event-grid-topic> --location <region>
A saída desse comando são informações sobre o tópico da Grade de Eventos que você criou. Salve o nome que você deu ao tópico da Grade de Eventos, para usá-lo mais tarde.
Criar o ponto de extremidade
Em seguida, crie um ponto de extremidade da Grade de Eventos nos Gêmeos Digitais do Azure, que conectará sua instância ao tópico da 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 o 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 desse comando são informações sobre o ponto de extremidade que você criou.
Procure o campo provisioningState na saída e verifique se o valor é "Êxito".
Ele também pode indicar "provisionamento", o que significa que o ponto de extremidade ainda está sendo criado. Se for, aguarde alguns segundos e execute o comando a seguir para verificar o status do ponto de extremidade. Repita-o até que provisioningState mostre "Êxito".
az dt endpoint show --dt-name <your-Azure-Digital-Twins-instance> --endpoint-name <your-Azure-Digital-Twins-endpoint>
Salve o nome do ponto de extremidade, para usá-lo mais tarde.
Criar a rota
Em seguida, crie uma rota dos Gêmeos Digitais do Azure que envia eventos para o ponto de extremidade criado da Grade de Eventos.
Use o seguinte comando da CLI, preenchendo o nome do ponto de extremidade da etapa anterior e os outros campos de espaço reservado, conforme o necessário. Esse comando encaminha todos os eventos que ocorrem no grafo gêmeo.
Dica
Você pode limitar os eventos apenas a alguns específicos se quiser 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 desse comando são algumas informações sobre a rota que você criou.
Observação
Os pontos de extremidade (da etapa anterior) devem ter o provisionamento concluído para configurar uma rota de eventos que os utilize. 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, assine a função do Azure ProcessDTRoutedData para o tópico da Grade de Eventos que você criou anteriormente, para que os dados de telemetria possam fluir do gêmeo thermostat67, pelo tópico da Grade de Eventos, até a função, que volta aos Gêmeos Digitais do Azure e atualiza o room21 de modo adequado.
Para fazer isso, você criará uma assinatura da Grade de Eventos que enviará dados do tópico da Grade de Eventos criado anteriormente para a 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 esta assinatura do evento e também há espaços reservados para você inserir sua ID de assinatura, grupo de recursos, o nome do tópico da Grade de Eventos e o nome do aplicativo de funções.
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
Executar a simulação e ver os resultados
Agora os eventos devem ter a capacidade de fluir do dispositivo simulado para os Gêmeos Digitais do Azure e de atualizar os gêmeos por meio do grafo de Gêmeos Digitais do Azure da maneira adequada. Nesta seção, você executará o simulador de dispositivo novamente para dar início ao fluxo de eventos completo que você definiu, e consultará os Gêmeos Digitais do Azure para ver os resultados ao vivo
Acesse a janela do console aberta na pasta DeviceSimulator\DeviceSimulator e execute o projeto do simulador de dispositivo com dotnet run.
Assim como na primeira vez que você executou o simulador de dispositivo, o projeto começará a ser executado e exibirá mensagens de telemetria de temperatura simuladas. Esses eventos estão passando pelo fluxo configurado anteriormente para atualizar o gêmeo thermostat67 e, em seguida, percorrendo o fluxo configurado para atualizar o gêmeo room21 de maneira correspondente.
Você não precisa fazer mais nada neste console, mas deixe-o em execução enquanto conclui as próximas etapas.
Para ver os dados do lado dos Gêmeos Digitais do Azure, acesse a outra janela do console aberta na pasta AdtSampleApp\SampleClientApp e execute o projeto SampleClientApp com dotnet run.
Quando o projeto estiver sendo executado e aceitando comandos, execute o seguinte comando para ver as temperaturas sendo relatadas pelos gêmeos digitais thermostat67 e room21.
ObserveProperties thermostat67 Temperature room21 Temperature
Você deve ver as temperaturas atualizadas de maneira dinâmica de sua instância dos Gêmeos Digitais do Azure sendo registradas no console a cada dois segundos. Observe que a temperatura de room21 está sendo atualizada de maneira a corresponder às atualizações de thermostat67.
Depois de verificar se o registro em log ao vivo das temperaturas está funcionando corretamente na sua instância, você pode parar de executar os dois projetos. Você também pode fechar as duas janelas do console, uma vez que o tutorial está concluído.
Revisão
Esta é uma revisão do cenário que você compilou neste tutorial.
- Uma instância dos Gêmeos Digitais do Azure representa digitalmente um andar, uma sala e um termostato (representado pela seção A no diagrama abaixo)
- A telemetria do dispositivo simulado é enviada ao Hub IoT, onde a função do Azure ProcessHubToDTEvents está escutando eventos de telemetria. A função do Azure ProcessHubToDTEvents usa as informações nesses eventos para definir a propriedade
Temperatureno thermostat67 (seta B no diagrama). - Os eventos de alteração de propriedade nos Gêmeos Digitais do Azure são roteados para um tópico da Grade de Eventos, em que a função do Azure ProcessDTRoutedData está escutando eventos. A função do Azure ProcessDTRoutedData usa as informações nesses eventos para definir a propriedade
Temperatureem room21 (seta B no diagrama).
Limpar os recursos
Depois de concluir este tutorial, você poderá escolher quais recursos gostaria de remover, dependendo do que você gostaria de fazer em seguida.
Caso não precise de nenhum dos recursos criados neste tutorial, você poderá excluir a instância dos Gêmeos Digitais do Azure e todos os outros recursos deste artigo com o comando az group delete da CLI. Isso exclui todos os recursos do Azure em um grupo de recursos, bem como o grupo de recursos em si.
Importante
A exclusão de um grupo de recursos é irreversível. O grupo de recursos e todos os recursos contidos nele são excluídos permanentemente. Não exclua acidentalmente grupo de recursos ou recursos incorretos.
Abra o Azure Cloud Shell ou uma janela da CLI local e execute o comando a seguir para excluir o grupo de recursos e tudo o que ele contém.
az group delete --name <your-resource-group>
Caso você deseje continuar usando a instância dos Gêmeos Digitais do Azure configurada neste artigo, mas limpar alguns ou todos os modelos, gêmeos e relações dela, use os comandos da CLI az dt para excluir os elementos que você deseja remover.
Essa opção não removerá nenhum dos outros recursos do Azure criados neste tutorial (Hub IoT, aplicativo do Azure Functions etc.). Você pode exclui-los individualmente usando os comandos dt apropriados para cada tipo de recurso.
Talvez seja interessante excluir a pasta do projeto do computador local.
Próximas etapas
Neste tutorial, você criou um cenário de ponta a ponta que mostra os Gêmeos Digitais do Azure controlados por dados dinâmicos do dispositivo.
Em seguida, comece a examinar a documentação de conceito para saber mais sobre os elementos com os quais você trabalhou no tutorial: