Tutorial: criar um grafo dos Gêmeos Digitais do Azure usando um aplicativo cliente de exemplo

Artigo
01/03/2024

Neste tutorial, você criará um grafo nos Gêmeos Digitais do Azure usando modelos, gêmeos e relações. A ferramenta para este tutorial é o aplicativo cliente de linha de comando de amostra para interagir com uma instância dos Gêmeos Digitais do Azure. O aplicativo cliente é semelhante ao escrito em Código de um aplicativo cliente.

Você pode usar este exemplo para executar ações essenciais dos Gêmeos Digitais do Azure, como carregar modelos, criar e modificar gêmeos e criar relações. Você também pode examinar o código do exemplo para saber mais sobre as APIs dos Gêmeos Digitais do Azure, bem como praticar a implementação de comandos próprios modificando o projeto de exemplo como preferir.

Neste tutorial, você vai...

Modelar um ambiente
Criar gêmeos digitais
Adicionar relações para formar um grafo
Consultar o grafo para responder perguntas

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.

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.

Executar o projeto de exemplo

Agora que o aplicativo e a autenticação estão configurados, abra uma janela de console local que você usará para executar o projeto. Navegue no console até a pasta digital-twins-samples-main\AdtSampleApp\SampleClientApp e execute o projeto com este comando dotnet:

dotnet run

O projeto começará a ser executado, realizará a autenticação e aguardará um comando.

Veja uma captura de tela mostrando o console do projeto:

Dica

Para obter uma lista de todos os comandos possíveis que você pode usar com este projeto, digite help no console do projeto e pressione retornar.

Depois de confirmar que o aplicativo está sendo executado com êxito, você poderá parar de executar o projeto. Você o executará de novo mais adiante no tutorial.

Modelar um ambiente físico com DTDL

Agora que a instância dos Gêmeos Digitais do Azure e o aplicativo de exemplo estão configurados, você pode começar a criar um grafo de um cenário.

A primeira etapa na criação de uma solução dos Gêmeos Digitais do Azure é definir modelos gêmeos para o ambiente.

Os modelos são semelhantes às classes nas linguagens de programação orientadas a objeto. Eles fornecem modelos definidos pelo usuário dos quais você poderá criar uma instância para criar gêmeos digitais. Os modelos para Gêmeos Digitais do Azure são escritos em uma linguagem semelhante a JSON chamada DTDL (Digital Twins Definition Language) e definem um tipo de gêmeo em termos de suas propriedades, relacionamentos e componentes.

Observação

A DTDL também permite a definição de comandos em gêmeos digitais. No entanto, atualmente os comandos não têm suporte nos Gêmeos Digitais do Azure.

Na pasta de projeto de exemplo que você baixou anteriormente, navegue até a pasta digital-twins-samples-main\AdtSampleApp\SampleClientApp\Models. Esta pasta contém modelos de exemplo.

Abra Room.json para edição e faça as seguintes alterações no código:

Atualizar o número de versão, de modo a indicar que você está fornecendo uma versão mais atualizada do modelo. Faça isso alterando o 1 no final do valor @id para 2. Qualquer número maior que o da versão atual também funcionará.
Editar uma propriedade. Altere o nome da propriedade Humidity para HumidityLevel (ou algo diferente se quiser. Caso use algo diferente de HumidityLevel, lembre-se do que usou e continue usando isso em vez de HumidityLevel ao longo do tutorial).
Adicionar uma propriedade. Abaixo da propriedade HumidityLevel que termina na linha 15, cole o código a seguir para adicionar uma propriedade RoomName à sala:
```
,{
  "@type": "Property",
  "name": "RoomName",
  "schema": "string"
}
```
Adicionar uma relação. Abaixo da propriedade RoomName que você acabou de adicionar, cole o seguinte código para adicionar a capacidade desse tipo de gêmeo de gerar relações do tipo contains com outros gêmeos:
```
,{
  "@type": "Relationship",
  "name": "contains"
}
```

Quando você terminar, o modelo atualizado deverá corresponder a:

{
    "@id": "dtmi:example:Room;2",
    "@type": "Interface",
    "displayName": "Room",
    "contents": [
      {
        "@type": "Property",
        "name": "Temperature",
        "schema": "double"
      },
      {
        "@type": "Property",
        "name": "HumidityLevel",
        "schema": "double"
      }
      ,{
        "@type": "Property",
        "name": "RoomName",
        "schema": "string"
      }
      ,{
        "@type": "Relationship",
        "name": "contains"
      }
    ],
    "@context": "dtmi:dtdl:context;3"
  }

Salve o arquivo antes de continuar.

Carregar modelos nos Gêmeos Digitais do Azure

Depois de criar modelos, você precisa carregá-los na instância dos Gêmeos Digitais do Azure. Isso vai configurar a instância de serviço dos Gêmeos Digitais do Azure com o seu vocabulário de domínio personalizado. Após carregar os modelos, será possível criar instâncias gêmeas para usá-los.

Volte à janela do console aberta na pasta digital-twins-samples-main\AdtSampleApp\SampleClientApp e execute o aplicativo de console novamente com dotnet run.
Na janela do console do projeto, execute o comando a seguir para carregar o modelo Room atualizado, juntamente com o modelo Floor que você também vai usar na próxima seção para criar diferentes tipos de gêmeos.
```
CreateModels Room Floor
```
A saída deve indicar que os modelos foram criados com êxito.
Verifique se os modelos foram criados executando o comando GetModels true. Esse comando vai copiar as informações completas de todos os modelos carregados na instância dos Gêmeos Digitais do Azure. Procure pelo modelo Room editado nos resultados:

Mantenha o aplicativo de console em execução para as próximas etapas.

Errors

O aplicativo de exemplo também trata erros do serviço.

Para testar isso, execute novamente o comando CreateModels para tentar recarregar o modelo Room que você já carregou:

CreateModels Room

Como os modelos não podem ser substituídos, esse comando agora retornará um erro de serviço indicando que algumas das IDs de modelo que você está tentando criar já existem.

Para obter detalhes sobre como excluir os modelos existentes, confira Gerenciar modelos DTDL.

Criar gêmeos digitais

Agora que alguns modelos foram carregados em sua instância dos Gêmeos Digitais do Azure, você pode criar gêmeos digitais com base nas definições do modelo. Gêmeos digitais representam as entidades no seu ambiente de negócios – itens como sensores em uma fazenda, salas em um prédio ou luzes em um carro.

Para criar um gêmeo digital, use o comando CreateDigitalTwin. Você precisa referenciar o modelo em que o gêmeo se baseia e pode optar por definir valores iniciais para qualquer propriedade no modelo. Não é preciso fornecer informações sobre a relação neste estágio.

Execute este código no console do projeto em execução para criar vários gêmeos, com base no modelo Room que você atualizou anteriormente e em outro modelo, Floor. Lembre-se de que o modelo Room tem três propriedades. Portanto, é possível fornecer argumentos com os valores iniciais delas. (Em geral, a inicialização de valores de propriedade é opcional, mas eles são necessários para este tutorial.)
```
CreateDigitalTwin dtmi:example:Room;2 room0 RoomName string Room0 Temperature double 70 HumidityLevel double 30
CreateDigitalTwin dtmi:example:Room;2 room1 RoomName string Room1 Temperature double 80 HumidityLevel double 60
CreateDigitalTwin dtmi:example:Floor;1 floor0
CreateDigitalTwin dtmi:example:Floor;1 floor1
```
A saída desses comandos deve indicar que os gêmeos foram criados com êxito.
Você pode verificar se os gêmeos foram criados executando o comando Query. Esse comando consulta sua instância dos Gêmeos Digitais do Azure para todos os gêmeos digitais que ela contém. Procure pelos gêmeos room0, room1, floor0 e floor1 nos resultados.

Observação

Após a realização de uma alteração nos dados do grafo, talvez haja uma latência de até dez segundos antes que as alterações sejam exibidas nas consultas.

A API do DigitalTwins reflete as alterações imediatamente. Portanto, se você precisar de uma resposta instantânea, use uma solicitação de API (DigitalTwins GetById) ou uma chamada de SDK (GetDigitalTwin) para obter dados dos gêmeos em vez de uma consulta.

