Tutorial: Implementar a Pré-visualização do Azure Digital Twins e configurar um gráfico espacial

Artigo
01/10/2020

Importante

Foi lançada uma nova versão do serviço Azure Digital Twins. À luz das capacidades expandidas do novo serviço, o serviço original do Azure Digital Twins (descrito neste conjunto de documentação) foi descontinuado.

Para ver a documentação do novo serviço, visite a Documentação ativa do Azure Digital Twins.

Pode utilizar o serviço de Pré-visualização do Azure Digital Twins para reunir pessoas, locais e dispositivos num sistema espacial coerente. Esta série de tutoriais demonstra como utilizar o Azure Digital Twins para detetar a ocupação de salas com condições ideais de temperatura e qualidade do ar.

Estes tutoriais irão guiá-lo através de uma aplicação de consola .NET para criar um cenário de um edifício de escritórios. O edifício tem vários pisos e salas em cada piso. As salas contêm dispositivos com sensores ligados que detetam movimento, temperatura ambiente e qualidade do ar.

Irá aprender a replicar as áreas físicas e as entidades no edifício como objetos digitais com o serviço Azure Digital Twins. Irá simular eventos de dispositivos com outra aplicação de consola. Em seguida, irá aprender a monitorizar os eventos provenientes destas áreas físicas e entidades em tempo quase real.

O administrador dos escritórios pode utilizar estas informações para ajudar os funcionários que trabalham neste edifício a reservarem salas de reuniões com as condições ideais. Um gestor de instalações do Office pode utilizar a sua configuração para obter tendências de utilização das salas e para monitorizar as condições de trabalho para fins de manutenção.

No primeiro tutorial da série, vai aprender a:

Implementar o Digital Twins.
Conceda permissões à sua aplicação.
Modificar uma aplicação de exemplo do Digital Twins.
Aprovisione o seu edifício.

Estes tutoriais utilizam e modificam os mesmos exemplos que o artigo Quickstart to find available rooms (início rápido para descobrir salas disponíveis) utiliza, para proporcionar uma cobertura mais detalhada e aprofundada dos conceitos.

Pré-requisitos

Uma subscrição do Azure. Se não tiver uma conta do Azure, crie uma conta gratuita.
O SDK .NET Core. Os exemplos do Azure Digital Twins utilizados nestes tutoriais são escritos em C#. Certifique-se de que instala o SDK .NET Core versão 2.1.403 ou posterior no seu computador de desenvolvimento para criar e executar o exemplo. Verifique se a versão certa está instalada no seu computador ao executar dotnet --version numa janela de comandos.
Visual Studio Code, para explorar o código de exemplo.

Implementar o Digital Twins

Utilize os passos nesta secção para criar uma nova instância do serviço Azure Digital Twins. Só é possível criar uma instância por subscrição. Avance para a secção seguinte se já tiver uma em execução.

Inicie sessão no portal do Azure.
Selecione a barra lateral da casa e, em seguida, + Criar um recurso.
Procure Digital Twins e selecione Digital Twins.

Em alternativa, selecione Internet das Coisas e selecione Digital Twins (pré-visualização).
Selecione Criar para iniciar o processo de implementação.
No painel Digital Twins, introduza as seguintes informações:
- Nome do Recurso: crie um nome exclusivo para a instância do Digital Twins.
- Subscrição: escolha a subscrição que quer utilizar para criar esta instância do Digital Twins.
- Grupo de recursos: selecione ou crie um grupo de recursos para a instância do Digital Twins.
- Localização: selecione a localização mais próxima dos seus dispositivos.
Reveja as informações do Digital Twins e, em seguida, selecione Criar. A sua instância do Digital Twins poderá demorar alguns minutos a ser criada. Pode monitorizar o progresso no painel Notificações.
Abra o painel Descrição geral da instância do Digital Twins. Anote a ligação em API de Gestão. O URL da API de Gestão está formatado como:
```
https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/swagger
```
Este URL leva-o para a documentação da API REST do Azure Digital Twins que se aplica à sua instância. Leia Como utilizar o Azure Digital Twins Swagger para saber como ler e utilizar esta documentação de API. Copie e modifique o URL da API de Gestão para este formato:
```
https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/api/v1.0/
```
A aplicação irá utilizar o URL modificado como URL base para aceder à sua instância. Copie este URL modificado para um ficheiro temporário. Irá precisar disto na secção seguinte.

