Tutorial: Implantar a Versão Prévia dos Gêmeos Digitais do Azure e configurar um grafo espacial

Artigo
01/10/2020

Importante

Uma nova versão do serviço gêmeos digitais do Azure foi lançada. À luz dos recursos expandidos do novo serviço, o serviço original dos Gêmeos Digitais do Azure (descrito neste conjunto de documentação) foi desativado.

Para exibir a documentação do novo serviço, visite a Documentação ativa dos Gêmeos Digitais do Azure.

Você pode usar o serviço de versão prévia dos Gêmeos Digitais do Azure para reunir pessoas, lugares e dispositivos em um sistema espacial coerente. Esta série de tutoriais demonstra como usar os Gêmeos Digitais do Azure para detectar a ocupação de salas com condições ideais de temperatura e qualidade do ar.

Esses tutoriais percorrerão com você um aplicativo de console do .NET para criar o cenário de um prédio de escritórios. O prédio tem vários andares e salas em cada andar. As salas contêm dispositivos com sensores conectados que detectam movimento, temperatura ambiente e qualidade do ar.

Você aprenderá a replicar as áreas físicas e entidades no prédio como objetos digitais usando o serviço Gêmeos Digitais do Azure. Você simulará eventos de dispositivo usando outro aplicativo de console. Em seguida, você aprenderá a monitorar os eventos provenientes dessas áreas físicas e entidades quase em tempo real.

Um administrador do escritório pode usar essas informações para ajudar um funcionário que trabalhe no prédio a reservar salas de reunião com condições ideais. Um gerente de instalações comerciais pode usar a configuração para obter tendências de uso de salas e monitorar as condições de trabalho para fins de manutenção.

No primeiro tutorial desta série, você aprenderá a:

Implantar os Gêmeos Digitais.
Conceder permissões ao aplicativo.
Modificar um aplicativo de exemplo dos Gêmeos Digitais.
Provisionar o prédio.

Estes tutoriais usam e modificam os mesmos exemplos que o início rápido para encontrar salas disponíveis usa, para uma cobertura mais detalhada e aprofundada dos conceitos.

Pré-requisitos

Uma assinatura do Azure. Se você ainda não tem uma conta do Azure, crie uma conta gratuita.
O SDK do .NET Core. Os exemplos dos Gêmeos Digitais do Azure usados nestes tutoriais estão escritos em C#. Instale o SDK do .NET Core versão 2.1.403 ou posterior no computador de desenvolvimento para executar a amostra. Verifique se a versão correta está instalada em seu computador executando dotnet --version em uma janela de comando.
Use o Visual Studio Code para explorar o código de exemplo.

Implantar Gêmeos Digitais

Use as etapas nesta seção para criar uma nova instância do serviço Gêmeos Digitais do Azure. Apenas uma instância pode ser criada por assinatura. Vá para a próxima seção se você já tiver uma em execução.

Entre no portal do Azure.
Selecione a barra lateral inicial e, em seguida, + Criar um recurso.
Pesquise Gêmeos Digitais e selecione Gêmeos Digitais.

Como alternativa, selecione Internet das Coisas e selecione Gêmeos Digitais (versão prévia).
Selecione Criar para iniciar o processo de implantação.
No painel Gêmeos Digitais, insira as seguintes informações:
- Nome do recurso: criar um nome exclusivo para sua instância de Gêmeos Digitais.
- Assinatura: escolha a assinatura que deseja usar para criar essa instância de Gêmeos Digitais.
- Grupo de recursos: selecione ou crie um grupo de recursos para a instância de Gêmeos Digitais.
- Local: selecione o local mais próximo de seus dispositivos.
Examine as informações de Gêmeos Digitais e, em seguida, selecione Criar. Sua instância de Gêmeos Digitais pode levar alguns minutos para ser criada. Você pode monitorar o progresso no painel Notificações.
Abra o painel Visão geral da sua instância de Gêmeos Digitais. Observe o link em API de Gerenciamento. A URL da API de Gerenciamento é formatada como:
```
https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/swagger
```
Esta URL leva você até a documentação da API REST de Gêmeos Digitais do Azure que se aplica à sua instância. Leia Como usar o Swagger dos Gêmeos Digitais do Azure para aprender a ler e usar essa documentação da API. Copie e modifique a URL da API de Gerenciamento para este formato:
```
https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/api/v1.0/
```
Seu aplicativo usará a URL modificada como a URL base para acessar a instância. Copie esta URL modificada para um arquivo temporário. Você precisará disso nas próximas seções.

