Início Rápido: Encontrar salas disponíveis usando os Gêmeos Digitais do Azure

  • Artigo

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.

O serviço Gêmeos Digitais do Azure permite que você recrie uma imagem digital de seu ambiente físico. Em seguida, você poderá ser notificado por eventos em seu ambiente e personalizar as respostas para eles.

Este início rápido usa um par de exemplos do .NET para digitalizar um prédio de escritórios imaginário. Ele mostra como encontrar salas disponíveis nesse prédio. Com os Gêmeos Digitais, você pode associar vários sensores ao ambiente. Você também pode descobrir se a qualidade do ar da sala disponível é ideal com a ajuda de um sensor de dióxido de carbono simulado. Um dos aplicativos de exemplo gera dados de sensor aleatórios para ajudá-lo a visualizar o cenário.

O vídeo a seguir resume a instalação do início rápido:

Pré-requisitos

  1. Se você ainda não tiver uma conta do Azure, crie uma conta gratuita antes de começar.

  2. Os dois consoles de aplicativo executados neste início rápido estão escritos em C#. Instale o SDK do .NET Core versão 2.1.403 ou superior no computador de desenvolvimento. Se você tiver o SDK do .NET Core instalado, verifique a versão atual do C# no computador de desenvolvimento. Execute dotnet --version em um prompt de comando.

  3. Baixe o projeto de exemplo em C#. Extraia o arquivo digital-twins-samples-csharp-master.zip.

Criar uma instância dos Gêmeos Digitais

Crie uma nova instância dos Gêmeos Digitais no portal seguindo as etapas desta seção.

  1. Entre no portal do Azure.

  2. Selecione a barra lateral inicial e, em seguida, + Criar um recurso.

    Expanda a barra lateral da página inicial e selecione + Criar um recurso

  3. Pesquise Gêmeos Digitais e selecione Gêmeos Digitais.

    Seleções para criar uma nova instância dos Gêmeos Digitais

    Como alternativa, selecione Internet das Coisas e selecione Gêmeos Digitais (versão prévia).

  4. Selecione Criar para iniciar o processo de implantação.

    Criar e confirmar a implantação do recurso

  5. 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.

      Painel Gêmeos Digitais com informações inseridas

  6. 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.

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

    Visão geral da API de Gerenciamento

Definir permissões para o aplicativo

Esta seção registra seu aplicativo de exemplo no Azure Active Directory (Azure AD) para que ele possa acessar a instância dos Gêmeos Digitais. Se você já tiver um registro de aplicativo do Azure AD, reutilize-o para o exemplo. Verifique se ele está configurado conforme descrito nesta seção.

Observação

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

  1. No portal do Azure, abra Azure Active Directory no painel esquerdo expansível e, em seguida, abra o painel Registros de aplicativo.

    Selecione o painel Azure Active Directory

  2. Selecione o botão + Novo registro.

    Selecione o botão Novo registro

  3. 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.

    Criar painel

  4. 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.

    Configuração do cliente público

  5. 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.

    Configurar URIs de Redirecionamento

    Clique em Configurar e Salvar.

  6. 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)

    ID do aplicativo do Azure Active Directory

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

      Pesquisar API ou Gêmeos Digitais do Azure

    2. Como alternativa, pesquise Azure Smart Spaces Service. Selecione a API Azure Smart Spaces Service.

      Pesquisar a API para o Azure Smart Spaces

    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.

  8. 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.

    Adicionar permissões de API

  9. 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.

    Administração aprovação de consentimento

    Verifique se Gêmeos Digitais do Azure aparece.

Compilar aplicativo

Compile o aplicativo de ocupação usando as etapas a seguir.

  1. Abra o prompt de comando. Vá para a pasta para a qual seus arquivos digital-twins-samples-csharp-master.zip foram extraídos.

  2. Execute cd occupancy-quickstart/src.

  3. Execute dotnet restore.

  4. Edite appSettings.json para atualizar as seguintes variáveis:

    • ClientId: insira a ID do aplicativo de registro de aplicativo do Azure AD anotada na seção anterior.
    • Tenant: insira a ID do diretório do locatário do Azure AD também anotada na seção anterior.
    • BaseUrl: a URL da API de Gerenciamento de sua instância dos Gêmeos Digitais está no formato https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/api/v1.0/. Substitua os espaços reservados nessa URL pelos valores da instância da seção anterior.

    Salve o arquivo atualizado.

Grafo de provisão

Esta etapa provisiona o grafo espacial dos Gêmeos Digitais com:

  • Vários espaços.
  • Um dispositivo.
  • Dois sensores.
  • Um função personalizada.
  • Uma atribuição de função.