Conceder permissões à sua aplicação

O Digital Twins utiliza o Azure Active Directory (Azure AD) para controlar o acesso de leitura/escrita ao serviço. Qualquer aplicação que precise de se ligar à sua instância do Digital Twins tem de estar registada com Azure AD. Os passos nesta secção explicam como registar o exemplo de aplicação.

Se já tiver um registo de aplicação, pode reutilizá-lo no seu exemplo. No entanto, leia esta secção para ter a certeza de que esse registo está devidamente configurado.

Nota

Esta secção fornece instruções para Azure AD registo de aplicações.

No portal do Azure, abra o Azure Active Directory a partir do menu esquerdo expansível e, em seguida, abra o painel Registos de aplicações.
Selecione o botão + Novo registo .
Atribua um nome amigável para este registo de aplicação na caixa Nome .
1. Na secção URI de Redirecionamento (opcional ), introduza https://microsoft.com na caixa de texto.
2. Verifique que contas e inquilinos são suportados pela sua aplicação do Azure Active Directory.
3. Selecione Registar.
O painel Autenticação especifica definições de configuração de autenticação importantes.
1. Adicione URIs de Redirecionamento e configure Tokens de Acesso ao selecionar + Adicionar uma plataforma.
2. Selecione Sim para especificar que a aplicação é um cliente público.
3. Verifique que contas e inquilinos são suportados pela sua aplicação do Azure Active Directory.
Depois de selecionar a plataforma adequada, configure os URIs de Redirecionamento e os Tokens de Acesso no painel lateral à direita da interface de utilizador.
1. Os URIs de redirecionamento têm de corresponder ao endereço fornecido pelo pedido de autenticação:
  - Para aplicações alojadas num ambiente de desenvolvimento local, selecione Cliente público (mobile & ambiente de trabalho). Certifique-se de que define o cliente público como Sim.
  - Para Single-Page Aplicações alojadas no Serviço de Aplicações do Azure, selecione Web.
2. Determine se um URL de Fim de Sessão é adequado.
3. Ative o fluxo de concessão implícito ao verificar tokens de acesso ou tokens de ID.
Clique em Configurar e, em seguida, em Guardar.
Abra o painel Descrição geral da sua aplicação registada e copie os valores das seguintes entidades para um ficheiro temporário. Irá utilizar estes valores para configurar a sua aplicação de exemplo nas secções seguintes.
- ID da Aplicação (cliente)
- ID do Diretório (inquilino)
Abra o painel de permissões da API para o registo da sua aplicação. Selecione + Adicionar um botão de permissão . No painel Pedir permissões da API , selecione o separador APIs que a minha organização utiliza e, em seguida, procure uma das seguintes opções:
1. Azure Digital Twins. Selecione a API do Azure Digital Twins .
2. Em alternativa, procure Azure Smart Spaces Service. Selecione a API de Serviço de Espaços Inteligentes do Azure .
Importante

O nome e o ID da API Azure AD que serão apresentados dependem do seu inquilino:
- As contas de cliente e inquilino de teste devem procurar Azure Digital Twins.
- Outras contas Microsoft devem procurar Azure Smart Spaces Service.
Qualquer uma das API aparecerá como Azure Digital Twins no mesmo painel Pedir permissões da API uma vez selecionada. Selecione a opção pendente Ler e, em seguida, selecione a caixa de verificação Ler.Escrever . Selecione o botão Adicionar permissões .
Dependendo das definições da sua organização, poderá ter de tomar medidas adicionais para conceder acesso de administrador a esta API. Contacte o administrador para obter mais informações. Assim que o acesso de administrador for aprovado, a coluna Consentimento Administração Obrigatório no painel de permissões da API apresentará as suas permissões.

Verifique se o Azure Digital Twins é apresentado.