Conceder permissões ao aplicativo

Os Gêmeos Digitais usam o Azure AD (Azure Active Directory) para controlar o acesso de leitura/gravação ao serviço. Todo aplicativo que precise se conectar à instância dos Gêmeos Digitais deve estar registrado no Azure AD. As etapas nesta seção mostram como registrar seu aplicativo de exemplo.

Se você já tiver um registro de aplicativo, poderá reutilizá-lo para o exemplo. No entanto, percorra esta seção para ter certeza de que o registro do aplicativo está configurado corretamente.

Observação

Esta seção fornece instruções para o registro de aplicativo do Azure AD.

No portal do Azure, abra Azure Active Directory no painel esquerdo expansível e, em seguida, abra o painel Registros de aplicativo.
Selecione o botão + Novo registro.
Dê um nome amigável para esse registro de aplicativo na caixa Nome.
1. Na seção URI de redirecionamento (opcional), insira https://microsoft.com na caixa de texto.
2. Verifique quais contas e locatários são compatíveis com seu aplicativo do Microsoft Azure Active Directory.
3. Selecione Registrar.
A folha Autenticação especifica as configurações de autenticação importantes.
1. Adicione os URIs de redirecionamento e configure os Tokens de acesso selecionando + Adicionar uma plataforma.
2. Selecione Sim para especificar que o aplicativo é um cliente público.
3. Verifique quais contas e locatários são compatíveis com seu aplicativo do Microsoft Azure Active Directory.
Depois de selecionar a plataforma apropriada, configure seus URIs de redirecionamento e Tokens de acesso no painel lateral à direita da interface do usuário.
1. Os URIs de Redirecionamento devem corresponder ao endereço fornecido pela solicitação de autenticação:
  - Para aplicativos hospedados em um ambiente de desenvolvimento local, selecione Cliente público (móvel e desktop) . Lembre-se de definir cliente público como Sim.
  - Para aplicativos de página única hospedados no Serviço de Aplicativo do Azure, selecione Web.
2. Determine se uma URL de logout é apropriada.
3. Habilite o fluxo de concessão implícita marcando Tokens de acesso ou Tokens de ID.
Clique em Configurar e Salvar.
Abra o painel Visão geral do seu aplicativo registrado e copie os valores das entidades a seguir para um arquivo temporário. Você usará esses valores para configurar seu aplicativo de exemplo nas seções a seguir.
- ID do aplicativo (cliente)
- ID do diretório (locatário)
Abra o painel Permissões de API para o registro do aplicativo. Selecione o botão + Adicionar uma permissão. No painel Solicitar permissões de API, selecione a guia APIs que a minha organização usa e pesquise pelo seguinte:
1. Azure Digital Twins. Selecione a API de Gêmeos Digitais do Azure.
2. Como alternativa, pesquise Azure Smart Spaces Service. Selecione a API Azure Smart Spaces Service.
Importante

A ID e o nome da API do Azure AD que serão exibidos dependerão do locatário:
- As contas de locatário e cliente de teste devem pesquisar Azure Digital Twins.
- Outras contas Microsoft devem pesquisar Azure Smart Spaces Service.
Qualquer uma das APIs, uma vez selecionada, será exibida como Gêmeos Digitais do Azure, no mesmo painel Solicitar permissões de API. Selecione a opção suspensa Leitura e marque a caixa de seleção Leitura.Gravação. Selecione o botão Adicionar permissões.
Dependendo das configurações da sua organização, talvez você precise seguir etapas adicionais para conceder acesso de administrador a essa API. Entre em contato com seu administrador para obter mais informações. Assim que o acesso de administrador for aprovado, a coluna Consentimento do Administrador Necessário no painel de Permissões da API exibirá suas permissões.

Verifique se Gêmeos Digitais do Azure aparece.

Configurar o exemplo dos Gêmeos Digitais

Esta seção explora um aplicativo dos Gêmeos Digitais do Azure que se comunica com as APIs REST dos Gêmeos Digitais.

Baixar o exemplo

