Tutorial: Criar um gráfico de Gêmeos Digitais do Azure usando um aplicativo cliente de exemplo

Artigo
01/04/2024

Neste tutorial, você criará um gráfico em Gêmeos Digitais do Azure usando modelos, gêmeos e relacionamentos. A ferramenta para este tutorial é o aplicativo cliente de linha de comando de exemplo para interagir com uma instância do Azure Digital Twins. O aplicativo cliente é semelhante ao escrito em Código 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 relacionamentos. Você também pode examinar o código do exemplo para saber mais sobre as APIs do Azure Digital Twins e praticar a implementação de seus próprios comandos modificando o projeto de exemplo como quiser.

Neste tutorial, você irá...

Modelar um ambiente
Criar duplos digitais
Adicionar relações para formar um gráfico
Consultar o gráfico para responder a perguntas

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 os exemplos, 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.

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 de 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 como 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.

Executar o projeto de exemplo

Agora que o aplicativo e a autenticação estão configurados, abra uma janela do 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, executará a autenticação e aguardará um comando.

Aqui está uma captura de tela de como o console do projeto se parece:

Gorjeta

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

Depois de confirmar que o aplicativo está sendo executado com êxito, você pode parar de executar o projeto. Você irá executá-lo novamente mais tarde no tutorial.

Modele um ambiente físico com DTDL

Agora que a instância do Azure Digital Twins e o aplicativo de exemplo estão configurados, você pode começar a criar um gráfico de um cenário.

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

Os modelos são semelhantes às classes em linguagens de programação orientadas a objetos; eles são modelos definidos pelo usuário que você pode instanciar 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, relações e componentes.

Nota

DTDL também permite a definição de comandos em gêmeos digitais. No entanto, os comandos não são suportados atualmente no serviço 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:

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

Quando terminar, o modelo atualizado deverá corresponder ao seguinte:

{
    "@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"
  }

Certifique-se de salvar o arquivo antes de prosseguir.

Carregar modelos para os Gêmeos Digitais do Azure

Depois de criar modelos, você precisa carregá-los em sua instância do Azure Digital Twins. Isso configura sua instância de serviço do Azure Digital Twins com seu próprio vocabulário de domínio personalizado. Depois de carregar os modelos, você pode criar instâncias gêmeas que os usam.

Retorne à janela do console aberta para a 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 seguinte comando para carregar seu modelo de sala atualizado junto com um modelo de piso que você também 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. Este comando imprimirá as informações completas de todos os modelos que foram carregados na sua instância do Azure Digital Twins. Procure o modelo de sala editado nos resultados:

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

Erros

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

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

CreateModels Room

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

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

Criar duplos digitais

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

Para criar um gêmeo digital, use o CreateDigitalTwin comando. Você deve fazer referência ao modelo no qual o gêmeo se baseia e, opcionalmente, pode definir valores iniciais para quaisquer propriedades no modelo. Você não precisa passar nenhuma informação de relacionamento nesta fase.

Execute este código no console de projeto em execução para criar vários gêmeos, com base no modelo de sala que você atualizou anteriormente e em outro modelo, Floor. Lembre-se de que Room tem três propriedades, portanto, você pode fornecer argumentos com os valores iniciais para essas propriedades. (A inicialização de valores de propriedade é opcional em geral, 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 sucesso.
Você pode verificar se os gêmeos foram criados executando o Query comando. Este comando consulta sua instância do Azure Digital Twins para todos os gêmeos digitais que ela contém. Procure os gêmeos quarto0, quarto1, andar0 e andar1 nos resultados.

Nota

Depois de fazer uma alteração nos dados do gráfico, pode haver uma latência de até 10 segundos antes que as alterações sejam refletidas 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 SDK (GetDigitalTwin) para obter dados gêmeos em vez de uma consulta.

Modificar um gêmeo digital

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

Nota

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

Execute este comando para alterar room0's RoomName 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 se a atualização foi bem-sucedida executando este comando para ver as informações da room0:
```
GetDigitalTwin room0
```
A saída deve refletir o nome atualizado.

Criar um gráfico adicionando relações

Em seguida, você pode criar algumas relações entre esses gêmeos, para conectá-los em um gráfico de gêmeos. Gráficos gêmeos são usados para representar um ambiente inteiro.

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

Para adicionar uma relação, use o CreateRelationship comando. Especifique o gêmeo de onde vem o relacionamento, o tipo de relacionamento e o gêmeo ao qual o relacionamento está se conectando. Por fim, dê ao relacionamento um ID exclusivo.

Execute os comandos a seguir para adicionar uma relação de cada um dos gêmeos de piso que você criou anteriormente a um contains gêmeo de quarto correspondente. As relações são denominadas relationship0 e relationship1.
```
CreateRelationship floor0 contains room0 relationship0
CreateRelationship floor1 contains room1 relationship1
```
Gorjeta

A contains relação no modelo Floor também foi definida com duas propriedades ownershipUser de cadeia de caracteres e ownershipDepartment, para que você também possa fornecer argumentos com os valores iniciais para elas ao criar as relações. Aqui está 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:
Você pode verificar as relações com qualquer um dos comandos a seguir, que imprimirão as relações em sua instância do Azure Digital Twins.
- Para ver todas as relações que saem de cada andar (visualizando as relações de um lado):
```
GetRelationships floor0
GetRelationships floor1
```
- Para ver todas as relações que chegam a cada sala (visualizando a relação do "outro" lado):
```
GetIncomingRelationships room0
GetIncomingRelationships room1
```
- Para procurar essas relações individualmente, por ID:
```
GetRelationship floor0 relationship0
GetRelationship floor1 relationship1
```

Os gêmeos e relacionamentos que você configurou neste tutorial formam o seguinte gráfico conceitual:

Consultar o gráfico gêmeo para responder a perguntas sobre o ambiente

Uma característica principal dos Gêmeos Digitais do Azure é a capacidade de consultar seu gráfico gêmeo de forma fácil e eficiente para responder a perguntas sobre seu ambiente.

Nota

Depois de fazer uma alteração nos dados do gráfico, pode haver uma latência de até 10 segundos antes que as alterações sejam refletidas nas consultas.

Execute os seguintes comandos 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 todos)
```
Query
```
Este comando permite-lhe fazer um balanço rápido do seu ambiente e certificar-se de que tudo está representado como pretende que esteja nos Gêmeos Digitais do Azure. O resultado deste comando é uma saída contendo cada gêmeo digital com seus detalhes. Aqui está um trecho:

Gorjeta

No projeto de exemplo, o comando Query sem argumentos adicionais é o equivalente Query SELECT * FROM DIGITALTWINSa . 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 todos os quartos do meu ambiente? (consulta por modelo)
```
Query SELECT * FROM DIGITALTWINS T WHERE IS_OF_MODEL(T, 'dtmi:example:Room;2')
```
Você pode restringir sua consulta a gêmeos de um determinado tipo, para obter informações mais específicas sobre o que é representado. O resultado disso mostra room0 e room1, mas não mostra floor0 ou floor1 (já que são andares, não quartos).
Quais são todos os quartos no piso 0? (consulta por relação)
```
Query SELECT room FROM DIGITALTWINS floor JOIN room RELATED floor.contains where floor.$dtId = 'floor0'
```
Você pode consultar com base em relacionamentos em seu gráfico, para obter informações sobre como os gêmeos estão conectados ou para restringir sua consulta a uma determinada área. Apenas room0 está no floor0, por isso é o único quarto no resultado.
Quais são todos os gémeos no meu ambiente com uma temperatura acima dos 75? (consulta por propriedade)
```
Query SELECT * FROM DigitalTwins T WHERE T.Temperature > 75
```
Você pode consultar o gráfico com base nas propriedades para responder a várias perguntas, incluindo encontrar valores atípicos em seu ambiente que possam precisar de atenção. Outros operadores de comparação (<,,>= , ou !=) também são suportados. Room1 aparece nos resultados aqui, porque tem uma temperatura de 80.
Quais são todos os quartos no piso 0 com uma 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, NOT. Esta consulta é usada AND para tornar a consulta anterior sobre temperaturas gêmeas mais específica. O resultado agora inclui apenas salas com temperaturas acima de 75 que estão no piso 0 — o que, neste caso, não é nenhum deles. O conjunto de resultados está 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.

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 planeia continuar para o próximo tutorial, pode manter os recursos que configurou aqui para continuar a utilizar esta instância dos Gêmeos Digitais do Azure e a aplicação de exemplo configurada para o próximo tutorial
Se você quiser continuar usando a instância de Gêmeos Digitais do Azure, mas limpar todos os seus modelos, gêmeos e relacionamentos, poderá usar os comandos e do aplicativo de exemplo para limpar os gêmeos DeleteAllTwins e DeleteAllModels modelos em sua instância, respectivamente.

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

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

Próximos passos

Neste tutorial, você começou a usar os Gêmeos Digitais do Azure criando um gráfico em sua instância usando um aplicativo cliente de exemplo. Você criou modelos, gêmeos digitais e relacionamentos para formar um gráfico. Você também executou algumas consultas no gráfico, 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 para 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:

Conecte uma solução de ponta a ponta

Tutorial: Criar um gráfico de Gêmeos Digitais do Azure usando um aplicativo cliente de exemplo

Pré-requisitos

Obter recursos de exemplo

Preparar uma instância do Azure Digital Twins

Configurar o projeto de exemplo

Configurar credenciais locais do Azure

Executar o projeto de exemplo

Modele um ambiente físico com DTDL

Carregar modelos para os Gêmeos Digitais do Azure

Erros

Criar duplos digitais

Modificar um gêmeo digital

Criar um gráfico adicionando relações

Consultar o gráfico gêmeo para responder a perguntas sobre o ambiente

Clean up resources (Limpar recursos)

Próximos passos

Recursos adicionais