Tutorial: Criar uma solução ponto a ponto

Este tutorial do Azure Digital Twins descreve como criar uma solução ponto a ponto que demonstra a funcionalidade do serviço. Para configurar uma solução ponto a ponto completa condicionada por dados dinâmicos do seu ambiente, pode ligar a sua instância do Azure Digital Twins a outros serviços do Azure para gestão de dispositivos e dados.

Neste tutorial, irá...

  • Configurar uma instância do Azure Digital Twins
  • Saiba mais sobre o cenário de criação de exemplos e instanciar os componentes pré-escritos
  • Utilizar uma aplicação Funções do Azure para encaminhar a telemetria simulada de um dispositivo Hub IoT para propriedades de duplo digital
  • Propagar alterações através do grafo duplo ao processar notificações de duplos digitais com Funções do Azure, pontos finais e rotas

Pré-requisitos

Antes de iniciar 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 utiliza o .NET Core 3.1. Pode transferir esta versão do SDK .NET Core para várias plataformas a partir de Transferir o .NET Core 3.1.

Em seguida, avance para o resto desta secção para configurar os restantes pré-requisitos.

Obter recursos de exemplo

O tutorial é impulsionado por um projeto de exemplo ponto a ponto do Azure Digital Twins escrito em C#. Obtenha o projeto de exemplo no seu computador ao navegar para a ligação de exemplo e ao selecionar o botão Procurar código por baixo do título.

Isto irá levá-lo para o repositório do GitHub para obter os exemplos, que pode transferir como um .zip ao selecionar o botão Código seguido de Transferir ZIP.

Captura de ecrã do repositório digital-twins-samples no GitHub, realçando os passos para transferi-lo como um zip.

Esta ação irá transferir uma pasta .zip para o seu computador como digital-twins-samples-main.zip. Deszipe a pasta e extraia os ficheiros.

Preparar uma instância do Azure Digital Twins

Para trabalhar com o Azure Digital Twins neste artigo, precisará de uma instância do Azure Digital Twins e das permissões necessárias para a utilizar. Se já tiver uma instância do Azure Digital Twins configurada, pode utilizar essa instância e avançar para a secção seguinte. Caso contrário, siga as instruções em Configurar uma instância e autenticação. As instruções contêm informações para o ajudar a verificar se concluiu cada passo com êxito.

Depois de configurar a instância, anote o nome do anfitrião da instância. Pode encontrar o nome do anfitrião no portal do Azure.

Prepare o seu ambiente para o CLI do Azure

Configurar a sessão da CLI

Para começar a trabalhar com o Azure Digital Twins na CLI, a primeira coisa a fazer é iniciar sessão e definir o contexto da CLI para a sua subscrição para esta sessão. Execute estes comandos na janela da CLI:

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

Dica

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

Se esta for a primeira vez que utiliza esta subscrição com o Azure Digital Twins, execute este comando para se registar no espaço de nomes do Azure Digital Twins. (Se não tiver a certeza, não há problema em executá-lo novamente, mesmo que já o tenha feito no passado.)

az provider register --namespace 'Microsoft.DigitalTwins'

Em seguida, irá adicionar a Extensão IoT do Microsoft Azure para a CLI do Azure, para ativar comandos para interagir com o Azure Digital Twins e outros serviços 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, está pronto para trabalhar com o Azure Digital Twins na CLI do Azure.

Pode verificar esta situação ao executar az dt --help em qualquer altura 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 uma aplicação cliente de exemplo que irá interagir com a instância do Azure Digital Twins.

Navegue no computador para a pasta que transferiu anteriormente a partir de amostras ponto a ponto do Azure Digital Twins (e deszipe-a se ainda não o tiver feito).

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