Se você já tem os exemplos baixados do início rápido para encontrar salas disponíveis, pode ignorar estas etapas.

Baixe os exemplos do .NET dos Gêmeos Digitais.
Extraia o conteúdo da pasta ZIP em seu computador.

Explorar o exemplo

Na pasta de exemplo extraída, abra o arquivo digital-twins-samples-csharp\digital-twins-samples.code-workspace no Visual Studio Code. Ele contém dois projetos:

Você pode usar o exemplo de provisionamento occupancy-quickstart para configurar e provisionar um grafo de inteligência espacial. Esse grafo é a imagem digitalizada de seus espaços físicos e os recursos presentes neles. Ele usa um modelo de objeto que define objetos de um prédio inteligente. Para obter uma lista completa das APIs REST e dos objetos dos Gêmeos Digitais, confira esta documentação da API REST ou a URL da API de Gerenciamento que foi criada para sua instância.

Para explorar o exemplo e ver como ele se comunica com sua instância dos Gêmeos Digitais, você pode começar pela pasta src\actions. Os arquivos na pasta implementam os comandos que você usará nestes tutoriais:
- O arquivo provisionSample.cs mostra como provisionar o grafo espacial.
- O arquivo getSpaces.cs obtém informações sobre os espaços provisionados.
- O arquivo getAvailableAndFreshSpaces.cs obtém os resultados de uma função personalizada chamada de função definida pelo usuário.
- O arquivo createEndpoints.cs cria pontos de extremidade para interagir com outros serviços.
O exemplo de simulação device-connectivity simula dados de sensor e o envia para o hub IoT que está provisionado para a instância dos Gêmeos Digitais. Você usará essa amostra no próximo tutorial depois de provisionar o grafo espacial. Os identificadores de sensores e dispositivos que você usou para configurar este exemplo devem ser os mesmos que serão usados para provisionar o grafo.

Configurar o exemplo de provisionamento

Abra uma janela de comando e vá para o exemplo baixado. Execute o comando a seguir:
```
cd occupancy-quickstart/src
```
Restaure as dependências para o projeto de exemplo executando este comando:
```
dotnet restore
```
No Visual Studio Code, abra o arquivo appSettings.json no projeto occupancy-quickstart. Atualize os seguintes valores:
- ClientId: insira a ID de aplicativo do registro de seu aplicativo do Azure AD. Você anotou essa ID na seção onde definiu permissões de aplicativo.
- Tenant: insira a ID de diretório de seu locatário do Azure AD. Você também anotou essa ID na seção onde definiu permissões de aplicativo.
- BaseUrl: insira a URL da instância dos Gêmeos Digitais. Para obter essa URL, substitua os espaços reservados nessa URL pelos valores da instância: https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/api/v1.0/. Você também pode obter essa URL modificando a URL da API de Gerenciamento na seção de implantação. Substitua swagger/ por api/v1.0/.
Examine uma lista de recursos dos Gêmeos Digitais que você pode explorar usando o exemplo. Execute o comando a seguir:
```
dotnet run
```

Entender o processo de provisionamento

Esta seção mostra como o exemplo provisiona um grafo espacial de um prédio.

No Visual Studio Code, navegue até a pasta occupancy-quickstart\src\actions e abra o arquivo provisionSample.cs. Observe a seguinte função:

public static async Task<IEnumerable<ProvisionResults.Space>> ProvisionSample(HttpClient httpClient, ILogger logger)
{
    IEnumerable<SpaceDescription> spaceCreateDescriptions;
    using (var r = new StreamReader("actions/provisionSample.yaml"))
    {
        spaceCreateDescriptions = await GetProvisionSampleTopology(r);
    }

    var results = await CreateSpaces(httpClient, logger, spaceCreateDescriptions, Guid.Empty);

    Console.WriteLine($"Completed Provisioning: {JsonConvert.SerializeObject(results, Formatting.Indented)}");

    return results;
}

Essa função usa provisionSample.yaml na mesma pasta. Abra esse arquivo e observe a hierarquia de um prédio comercial: Local, Andar, Área e Salas. Qualquer um desses espaços físicos pode conter dispositivos e sensores. Cada entrada tem um predefinido type, por exemplo, Floor, Room.