Modificar um gêmeo digital

Você também pode modificar as propriedades de um gêmeo que criou.

Observação

A API REST subjacente usa o formato patch JSON para definir atualizações em um gêmeo. O aplicativo de linha de comando também usa esse formato, para proporcionar uma experiência mais verdadeira com o que as APIs subjacentes esperam.

Execute este comando para alterar o "RoomName" de room0 de "Room0" para "PresidentialSuite":
```
UpdateDigitalTwin room0 add /RoomName string PresidentialSuite
```
A saída deve indicar que o gêmeo foi atualizado com êxito.
Você pode verificar a atualização executando esse comando para ver as informações de room0:
```
GetDigitalTwin room0
```
A saída deve refletir o nome atualizado.

Criar um grafo adicionando relações

Em seguida, você pode criar algumas relações entre esses gêmeos para conectá-los em um grafo de gêmeos. Grafos de gêmeos são usados para representar todo o ambiente.

Os tipos de relações que você pode criar de um tipo de gêmeo para outro são definidos nos modelos que você carregou anteriormente. A definição de modelo do Floor especifica que os andares podem ter um tipo de relação chamada contains, que possibilita criar uma relação do tipo contains de cada gêmeo Floor para a sala correspondente que ele contém.

Para adicionar uma relação, use o comando CreateRelationship. Especifique o gêmeo no qual a relação tem origem, o tipo de relação e o gêmeo ao qual a relação está se conectando. Por fim, dê à relação uma ID exclusiva.

Execute os comandos a seguir para adicionar uma relação contains de cada um dos gêmeos de Floor criados anteriormente a cada Room correspondente. As relações são nomeadas relationship0 e relationship1.
```
CreateRelationship floor0 contains room0 relationship0
CreateRelationship floor1 contains room1 relationship1
```
Dica

A relação contains no modelo Floor também foi definida com duas propriedades de cadeia de caracteres, ownershipUser e ownershipDepartment. Portanto, você também pode fornecer argumentos com os valores iniciais para eles ao criar as relações. Esta é uma versão alternativa do comando acima para criar relationship0 que também especifica valores iniciais para essas propriedades:
```
CreateRelationship floor0 contains room0 relationship0 ownershipUser string MyUser ownershipDepartment string myDepartment
```
A saída desses comandos confirma que as relações foram criadas com êxito:
É possível verificar as relações usando um dos comandos a seguir, que vai copiar as relações na instância dos Gêmeos Digitais do Azure.
- Para ver todas as relações provenientes de cada andar (exibindo as relações de um lado):
```
GetRelationships floor0
GetRelationships floor1
```
- Para ver todas as relações chegando em cada sala (exibindo a relação do "outro" lado):
```
GetIncomingRelationships room0
GetIncomingRelationships room1
```
- Para procurar essas relações individualmente, por ID:
```
GetRelationship floor0 relationship0
GetRelationship floor1 relationship1
```

O gêmeos e as relações que você configurou neste tutorial formam o seguinte grafo conceitual:

Consultar o grafo de gêmeos para responder às perguntas sobre o ambiente

Um dos principais recursos dos Gêmeos Digitais do Azure é a capacidade de consultar o grafo de gêmeos com facilidade e eficiência para responder às perguntas sobre o seu ambiente.

Observação

Após a realização de uma alteração nos dados do grafo, talvez haja uma latência de até dez segundos antes que as alterações sejam exibidas nas consultas.

Execute os comandos a seguir no console do projeto em execução para responder a algumas perguntas sobre o ambiente de exemplo.

Quais são todas as entidades do meu ambiente representadas nos Gêmeos Digitais do Azure? (consultar tudo)
```
Query
```
Esse comando permite fazer um resumo rápido sobre o ambiente e verificar se tudo está representado como você deseja dentro dos Gêmeos Digitais do Azure. O resultado desse comando é uma saída contendo cada gêmeo digital com os respectivos detalhes. Veja um trecho:

Dica