Configurar o exemplo do Digital Twins

Esta secção orienta-o através de uma aplicação do Azure Digital Twins que comunica com as APIs REST do Digital Twins.

Transferir o exemplo

Se já tiver transferido os exemplos para Quickstart to find available rooms (Início rápido para descobrir salas disponíveis), pode ignorar estes passos.

Transfira os exemplos de .NET do Digital Twins.
Extraia o conteúdo da pasta zip no seu computador.

Explorar o exemplo

Na pasta de exemplo extraída, abra o ficheiro digital-twins-samples-csharp\digital-twins-samples.code-workspace no Visual Studio Code. Inclui dois projetos:

Pode utilizar o exemplo de aprovisionamento occupancy-quickstart para configurar e aprovisionar um gráfico de inteligência espacial. Este gráfico é a imagem digitalizada dos seus espaços físicos e dos recursos neles contidos. Utiliza um modelo de objeto, que define objetos para um edifício inteligente. Para obter uma lista completa dos objetos e das APIs REST do Digital Twins, veja esta documentação da API REST ou o URL API de Gestão que foi criado para a sua instância.

Para explorar o exemplo para compreender como comunica com a sua instância do Digital Twins, pode começar com a pasta src\actions . Os ficheiros nesta pasta implementam os comandos que irá utilizar nestes tutoriais:
- O ficheiro provisionSample.cs mostra como aprovisionar o gráfico espacial.
- O ficheiro getSpaces.cs obtém informações sobre os espaços aprovisionados.
- O ficheiro getAvailableAndFreshSpaces.cs obtém os resultados de uma função personalizada denominada função definida pelo utilizador.
- O ficheiro createEndpoints.cs cria pontos finais para interagir com outros serviços.
O exemplo de simulação de conectividade do dispositivo simula os dados do sensor e envia-os para o hub IoT aprovisionado para a instância do Digital Twins. Irá utilizar este exemplo no próximo tutorial depois de aprovisionar o gráfico espacial. Os identificadores do sensor e do dispositivo que utiliza para configurar este exemplo devem ser os mesmos que irá utilizar para aprovisionar o gráfico.

Configurar o exemplo de aprovisionamento

Abra uma janela de comandos e aceda ao exemplo transferido. Execute o seguinte comando:
```
cd occupancy-quickstart/src
```
Execute o comando seguinte para restaurar as dependências para o exemplo de projeto:
```
dotnet restore
```
No Visual Studio Code, abra o ficheiro appSettings.json no projeto occupancy-quickstart . Atualize os seguintes valores:
- ClientId: introduza o ID da aplicação do Azure AD registo da aplicação. Anotou este ID na secção onde definiu as permissões da aplicação.
- Inquilino: introduza o ID de diretório do seu inquilino Azure AD. Também anotou este ID na secção onde definiu as permissões da aplicação.
- BaseUrl: introduza o URL da instância do Digital Twins. Para obter este URL, substitua os marcadores de posição no mesmo elos valores da sua instância, https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/api/v1.0/. Também pode obter este URL ao modificar o URL da API de Gestão a partir da secção de implementação. Substitua swagger/ por api/v1.0/.
Reveja uma lista de funcionalidades do Digital Twins que pode explorar com o exemplo. Execute o seguinte comando:
```
dotnet run
```

Compreender o processo de aprovisionamento

Esta secção mostra de que forma é que o exemplo aprovisiona um gráfico espacial de um edifício.

No Visual Studio Code, navegue para a pasta occupancy-quickstart\src\actions e abra o ficheiro provisionSample.cs. Repare na função seguinte:

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;
}

Esta função utiliza provisionSample.yaml na mesma pasta. Abra este ficheiro e anote a hierarquia de um edifício de escritórios: Local, Piso, Área e Salas. Qualquer um destes espaços físicos pode ter dispositivos e sensores. Cada entrada tem um predefinido type, por exemplo, Piso, Sala.