O arquivo de exemplo yaml mostra um grafo espacial que usa o modelo de objeto dos Gêmeos Digitais Default. Esse modelo fornece nomes genéricos para a maioria dos tipos. Os nomes genéricos são suficientes para um prédio. Os exemplos incluem Temperature para SensorDataType e Map para SpaceBlobType. Um tipo de espaço de exemplo é Room, com subtipos FocusRoom, ConferenceRoom e assim por diante.

Se você precisou criar um grafo espacial para um local de tipo diferente, como uma fábrica, talvez seja necessário usar um modelo de objeto diferente. Execute o comando dotnet run GetOntologies na linha de comando do exemplo de provisionamento para saber quais modelos estão disponíveis para uso.

Para obter mais informações sobre grafos espaciais e modelos de objeto, leia Noções básicas sobre modelos de objeto e grafo de inteligência espacial dos Gêmeos Digitais.

Modificar grafo espacial de exemplo

O arquivo provisionSample.yaml contém os seguintes nós:

resources: o nó resources cria um recurso do Hub IoT do Azure para se comunicar com os dispositivos em sua configuração. Um hub IoT no nó raiz do grafo pode se comunicar com todos os dispositivos e sensores no grafo.
spaces: no modelo de objeto dos Gêmeos Digitais, spaces representa os locais físicos. Cada espaço tem um Type— por exemplo, Região, Local ou Cliente — e um amigável Name. Os espaços podem pertencer a outros espaços, criando uma estrutura hierárquica. O arquivo provisionSample.yaml tem um grafo espacial de um prédio imaginário. Observe o aninhamento lógico dos espaços do tipo Floor em Venue, Area em um andar e nós Room em uma área.
devices: os espaços podem conter devices, que são entidades físicas ou virtuais que gerenciam uma quantidade de sensores. Por exemplo, um dispositivo pode ser o telefone de um usuário, um pod de sensor Raspberry Pi ou um gateway. No prédio imaginário do exemplo, observe como a sala chamada Sala de Foco contém um dispositivo Raspberry Pi 3 A1. Cada nó do dispositivo é identificado por um único hardwareId, que está codificado no exemplo. Para configurar esse exemplo para uma produção real, substitua-os pelos valores de sua configuração.
sensors: um dispositivo pode conter vários sensors. Eles podem detectar e registrar alterações físicas, como temperatura, movimento e nível de bateria. Cada nó de sensor é identificado exclusivamente por um hardwareId, que, no nosso caso, está no código. Em um aplicativo real, substitua-os usando os identificadores exclusivos dos sensores da instalação. O arquivo provisionSample.yaml tem dois sensores para gravar Motion e CarbonDioxide. Adicione outro sensor para registrar a Temperatura, adicionando as linhas a seguir abaixo das linhas do sensor CarbonDioxide. Eles são fornecidos em provisionSample.yaml como linhas comentadas. Você pode remover os comentários removendo o caractere # na frente de cada linha.
```
        - dataType: Temperature
          hardwareId: SAMPLE_SENSOR_TEMPERATURE
```
Observação

Verifique se as chaves dataType e hardwareId também estão alinhadas com as instruções acima desse snippet. Verifique também se o editor não substitui espaços por tabulações.

Salve e feche o arquivo provisionSample.yaml. No próximo tutorial, você adicionará outras informações a esse arquivo e provisionará o prédio de exemplo dos Gêmeos Digitais do Azure.

Dica

É possível exibir e modificar seu grafo espacial usando o Visualizador de Grafos dos Gêmeos Digitais do Azure.

Limpar os recursos

Se você quiser parar de explorar os Gêmeos Digitais do Azure neste momento, fique à vontade para excluir recursos criados neste tutorial:

No menu à esquerda no portal do Azure, escolha Todos os recursos, marque o grupo de recursos dos Gêmeos Digitais e a opção Excluir.

Dica

Se você teve problemas para excluir sua instância de Gêmeos Digitais, lançamos uma atualização de serviço com a correção. Tente novamente excluir a instância.
Se necessário, exclua o aplicativo de exemplo em seu computador de trabalho.

Próximas etapas

Para saber como implementar uma lógica personalizada para monitorar as condições do prédio de exemplo, vá para o próximo tutorial da série:

Tutorial: Provisionar o prédio e monitorar as condições de trabalho

Compartilhar via