No corpo do ficheiro, altere o URL do nome do anfitrião da instância do instanceUrl Azure Digital Twins (ao adicionar https:// à frente do nome do anfitrião, conforme mostrado abaixo).

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

Guarde e feche o ficheiro.

Configurar credenciais locais do Azure

Este exemplo utiliza DefaultAzureCredential (parte da Azure.Identity biblioteca) para autenticar utilizadores com a instância do Azure Digital Twins quando o executa no computador local. Para obter mais informações sobre diferentes formas de autenticação de uma aplicação cliente com o Azure Digital Twins, veja Escrever código de autenticação de aplicações.

Com DefaultAzureCredentialo , o exemplo irá procurar credenciais no seu ambiente local, como um início de sessão do Azure numa CLI local do Azure ou no Visual Studio ou No Visual Studio Code. Por este motivo, deve iniciar sessão no Azure localmente através de um destes 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 estiver a utilizar uma janela da CLI local, execute o az login comando para iniciar sessão na sua conta do Azure. Depois disso, quando executar o seu exemplo de código, deve ser autenticado automaticamente.

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

O projeto de exemplo utilizado neste tutorial representa um cenário de construção do mundo real, que contém um piso, uma sala e um dispositivo termóstato. Estes componentes serão representados digitalmente numa instância do Azure Digital Twins, que será ligada a Hub IoT, Event Grid e duas funções do Azure para permitir o movimento de dados.

Segue-se um diagrama que representa o cenário completo.

Primeiro, vai criar a instância do Azure Digital Twins (secção A no diagrama) e, em seguida, configurar o fluxo de dados telemétricos para os duplos digitais (seta B) e, em seguida, configurar a propagação de dados através do gráfico duplo (seta C).

Diagrama do cenário de construção completo, que mostra os dados que fluem de um dispositivo para o Azure Digital Twins através de vários serviços do Azure.

Para resolver o cenário, irá interagir com componentes da aplicação de exemplo pré-escrita que transferiu anteriormente.

Eis os componentes implementados pela aplicação de exemplo AdtSampleApp do cenário de criação:

  • Autenticação do dispositivo
  • Exemplos de utilização do SDK .NET (C#) (encontrados em CommandLoop.cs)
  • Interface da consola para chamar a API do Azure Digital Twins
  • SampleClientApp - Uma solução de exemplo do Azure Digital Twins
  • SampleFunctionsApp - uma aplicação Funções do Azure que atualiza o gráfico do Azure Digital Twins com base na telemetria de eventos do Hub IoT e do Azure Digital Twins

Instanciar o grafo duplo pré-criado

Primeiro, irá utilizar a solução AdtSampleApp do projeto de exemplo para criar a parte do Azure Digital Twins do cenário ponto a ponto (secção A):

Diagrama de um excerto do diagrama completo do cenário de criação a realçar a secção da instância do Azure Digital Twins.

Abra uma janela da consola local e navegue para 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, realizará a autenticação e aguardará por um comando. Nesta consola, execute o comando seguinte para instanciar a solução do Azure Digital Twins de exemplo.

Importante

Se já tiver duplos digitais e relações na sua instância do Azure Digital Twins, executar este comando irá eliminá-los e substituí-los pelos duplos e relações para o cenário de exemplo.

SetupBuildingScenario

A saída deste comando é uma série de mensagens de confirmação, uma vez que três duplos digitais são criados e ligados na sua instância do Azure Digital Twins: um piso com o nome floor1, uma sala com o nome room21 e um sensor de temperatura com o nome termóstato67. Estes duplos digitais representam as entidades que existiriam num ambiente real.

Estão ligados através de relações no gráfico duplo seguinte. O gráfico duplo representa o ambiente como um todo, incluindo a forma como as entidades interagem e se relacionam entre si.

Diagrama a mostrar que o piso1 contém a sala21 e a sala21 contém o termóstato67.

Pode verificar os duplos que foram criados ao executar o seguinte comando, que consulta a instância do Azure Digital Twins ligada para todos os duplos digitais que contém:

Query

Agora pode parar de executar o projeto. No entanto, mantenha a janela da consola aberta nesta localização, uma vez que irá utilizar esta aplicação novamente mais tarde no tutorial.

Configurar a aplicação de funções de exemplo

O próximo passo é configurar uma aplicação Funções do Azure que será utilizada ao longo deste tutorial para processar dados. A aplicação de funções SampleFunctionsApp contém duas funções:

  • ProcessHubToDTEvents: processa dados de entrada Hub IoT e atualiza o Azure Digital Twins em conformidade
  • ProcessDTRoutedData: processa dados de duplos digitais e atualiza os duplos principais no Azure Digital Twins em conformidade

Nesta secção, irá publicar a aplicação de funções pré-escrita e garantir que a aplicação de funções pode aceder ao Azure Digital Twins ao atribuir-lhe uma identidade do Azure Active Directory (Azure AD).

A aplicação de funções faz parte do projeto de exemplo que transferiu, localizado na pasta digital-twins-samples-main\AdtSampleApp\SampleFunctionsApp .

Publicar a aplicação

Para publicar a aplicação de funções no Azure, terá de criar uma conta de armazenamento, criar a aplicação de funções no Azure e, por fim, publicar as funções na aplicação de funções do Azure. Esta secção conclui estas ações com a CLI do Azure.

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

    az storage account create --name <name-for-new-storage-account> --location <location> --resource-group <resource-group> --sku Standard_LRS
    
  2. Crie uma aplicação de funções do Azure ao executar 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 --runtime-version 6 --resource-group <resource-group>
    
  3. Em seguida, irá fechar as funções e publicá-las na sua nova aplicação de funções do Azure.

    1. Abra uma janela de consola no seu computador e navegue para a pasta digital-twins-samples-main\AdtSampleApp\SampleFunctionsApp no seu projeto de exemplo transferido.

    2. Na consola do , execute o seguinte comando para publicar o projeto localmente:

      dotnet publish -c Release
      

      Este comando publica o projeto no diretório digital-twins-samples-main\AdtSampleApp\SampleFunctionsApp\bin\Release\netcoreapp3.1\publish .

    3. Com o seu método preferido, crie um zip dos ficheiros publicados que estão localizados no diretório digital-twins-samples-main\AdtSampleApp\SampleFunctionsApp\bin\Release\netcoreapp3.1\publish . Dê um nome à pasta zipada publish.zip.

      Dica

      Se estiver a utilizar o PowerShell, pode criar o zip ao copiar o caminho completo para esse diretório \publicar e colá-lo no seguinte comando:

      Compress-Archive -Path <full-path-to-publish-directory>\* -DestinationPath .\publish.zip
      

      O cmdlet irá criar o ficheiro publish.zip na localização do diretório da consola.

      O ficheiro publish.zip deve conter pastas para bin, ProcessDTRoutedData e ProcessHubToDTEvents e também deve existir um ficheiro host.json .

      Captura de ecrã a mostrar Explorador de Ficheiros no Windows a mostrar o conteúdo da pasta zip de publicação.

    Agora, pode fechar a janela da consola local que utilizou para preparar o projeto. O último passo será feito na CLI do Azure.

  4. Na CLI do Azure, execute o seguinte comando para implementar as funções publicadas e zipadas na sua aplicação 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 estiver a utilizar a CLI do Azure localmente, pode aceder ao ficheiro ZIP no seu computador diretamente através do respetivo caminho no seu computador.

    Se estiver a utilizar o Cloud Shell do Azure, carregue o ficheiro ZIP para Cloud Shell com este botão antes de executar o comando:

    Captura de ecrã da Cloud Shell do Azure a realçar como carregar ficheiros.

    Neste caso, o ficheiro será carregado para o diretório de raiz do seu armazenamento Cloud Shell, para que possa consultar o ficheiro diretamente pelo respetivo nome para o --src parâmetro do comando (como em , --src publish.zip).

    Uma implementação bem-sucedida responderá com o código de estado 202 e produzirá um objeto JSON que contém detalhes da sua nova função. Pode confirmar que a implementação foi efetuada com êxito ao procurar este campo no resultado:

    "provisioningState": "Succeeded",
    

As funções devem agora ser publicadas numa aplicação de funções no Azure. Pode utilizar os seguintes comandos da CLI para verificar se ambas as funções foram publicadas com êxito. Cada comando tem marcadores de posição para o grupo de recursos e o nome da sua aplicação de funções. Os comandos irão imprimir 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, a sua aplicação de funções terá de ter a permissão certa para aceder à instância do Azure Digital Twins. Irá configurar este acesso na secção seguinte.

Configurar permissões para a aplicação de funções

Existem duas definições que têm de ser definidas para que a aplicação de funções aceda à sua instância do Azure Digital Twins, ambas podem ser efetuadas com a CLI do Azure.

Atribuir função de acesso

A primeira definição dá à aplicação de funções a função Proprietário de Dados do Azure Digital Twins na instância do Azure Digital Twins. Esta função é necessária para qualquer utilizador ou função que pretenda realizar muitas atividades do plano de dados na instância. Pode ler mais sobre atribuições de funções e segurança em Segurança para soluções do Azure Digital Twins.

  1. Utilize o seguinte comando para criar uma identidade atribuída pelo sistema para a função. O resultado apresentará detalhes da identidade que foi criada. Tome nota do campo principalId na saída a utilizar no passo seguinte.

    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 --dt-name <your-Azure-Digital-Twins-instance> --assignee "<principal-ID>" --role "Azure Digital Twins Data Owner"
    

O resultado deste comando é a saída de informações sobre a atribuição de função que criou. A aplicação de funções tem agora permissões para aceder a dados na instância do Azure Digital Twins.

Configurar definições da aplicação

A segunda definição cria uma variável de ambiente para a função com o URL da instância do Azure Digital Twins. O código de função utilizará o valor desta variável para fazer referência à sua instância. Para obter mais informações sobre variáveis de ambiente, veja Gerir a sua aplicação de funções.

Execute o comando abaixo, preenchendo os marcadores de posição 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>"

O resultado é a lista de definições da Função do Azure, que deve conter agora uma entrada chamada ADT_SERVICE_URL.

Processar telemetria simulada a partir de um dispositivo Hub IoT

Um grafo do Azure Digital Twins destina-se a ser conduzido por telemetria a partir de dispositivos reais.

Neste passo, irá ligar um dispositivo termóstato simulado registado no Hub IoT ao duplo digital que o representa no Azure Digital Twins. À medida que o dispositivo simulado emite telemetria, os dados serão direcionados através da função ProcessHubToDTEvents do Azure que aciona uma atualização correspondente no duplo digital. Desta forma, o duplo digital mantém-se atualizado com os dados reais do dispositivo. No Azure Digital Twins, o processo de direção de dados de eventos de um local para outro chama-se eventos de encaminhamento.

O processamento da telemetria simulada ocorre nesta parte do cenário ponto a ponto (seta B):

Diagrama de um excerto do diagrama completo do cenário de criação a realçar a secção que mostra elementos antes do Azure Digital Twins.

Eis as ações que irá concluir para configurar esta ligação de dispositivo:

  1. Criar um hub IoT que irá gerir o dispositivo simulado
  2. Ligar o hub IoT à função adequada do Azure ao configurar uma subscrição de evento
  3. Registar o dispositivo simulado no hub IoT
  4. Executar o dispositivo simulado e gerar telemetria
  5. Consultar o Azure Digital Twins para ver os resultados em direto

Criar uma instância do Hub IoT

O Azure Digital Twins foi concebido para funcionar em conjunto com Hub IoT, um serviço do Azure para gerir dispositivos e os respetivos dados. Neste passo, vai configurar um hub IoT que irá gerir o dispositivo de exemplo neste tutorial.

Na CLI do Azure, utilize 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

O resultado deste comando são informações sobre o hub IoT que foi criado.

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

Ligar o hub IoT à função do Azure

Em seguida, ligue o hub IoT à função ProcessHubToDTEvents do Azure na aplicação de funções que publicou anteriormente, para que os dados possam fluir do dispositivo em Hub IoT através da função, que atualiza o Azure Digital Twins.

Para tal, irá criar uma subscrição de evento no seu Hub IoT, com a função do Azure como ponto final. Esta ação "subscreve" a função aos eventos que ocorrem no Hub IoT.

Utilize o seguinte comando da CLI para criar a subscrição do evento. Existe um marcador de posição para introduzir um nome para a subscrição do evento e também existem marcadores de posição para introduzir o ID da subscrição, o grupo de recursos, o nome do hub IoT e o nome da sua aplicação 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

O resultado mostrará informações sobre a subscrição de eventos que foi criada. Pode confirmar que a operação foi concluída com êxito ao verificar o provisioningState valor no resultado:

"provisioningState": "Succeeded",

Dica

Se o comando devolver um erro do fornecedor de recursos, adicione Microsoft.EventGrid como fornecedor de recursos à sua subscrição. Pode fazê-lo no portal do Azure ao seguir as instruções em Registar fornecedor de recursos.

Registar o dispositivo simulado com Hub IoT

Esta secção cria uma representação do dispositivo no Hub IoT com o termóstato de ID67. O dispositivo simulado irá ligar-se a esta representação, que é a forma como os eventos de telemetria passarão do dispositivo para Hub IoT. O hub IoT é onde a função subscrita do Azure do passo anterior está a escutar, pronta para recolher 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>

O resultado são informações sobre o dispositivo que foi criado.

Configurar e executar a simulação

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

Comece por obter a cadeia de ligação do hub IoT com este comando:

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, ligue estes valores ao código do simulador de dispositivos no projeto local para ligar o simulador a este hub IoT e ao dispositivo hub IoT.

Navegue no seu computador local para a pasta de exemplo transferida e para a pasta digital-twins-samples-main\DeviceSimulator\DeviceSimulator . Abra o ficheiro AzureIoTHub.cs para edição. Altere os seguintes valores de cadeia de ligação para os valores que recolheu 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 configurou, abra uma nova janela da consola local e navegue para digital-twins-samples-main\DeviceSimulator\DeviceSimulator.

Nota

Agora, deverá ter duas janelas de consola abertas: uma aberta para a pasta DeviceSimulator\DeviceSimulator e outra anterior que ainda está aberta para a pasta AdtSampleApp\SampleClientApp .

Utilize o seguinte comando dotnet para executar o projeto de simulador de dispositivos:

dotnet run

O projeto começará a ser executado e começará a apresentar mensagens de telemetria de temperatura simulada. Estas mensagens estão a ser enviadas para Hub IoT, onde são depois recolhidas e processadas pela função do Azure.

Captura de ecrã a mostrar a saída da consola do simulador do dispositivo que mostra a telemetria de temperatura a ser enviada.

Não precisa de fazer mais nada nesta consola, mas deixe-a em execução enquanto conclui os passos seguintes.

Ver os resultados no Azure Digital Twins

A função ProcessHubToDTEvents que publicou anteriormente escuta os dados Hub IoT e chama uma API do Azure Digital Twins para atualizar a Temperature propriedade no termóstato67 duplo.

Para ver os dados do lado do Azure Digital Twins, mude para a outra janela da consola aberta para a pasta AdtSampleApp\SampleClientApp . Execute o projeto SampleClientApp com dotnet run.

Assim que o projeto estiver a executar e a aceitar comandos, execute o seguinte comando para obter as temperaturas que estão a ser reportadas pelo termóstato duplo digital67:

ObserveProperties thermostat67 Temperature

Deverá ver as temperaturas atualizadas em direto da instância do Azure Digital Twins a serem registadas na consola a cada dois segundos. Devem refletir os valores que o simulador de dados está a gerar (pode colocar as janelas da consola lado a lado para verificar se os valores coordenam).

Nota

Os dados do dispositivo podem demorar alguns segundos a propagar para o duplo. As primeiras leituras de temperatura podem ser apresentadas como 0 antes de os dados começarem a chegar.

Captura de ecrã a mostrar a saída da consola a mostrar o registo de mensagens de temperatura do termóstato duplo digital67.

Depois de verificar se o registo de temperatura em direto está a funcionar com êxito, pode parar de executar ambos os projetos. Mantenha as janelas da consola abertas, pois irá utilizá-las novamente mais tarde no tutorial.

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

Até agora, neste tutorial, viu como o Azure Digital Twins pode ser atualizado a partir de dados de dispositivos externos. Em seguida, verá como as alterações a um duplo digital podem propagar-se através do grafo do Azure Digital Twins, ou seja, como atualizar duplos a partir de dados internos do serviço.

Para tal, irá utilizar a função ProcessDTRoutedData do Azure para atualizar um Duplo Quarto quando o Termóstato duplo ligado for atualizado. A funcionalidade de atualização ocorre nesta parte do cenário ponto a ponto (seta C):

Diagrama de um excerto do diagrama completo do cenário de criação a realçar a secção que mostra os elementos após o Azure Digital Twins.

Eis as ações que irá concluir para configurar este fluxo de dados:

  1. Criar um tópico do Event Grid para ativar o movimento de dados entre os serviços do Azure
  2. Criar um ponto final no Azure Digital Twins que liga a instância ao tópico do Event Grid
  3. Configurar uma rota no Azure Digital Twins que envia eventos de alteração de propriedade duplo para o ponto final
  4. Configurar uma função do Azure que escuta o tópico do Event Grid no ponto final, recebe os eventos de alteração da propriedade duplo que são enviados para lá e atualiza outros duplos no gráfico em conformidade

Criar o tópico do Event Grid

O Event Grid é um serviço do Azure que ajuda a encaminhar e a fornecer eventos dos serviços do Azure para outros locais no Azure. Pode criar um tópico do Event Grid para recolher determinados eventos de uma origem e, em seguida, os subscritores podem ouvir o tópico para receber os eventos à medida que passam.

Na CLI do Azure, execute o seguinte comando para criar um tópico do Event Grid:

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

O resultado deste comando é informações sobre o tópico do Event Grid que criou. Guarde o nome que deu ao seu tópico do Event Grid, uma vez que irá utilizá-lo mais tarde.

Criar o ponto final

Em seguida, crie um ponto final do Event Grid no Azure Digital Twins, que ligará a sua instância ao seu tópico do Event Grid. Utilize o comando abaixo, preenchendo o nome do tópico do Event Grid do passo anterior e os outros campos de marcador de posição, 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>

O resultado deste comando é uma informação sobre o ponto final que criou.

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

Captura de ecrã a mostrar o resultado da consulta de ponto final na Cloud Shell do portal do Azure, mostrando o ponto final com um provisioningState of Succeeded.

Também pode dizer "Aprovisionamento", o que significa que o ponto final ainda está a ser criado. Em caso afirmativo, aguarde alguns segundos e execute o seguinte comando para verificar o estado do ponto final. Repita até mostrar provisioningState "Com êxito".

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

Guarde o nome do ponto final, pois irá utilizá-lo mais tarde.

Criar a rota

Em seguida, crie uma rota do Azure Digital Twins que envie eventos para o ponto final do Event Grid que criou.

Utilize o seguinte comando da CLI, preenchendo o nome do ponto final do passo anterior e os outros campos de marcador de posição, conforme necessário. Este comando reencaminha todos os eventos que ocorrem no gráfico duplo.

Dica

Pode limitar os eventos a apenas eventos específicos, se quiser, através de 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>

O resultado deste comando é algumas informações sobre a rota que criou.

Nota

Os pontos finais (do passo anterior) têm de estar concluídos antes de poder configurar uma rota de eventos que os utilize. Se a criação da rota falhar porque os pontos finais não estão prontos, aguarde alguns minutos e tente novamente.

Ligar a função do Azure

Em seguida, subscreva a função ProcessDTRoutedData do Azure para o tópico do Event Grid que criou anteriormente, para que os dados telemétricos possam fluir do termóstato67 duplo através do tópico Event Grid para a função, que regressa ao Azure Digital Twins e atualiza a sala 21 twin em conformidade.

Para tal, irá criar uma subscrição do Event Grid que envia dados do tópico do Event Grid que criou anteriormente para a função ProcessDTRoutedData do Azure.

Utilize o seguinte comando da CLI para criar a subscrição do evento. Existe um marcador de posição para introduzir um nome para esta subscrição de evento e também existem marcadores de posição para introduzir o ID da subscrição, o grupo de recursos, o nome do tópico do Event Grid e o nome da sua aplicação 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

Execute a simulação e veja os resultados

Agora, os eventos devem ter a capacidade de fluir do dispositivo simulado para o Azure Digital Twins e através do grafo do Azure Digital Twins para atualizar duplos conforme adequado. Nesta secção, irá executar novamente o simulador de dispositivos para iniciar o fluxo de eventos completo que configurou e consultar o Azure Digital Twins para ver os resultados em direto

Aceda à janela da consola que está aberta na pasta DeviceSimulator\DeviceSimulator e execute o projeto de simulador de dispositivos com dotnet run.

Tal como na primeira vez que executou o simulador do dispositivo, o projeto começará a ser executado e a apresentar mensagens de telemetria de temperatura simulada. Estes eventos estão a passar pelo fluxo que configurou anteriormente para atualizar o termóstato67 duplo e, em seguida, a percorrer o fluxo que configurou recentemente para atualizar a sala 21 twin para corresponder.

Captura de ecrã a mostrar a saída da consola do simulador do dispositivo que mostra a telemetria de temperatura a ser enviada.

Não precisa de fazer mais nada nesta consola, mas deixe-a em execução enquanto conclui os passos seguintes.

Para ver os dados do lado do Azure Digital Twins, aceda à outra janela da consola aberta na pasta AdtSampleApp\SampleClientApp e execute o projeto SampleClientApp com dotnet run.

Assim que o projeto estiver em execução e a aceitar comandos, execute o seguinte comando para obter as temperaturas comunicadas pelo termóstato duplo digital67 e pela sala de duplos digitais21.

ObserveProperties thermostat67 Temperature room21 Temperature

Deverá ver as temperaturas atualizadas em direto da instância do Azure Digital Twins a serem registadas na consola a cada dois segundos. Repare que a temperatura da sala21 está a ser atualizada para corresponder as atualizações ao termóstato67.

Captura de ecrã da saída da consola a mostrar um registo de mensagens de temperatura, a partir de um termóstato e de uma sala.

Depois de verificar se o registo de temperaturas dinâmicas da sua instância está a funcionar com êxito, pode parar de executar ambos os projetos. Também pode fechar ambas as janelas da consola, uma vez que o tutorial está agora concluído.

Revisão

Eis uma revisão do cenário que criou neste tutorial.

  1. Uma instância do Azure Digital Twins representa digitalmente um piso, uma sala e um termóstato (representado pela secção A no diagrama abaixo)
  2. A telemetria do dispositivo simulado é enviada para Hub IoT, onde a função ProcessHubToDTEvents do Azure está a escutar eventos de telemetria. A função ProcessHubToDTEvents do Azure utiliza as informações nestes eventos para definir a Temperature propriedade no termóstato67 (seta B no diagrama).
  3. Os eventos de alteração de propriedades no Azure Digital Twins são encaminhados para um tópico do Event Grid, onde a função ProcessDTRoutedData do Azure está a escutar eventos. A função ProcessDTRoutedData do Azure utiliza as informações nestes eventos para definir a Temperature propriedade na sala21 (seta C no diagrama).

Diagrama do cenário de construção completo, que mostra os dados que fluem de um dispositivo para o Azure Digital Twins através de vários serviços do Azure.

Limpar os recursos

Depois de concluir este tutorial, pode escolher os recursos que pretende remover, consoante o que pretende fazer a seguir.

  • Se não precisar de nenhum dos recursos que criou neste tutorial, pode eliminar a instância do Azure Digital Twins e todos os outros recursos deste artigo com o comando az group delete CLI. Isto elimina todos os recursos do Azure num 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 eliminar o grupo de recursos e tudo o que contém.

    az group delete --name <your-resource-group>
    
  • Se quiser continuar a utilizar a instância do Azure Digital Twins que configurou neste artigo, mas limpar alguns ou todos os modelos, duplos e relações, pode utilizar os comandos da CLI az dt para eliminar os elementos que pretende remover.

    Esta opção não removerá nenhum dos outros recursos do Azure criados neste tutorial (Hub IoT, Funções do Azure aplicação, etc.). Pode eliminá-los individualmente com os comandos dt adequados para cada tipo de recurso.

Também pode querer eliminar a pasta do projeto do seu computador local.

Passos seguintes

Neste tutorial, criou um cenário ponto a ponto que mostra o Azure Digital Twins a ser impulsionado por dados de dispositivos dinâmicos.

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