O ficheiro yaml de exemplo mostra um gráfico espacial que utiliza o modelo de objetos do Default Digital Twins. Este modelo fornece nomes genéricos para a maioria dos tipos. Os nomes genéricos são suficientes para um edifício. Os exemplos são Temperature for SensorDataType e Map for SpaceBlobType. Um tipo de espaço de exemplo é Sala com subtipos FocusRoom, ConferenceRoom, etc.

Se tiver de criar um gráfico espacial para outro tipo de local, como uma fábrica, poderá ter de utilizar um modelo de objetos diferente. Pode descobrir que modelos estão disponíveis para utilizar ao executar o comando dotnet run GetOntologies na linha de comandos do exemplo de aprovisionamento.

Para obter mais informações sobre grafos espaciais e modelos de objetos, leia Understanding Digital Twins object models and spatial intelligence graph (Compreender os modelos de objetos do Digital Twins e o gráfico de inteligência espacial).

Modificar o gráfico espacial de exemplo

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

recursos: o resources nó cria um recurso Hub IoT do Azure para comunicar com os dispositivos na sua configuração. Um hub IoT no nó raiz do gráfico pode comunicar com todos os dispositivos e sensores no gráfico.
spaces: no modelo de objetos do Digital Twins, spaces representa as localizações físicas. 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 ficheiro provisionSample.yaml tem um gráfico espacial de um edifício imaginário. Repare no aninhamento lógico de espaços do tipo Floor dentro de , Area num piso e RoomVenuenós numa área.
devices: os espaços podem conter devices, que são entidades físicas ou virtuais que gerem vários sensores. Por exemplo, um dispositivo pode ser o telemóvel de um utilizador, um pod do sensor Raspberry Pi ou um gateway. No edifício imaginário do exemplo, repare que a sala denominada Focus Room contém um dispositivo Raspberry Pi 3 A1. Cada nó do dispositivo é identificado por um hardwareId exclusivo, que está codificado no exemplo. Para configurar este exemplo para uma produção real, substitua estes valores pelos da sua configuração.
sensores: um dispositivo pode conter vários sensors. Podem detetar e registar alterações físicas, como temperatura, movimento e nível de bateria. Cada nó do sensor é identificado exclusivamente por um hardwareId, que está codificado aqui. Para uma aplicação real, substitua-as com os identificadores exclusivos dos sensores na sua configuração. O ficheiro provisionSample.yaml tem dois sensores para registar Motion (Movimento) e CarbonDioxide (Dióxido de Carbono). Adicione outro sensor para registar a Temperature (Temperatura) ao adicionar as linhas seguintes, abaixo das do sensor CarbonDioxide. Estes são fornecidos em provisionSample.yaml como linhas comentadas. Pode anular os comentários ao remover o # caráter na frente de cada linha.
```
        - dataType: Temperature
          hardwareId: SAMPLE_SENSOR_TEMPERATURE
```
Nota

Certifique-se de que as dataType teclas e hardwareId estão alinhadas com as instruções acima deste fragmento. Confirme também que o editor não substitui espaços por tabulações.

Guarde e feche o ficheiro provisionSample.yaml. No próximo tutorial, irá adicionar mais informações a este ficheiro e, em seguida, aprovisionar o seu exemplo de compilação do Azure Digital Twins.

Dica

Pode ver e modificar o gráfico espacial com o Visualizador do Graph do Azure Digital Twins.

Limpar os recursos

Se quiser parar de explorar o Azure Digital Twins neste momento, não hesite em eliminar recursos criados neste tutorial:

No menu esquerdo do portal do Azure, selecione Todos os recursos, selecione o seu grupo de recursos Digital Twins e selecione Eliminar.

Dica

Se teve problemas ao eliminar a instância do Digital Twins, foi implementada uma atualização de serviço com a correção. Repita a eliminação da instância.
Se necessário, elimine a aplicação de exemplo no seu computador de trabalho.

Passos seguintes

Para saber como implementar uma lógica personalizada para monitorizar as condições no seu exemplo de criação, aceda ao próximo tutorial da série:

Tutorial: Provision your building and monitor working conditions (Tutorial: Aprovisionar o edifício e monitorizar as condições de funcionamento)

Partilhar via