O grafo espacial é provisionado usando o arquivo provisionSample.yaml.

  1. Execute dotnet run ProvisionSample.

    Observação

    A ferramenta de Logon do Dispositivo da CLI do Azure é usada para autenticar o usuário no Azure AD. O usuário precisa inserir um código especificado para fazer a autenticação usando a página de logon da Microsoft. Após a inserção do código, execute as etapas para se autenticar. O usuário deve fazer a autenticação quando a ferramenta estiver em execução.

    Dica

    Ao executar essa etapa, verifique se as variáveis foram copiadas corretamente caso apareça a seguinte mensagem de erro: EXIT: Unexpected error: The input is not a valid Base-64 string ...

  2. A etapa de provisionamento pode levar alguns minutos. Ela também provisiona um Hub IoT em sua instância dos Gêmeos Digitais. Ela será repetida até que o Hub IoT exiba o Status=Running.

    Provisionar o exemplo – Status=Running

  3. No final da execução, copie a ConnectionString do dispositivo para usar no exemplo do simulador de dispositivo. Copie apenas a cadeia de caracteres descrita nesta imagem.

    Copiar o cadeia de conexão

    Dica

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

Mantenha a janela do console aberta para usá-la novamente depois.

Enviar dados de sensor

Compile e execute o aplicativo do dispositivo simulador de sensor executando estas etapas.

  1. Abra um novo prompt de comando. Acesse o projeto que você baixou na pasta digital-twins-samples-csharp-master.

  2. Execute cd device-connectivity.

  3. Execute dotnet restore.

  4. Edite appsettings.json para atualizar DeviceConnectionString com a ConnectionString anterior. Salve o arquivo atualizado.

  5. Execute dotnet run para começar a enviar dados de sensor. Ele será enviado para os Gêmeos Digitais do Azure, conforme mostrado na imagem a seguir.

    Conectividade do dispositivo

  6. Deixe que esse simulador seja executado para que você possa exibir os resultados lado a lado com a ação da próxima etapa. A janela mostra os dados de sensor simulado enviados para os Gêmeos Digitais. A próxima etapa faz consultas em tempo real para encontrar salas disponíveis com ar fresco.

    Dica

    Ao executar essa etapa, verifique se DeviceConnectionString foi copiado corretamente caso a seguinte mensagem de erro aparecer: EXIT: Unexpected error: The input is not a valid Base-64 string ...

Encontrar espaços disponíveis com ar fresco

O exemplo de sensor simula os valores de dados aleatórios para dois sensores. Eles são os sensores de movimento e de dióxido de carbono. Os espaços disponíveis com ar fresco são definidos no exemplo pela ausência de dados na sala. Eles também são definidos por um nível de dióxido de carbono de, no máximo, 1.000 ppm. Se a condição não for atendida, o espaço não será considerado disponível ou a qualidade do ar será considerada ruim.

  1. Abra o prompt de comando usado para executar a etapa de provisionamento anterior.

  2. Execute dotnet run GetAvailableAndFreshSpaces.

  3. Examine esse prompt de comando e o prompt de comando dos dados do sensor lado a lado.

    O prompt de comando de dados do sensor envia dados simulados de movimento e de dióxido de carbono para os Gêmeos Digitais a cada cinco segundos. O outro prompt de comando lê o grafo em tempo real para descobrir os ambientes disponíveis com ar fresco tendo como base dados simulados aleatórios. Ele exibe uma das seguintes condições quase em tempo real com base nos dados de sensor que foram enviados da última vez:

    • Room is available and air is fresh

    • Room is not available or air quality is poor

      Obter espaços disponíveis com ar fresco

Para entender o que aconteceu neste início rápido e quais APIs foram chamadas, abra o Visual Studio Code com o projeto de workspace do código encontrado em digital-twins-samples-csharp. Use o seguinte comando:

<path>\occupancy-quickstart\src>code ..\..\digital-twins-samples.code-workspace

Os tutoriais se aprofundam no código. Eles ensinam como modificar dados de configuração e quais APIs são chamadas. Para obter mais informações sobre as APIs de Gerenciamento, vá para sua página do Swagger dos Gêmeos Digitais:

https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/swagger
Nome Substitua por
NOME_DA_SUA_INSTÂNCIA O nome da instância dos Gêmeos Digitais
SUA_LOCALIZAÇÃO A região do servidor na qual sua instância está hospedada

Ou, para sua conveniência, navegue até o Swagger dos Gêmeos Digitais.

Limpar os recursos

Os tutoriais abordam detalhes sobre como:

  • Criar um aplicativo para os gerentes das instalações aumentarem a produtividade dos ocupantes.
  • Fazer o prédio funcionar com mais eficiência.

Para continuar nos tutoriais, não limpe os recursos criados neste início rápido. Se você não planeja continuar, exclua todos os recursos criados neste início rápido.

  1. Exclua a pasta que foi criada quando você baixou o repositório de exemplo.

  2. No menu à esquerda no portal do Azure, marque Todos os recursos. Em seguida, escolha o recurso dos Gêmeos Digitais. Na parte superior do painel Todos os recursos, marque 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.

Próximas etapas

Este início rápido usou um cenário simples e aplicativos de exemplo para mostrar como os Gêmeos Digitais podem ser usados para encontrar salas com boas condições de trabalho. Para obter uma análise detalhada do cenário, leia este tutorial:

Tutorial: Implantar os Gêmeos Digitais do Azure e configurar um grafo espacial