No projeto de exemplo, o comando Query sem argumentos adicionais é o equivalente de Query SELECT * FROM DIGITALTWINS. Para consultar todos os gêmeos em sua instância usando as APIs de Consulta ou os comandos da CLI, use a consulta mais longa (completa).
Quais são as salas em meu ambiente? (consultar por modelo)
```
Query SELECT * FROM DIGITALTWINS T WHERE IS_OF_MODEL(T, 'dtmi:example:Room;2')
```
Você pode restringir a consulta aos gêmeos de um determinado tipo a fim de obter informações mais específicas sobre o que é representado. O resultado mostra room0 e room1, porém não mostra floor0 nem floor1 (pois eles são andares, não salas).
Quais são as salas em floor0? (consultar por relação)
```
Query SELECT room FROM DIGITALTWINS floor JOIN room RELATED floor.contains where floor.$dtId = 'floor0'
```
Você pode consultar com base nas relações em seu grafo para obter informações sobre como os gêmeos estão conectados ou para restringir a consulta a uma determinada área. Somente room0 está em floor0 e, portanto, é a única sala no resultado.
Quais são todos os gêmeos em meu ambiente com temperatura acima de 75? (consultar por propriedade)
```
Query SELECT * FROM DigitalTwins T WHERE T.Temperature > 75
```
É possível consultar o grafo com base nas propriedades para responder a várias perguntas, incluindo como localizar exceções no ambiente que poderão requerer atenção. Também há suporte a outros operadores de comparação (<, >, = ou !=). room1 aparece nos resultados aqui porque tem uma temperatura de 80.
Quais são as salas em floor0 com temperatura acima de 75? (consulta composta)
```
Query SELECT room FROM DIGITALTWINS floor JOIN room RELATED floor.contains where floor.$dtId = 'floor0' AND IS_OF_MODEL(room, 'dtmi:example:Room;2') AND room.Temperature > 75
```
Você também pode combinar as consultas anteriores como faria no SQL, usando operadores de combinação como AND, OR e NOT. Essa consulta usa AND para deixar a consulta anterior sobre as temperaturas dos gêmeos mais específica. O resultado agora inclui apenas salas com temperaturas acima de 75 que estão em floor0– que, nesse caso, é nenhuma delas. O conjunto de resultados é vazio.

Agora que você executou várias consultas no cenário configurado, o tutorial está concluído. Pare de executar o projeto e feche a janela do console.

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 planeje prosseguir para o próximo tutorial, você pode manter os recursos configurados aqui para continuar usando essa instância dos Gêmeos Digitais do Azure e o aplicativo de exemplo configurado para o próximo tutorial
Caso queira continuar usando a instância dos Gêmeos Digitais do Azure, mas limpar todos os seus modelos, gêmeos e relações, use os comandos DeleteAllTwins e DeleteAllModels do aplicativo de exemplo para limpar o gêmeos e os modelos em sua instância, respectivamente.

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>
```

Talvez seja interessante excluir a pasta do projeto baixada do computador local.

Próximas etapas

Neste tutorial, você começou a usar os Gêmeos Digitais do Azure criando um grafo em sua instância usando um aplicativo cliente de exemplo. Você criou modelos, gêmeos digitais e relações para formar um grafo. Você também executou algumas consultas no grafo para ter uma ideia de quais tipos de perguntas os Gêmeos Digitais do Azure podem responder sobre um ambiente.

Continue para o próximo tutorial a fim de combinar os Gêmeos Digitais do Azure com outros serviços do Azure para concluir um cenário de ponta a ponta orientado por dados:

Conectar uma solução de ponta a ponta

Tutorial: criar um grafo dos Gêmeos Digitais do Azure usando um aplicativo cliente de exemplo

Pré-requisitos

Obter exemplos de recursos

Preparar uma instância dos Gêmeos Digitais do Azure

Configurar o projeto de exemplo

Configurar credenciais locais do Azure

Executar o projeto de exemplo

Modelar um ambiente físico com DTDL

Carregar modelos nos Gêmeos Digitais do Azure

Errors

Criar gêmeos digitais

Modificar um gêmeo digital

Criar um grafo adicionando relações

Consultar o grafo de gêmeos para responder às perguntas sobre o ambiente

Limpar os recursos

Próximas etapas

Recursos adicionais