Tutorial: Provisionar seu prédio e monitorar as condições de trabalho com a Versão prévia dos Gêmeos Digitais do AzureTutorial: Provision your building and monitor working conditions with Azure Digital Twins Preview

Este tutorial demonstra como usar a Versão prévia dos Gêmeos Digitais do Azure para monitorar as condições de temperatura e o nível de conforto desejados em seus espaços.This tutorial demonstrates how to use Azure Digital Twins Preview to monitor your spaces for desired temperature conditions and comfort level. Depois de configurar o prédio de exemplo, provisione o prédio e execute funções personalizadas em seus dados de sensor usando as etapas deste tutorial.After you configure your sample building, you can provision your building and run custom functions on your sensor data by using the steps in this tutorial.

Neste tutorial, você aprenderá como:In this tutorial, you learn how to:

  • Definir condições a serem monitoradas.Define conditions to monitor.
  • Criar uma UDF (função definida pelo usuário).Create a user-defined function (UDF).
  • Simular dados de sensor.Simulate sensor data.
  • Obter resultados de uma função definida pelo usuário.Get results of a user-defined function.

Pré-requisitosPrerequisites

Este tutorial pressupõe que você já tenha concluído a configuração dos Gêmeos Digitais do Azure.This tutorial assumes that you have finished your Azure Digital Twins setup. Antes de prosseguir, verifique se você tem:Before proceeding, make sure that you have:

Dica

Use um nome de instância dos Gêmeos Digitais exclusivo quando estiver provisionando uma nova instância.Use a unique Digital Twins instance name if you're provisioning a new instance.

Definir condições a serem monitoradasDefine conditions to monitor

Você pode definir um conjunto de condições específicas a monitorar nos dados de dispositivo ou sensor, chamadas correspondências.You can define a set of specific conditions to monitor in the device or sensor data, called matchers. Em seguida, você pode definir funções chamadas funções definidas pelo usuário.You can then define functions called user-defined functions. As funções definidas pelo usuário executam a lógica personalizada nos dados oriundos de seus dispositivos e espaços quando as condições especificadas pelas correspondências são atendidas.User-defined functions execute custom logic on data that comes from your spaces and devices, when the conditions specified by the matchers occur. Para obter mais informações, leia Processamento de dados e funções definidas pelo usuário.For more information, read Data processing and user-defined functions.

No projeto de exemplo occupancy-quickstart, abra o arquivo src\actions\provisionSample.yaml no Visual Studio Code.From the occupancy-quickstart sample project, open the file src\actions\provisionSample.yaml in Visual Studio Code. Observe a seção que começa com o tipo de matchers.Note the section that begins with the type matchers. Cada entrada nesse tipo cria uma correspondência com o Nome especificado.Each entry under this type creates a matcher with the specified Name. A correspondência monitorará um sensor do tipo dataTypeValue.The matcher will monitor a sensor of type dataTypeValue. Observe como ela se relaciona com o espaço chamado Sala de Foco A1, que tem um nó devices contendo alguns sensores.Notice how it relates to the space named Focus Room A1, which has a devices node that contains a few sensors. Para provisionar uma correspondência que vai controlar um desses sensores, seu dataTypeValue deverá corresponder ao dataType do sensor.To provision a matcher that will track one of these sensors, make sure that its dataTypeValue matches the sensor's dataType.

Adicione a seguinte correspondência abaixo das correspondências existentes.Add the following matcher below the existing matchers. Verifique se as chaves estão alinhadas e se os espaços não foram substituídos por guias.Make sure the keys are aligned and spaces are not replaced by tabs. Essas linhas também estão presentes no arquivo provisionSample.yaml como linhas comentadas.These lines are also present in the provisionSample.yaml file as commented-out lines. Você pode remover os comentários removendo o caractere # na frente de cada linha.You can uncomment them by removing the # character in front of each line.

      - name: Matcher Temperature
        dataTypeValue: Temperature

Essa correspondência controlará o sensor SAMPLE_SENSOR_TEMPERATURE que você adicionou no primeiro tutorial.This matcher will track the SAMPLE_SENSOR_TEMPERATURE sensor that you added in the first tutorial.

Criar uma função definida pelo usuárioCreate a user-defined function

Você pode usar as funções definidas pelo usuário para personalizar o processamento de seus dados de sensor.You can use user-defined functions to customize the processing of your sensor data. Elas são um código JavaScript personalizado que pode ser executado dentro da instância dos Gêmeos Digitais do Azure quando ocorrem condições específicas descritas pelas correspondências.They're custom JavaScript code that can run within your Azure Digital Twins instance, when specific conditions as described by the matchers occur. Você pode criar correspondências e funções definidas pelo usuário para cada sensor que deseja monitorar.You can create matchers and user-defined functions for each sensor that you want to monitor. Para obter mais informações, leia Processamento de dados e funções definidas pelo usuário.For more information, read Data processing and user-defined functions.

No arquivo de exemplo provisionSample.yaml, procure uma seção que começa com o tipo userdefinedfunctions.In the sample provisionSample.yaml file, look for a section that begins with the type userdefinedfunctions. Esta seção provisiona uma função definida pelo usuário com determinado Nome.This section provisions a user-defined function with a given Name. Essa UDF atua na lista de correspondências em matcherNames.This UDF acts on the list of matchers under matcherNames. Observe como você pode fornecer seu próprio arquivo JavaScript para a UDF como o script.Notice how you can provide your own JavaScript file for the UDF as the script.

Além disso, observe a seção denominada roleassignments.Also note the section named roleassignments. Ela atribui a função de Administrador de Espaço à função definida pelo usuário.It assigns the Space Administrator role to the user-defined function. Essa função permite que ela acesse os eventos que vêm de um dos espaços provisionados.This role allows it to access the events that come from any of the provisioned spaces.

  1. Configure a UDF para incluir a correspondência de temperatura adicionando ou removendo marcas de comentários na seguinte linha no nó matcherNames do arquivo provisionSample.yaml:Configure the UDF to include the temperature matcher by adding or uncommenting the following line in the matcherNames node of the provisionSample.yaml file:

            - Matcher Temperature
    
  2. Abra o arquivo src\actions\userDefinedFunctions\availability.js em seu editor.Open the file src\actions\userDefinedFunctions\availability.js in your editor. Esse é o arquivo referenciado no elemento script de provisionSample.yaml.This is the file referenced in the script element of provisionSample.yaml. A função definida pelo usuário nesse arquivo procura condições quando nenhum movimento é detectado na sala e quando os níveis de dióxido de carbono estão abaixo de 1.000 ppm.The user-defined function in this file looks for conditions when no motion is detected in the room and carbon dioxide levels are below 1,000 ppm.

    Modifique o arquivo JavaScript para monitorar a temperatura e outras condições.Modify the JavaScript file to monitor temperature and other conditions. Adicione as linhas de código a seguir para procurar condições quando nenhum movimento é detectado na sala, os níveis de dióxido de carbono estão abaixo de 1.000 ppm e a temperatura está abaixo de 25 graus Celsius.Add the following lines of code to look for conditions when no motion is detected in the room, carbon dioxide levels are below 1,000 ppm, and temperature is below 78 degrees Fahrenheit.

    Observação

    Esta seção modifica o arquivo src\actions\userDefinedFunctions\availability.js para que você possa saber com detalhes como escrever uma função definida pelo usuário.This section modifies the file src\actions\userDefinedFunctions\availability.js so you can learn in detail one way to write a user-defined function. No entanto, você pode optar por usar diretamente o arquivo src\actions\userDefinedFunctions\availabilityForTutorial.js em sua configuração.However, you can choose to directly use the file src\actions\userDefinedFunctions\availabilityForTutorial.js in your setup. Esse arquivo tem todas as alterações exigidas por este tutorial.This file has all the changes required for this tutorial. Se você usar esse arquivo, não deixe de usar o nome de arquivo correto para a chave script em src\actions\provisionSample.yaml.If you use this file instead, make sure to use the correct file name for the script key in src\actions\provisionSample.yaml.

    a.a. Na parte superior do arquivo, adicione as seguintes linhas para a temperatura abaixo do comentário // Add your sensor type here:At the top of the file, add the following lines for temperature below the comment // Add your sensor type here:

        var temperatureType = "Temperature";
        var temperatureThreshold = 78;
    

    b.b. Adicione as seguintes linhas depois da instrução que define var motionSensor, abaixo do comentário // Add your sensor variable here:Add the following lines after the statement that defines var motionSensor, below the comment // Add your sensor variable here:

       var temperatureSensor = otherSensors.find(function(element) {
           return element.DataType === temperatureType;
       });
    

    c.c. Adicione a seguinte linha depois da instrução que define var carbonDioxideValue, abaixo do comentário // Add your sensor latest value here:Add the following line after the statement that defines var carbonDioxideValue, below the comment // Add your sensor latest value here:

        var temperatureValue = getFloatValue(temperatureSensor.Value().Value);
    

    d.d. Remova as seguintes linhas de código abaixo do comentário // Modify this line to monitor your sensor value:Remove the following lines of code from below the comment // Modify this line to monitor your sensor value:

       if(carbonDioxideValue === null || motionValue === null) {
           sendNotification(telemetry.SensorId, "Sensor", "Error: Carbon dioxide or motion are null, returning");
           return;
       }
    

    Substitua-as pelas seguintes linhas:Replace them with the following lines:

        if(carbonDioxideValue === null || motionValue === null || temperatureValue === null){
            sendNotification(telemetry.SensorId, "Sensor", "Error: Carbon dioxide, motion, or temperature are null, returning");
            return;
        }
    

    e.e. Remova as seguintes linhas de código abaixo do comentário // Modify these lines as per your sensor:Remove the following lines of code from below the comment // Modify these lines as per your sensor:

        var availableFresh = "Room is available and air is fresh";
        var noAvailableOrFresh = "Room is not available or air quality is poor";
    

    Substitua-as pelas seguintes linhas:Replace them with the following lines:

        var alert = "Room with fresh air and comfortable temperature is available.";
        var noAlert = "Either room is occupied, or working conditions are not right.";
    

    f.f. Remova o seguinte bloco de código if-else após o comentário // Modify this code block for your sensor:Remove the following if-else code block after the comment // Modify this code block for your sensor:

        // If carbonDioxide less than threshold and no presence in the room => log, notify and set parent space computed value
        if(carbonDioxideValue < carbonDioxideThreshold && !presence) {
            log(`${availableFresh}. Carbon Dioxide: ${carbonDioxideValue}. Presence: ${presence}.`);
            setSpaceValue(parentSpace.Id, spaceAvailFresh, availableFresh);
        }
        else {
            log(`${noAvailableOrFresh}. Carbon Dioxide: ${carbonDioxideValue}. Presence: ${presence}.`);
            setSpaceValue(parentSpace.Id, spaceAvailFresh, noAvailableOrFresh);
    
            // Set up custom notification for poor air quality
            parentSpace.Notify(JSON.stringify(noAvailableOrFresh));
        }
    

    E substitua-o pelo bloco if-else a seguir:And replace it with the following if-else block:

        // If sensor values are within range and room is available
        if(carbonDioxideValue < carbonDioxideThreshold && temperatureValue < temperatureThreshold && !presence) {
            log(`${alert}. Carbon Dioxide: ${carbonDioxideValue}. Temperature: ${temperatureValue}. Presence: ${presence}.`);
    
            // log, notify and set parent space computed value
            setSpaceValue(parentSpace.Id, spaceAvailFresh, alert);
    
            // Set up notification for this alert
            parentSpace.Notify(JSON.stringify(alert));
        }
        else {
            log(`${noAlert}. Carbon Dioxide: ${carbonDioxideValue}. Temperature: ${temperatureValue}. Presence: ${presence}.`);
    
            // log, notify and set parent space computed value
            setSpaceValue(parentSpace.Id, spaceAvailFresh, noAlert);
        }
    

    O UDF modificado irá procurar uma condição em que uma sala se torna disponível e tem o dióxido de carbono e a temperatura dentro dos limites toleráveis.The modified UDF will look for a condition where a room becomes available and has the carbon dioxide and temperature within tolerable limits. Ele irá gerar uma notificação com a instrução parentSpace.Notify(JSON.stringify(alert)); quando essa condição for atendida.It will generate a notification with the statement parentSpace.Notify(JSON.stringify(alert)); when this condition is met. Ela definirá o valor do espaço monitorado independentemente de a condição ser atendida, com a mensagem correspondente.It will set the value of the monitored space regardless of whether the condition is met, with the corresponding message.

    g.g. Salve o arquivo.Save the file.

  3. Abra a janela de comando e navegue até a pasta occupancy-quickstart\src.Open a command window, and go to the folder occupancy-quickstart\src. Execute o seguinte comando para provisionar o grafo de inteligência espacial e a função definida pelo usuário:Run the following command to provision your spatial intelligence graph and user-defined function:

    dotnet run ProvisionSample
    

    Importante

    Para impedir o acesso não autorizado à API de Gerenciamento dos Gêmeos Digitais, o aplicativo occupancy-quickstart exige que você entre com suas credenciais de conta do Azure.To prevent unauthorized access to your Digital Twins Management API, the occupancy-quickstart application requires you to sign in with your Azure account credentials. Ele salva suas credenciais por um breve período, para que você não precise entrar toda vez que for executá-lo.It saves your credentials for a brief period, so you might not need to sign in every time you run it. Quando o programa é executado pela primeira vez e quando as credenciais salvas expiram, ele encaminha você para uma página de entrada e fornece um código específico da sessão para inserir nessa página.The first time this program runs, and when your saved credentials expire after that, the application directs you to a sign-in page and gives a session-specific code to enter on that page. Siga os prompts para entrar com sua conta do Azure.Follow the prompts to sign in with your Azure account.

  4. Depois que a conta é autenticada, o aplicativo começa a criação de um grafo especial de exemplo conforme configurado em provisionSample.yaml.After your account is authenticated, the application starts creating a sample spatial graph as configured in provisionSample.yaml. Aguarde até a conclusão do provisionamento.Wait until the provisioning finishes. Isso levará alguns minutos.It will take a few minutes. Depois disso, observe as mensagens na janela de comando e observe como o grafo espacial é criado.After that, observe the messages in the command window and notice how your spatial graph is created. Observe como o aplicativo cria um hub IoT no nó raiz ou em Venue.Notice how the application creates an IoT hub at the root node or the Venue.

  5. Da saída na janela de comando, copie o valor da ConnectionString, na seção Devices, para a área de transferência.From the output in the command window, copy the value of ConnectionString, under the Devices section, to your clipboard. Você precisará desse valor para simular a conexão do dispositivo na próxima seção.You'll need this value to simulate the device connection in the next section.

    Exemplo de provisionamentoProvision sample

Dica

Se você receber uma mensagem de erro semelhante a "A operação de E/S foi anulada devido a uma saída de thread ou solicitação do aplicativo" no meio do provisionamento, tente executar o comando novamente.If you get an error message similar to "The I/O operation has been aborted because of either a thread exit or an application request" in the middle of the provisioning, try running the command again. Isso pode acontecer quando o cliente HTTP atingir o tempo limite devido a um problema de rede.This might happen if the HTTP client timed out from a network issue.

Simular dados de sensorSimulate sensor data

Nesta seção, você usará o projeto chamado device-connectivity no exemplo.In this section, you'll use the project named device-connectivity in the sample. Você vai simular dados de sensor para detectar movimento, temperatura e dióxido de carbono.You'll simulate sensor data for detecting motion, temperature, and carbon dioxide. Esse projeto gera valores aleatórios para os sensores e os envia ao hub IoT usando a cadeia de conexão do dispositivo.This project generates random values for the sensors, and sends them to the IoT hub by using the device connection string.

  1. Em uma janela de comando separada, vá para o exemplo dos Gêmeos Digitais do Azure e, em seguida para a pasta device-connectivity.In a separate command window, go to the Azure Digital Twins sample and then to the device-connectivity folder.

  2. Execute esse comando para ter certeza de que as dependências do projeto estão corretas:Run this command to make sure the dependencies for the project are correct:

    dotnet restore
    
  3. Abra o arquivo appsettings.json no editor e edite os seguintes valores:Open the appsettings.json file in your editor, and edit the following values:

    a.a. DeviceConnectionString: Atribua o valor de ConnectionString na Janela de Saída da seção anterior.DeviceConnectionString: Assign the value of ConnectionString in the output window from the previous section. Copie essa cadeia de caracteres na totalidade, entre aspas, para que o simulador possa se conectar corretamente ao hub IoT.Copy this string completely, within the quotes, so the simulator can connect properly with the IoT hub.

    b.b. HardwareId na matriz Sensores: Como você está simulando eventos dos sensores provisionados em sua instância dos Gêmeos Digitais do Azure, a ID de hardware e os nomes dos sensores nesse arquivo devem corresponder ao nó sensors do arquivo provisionSample.yaml.HardwareId within the Sensors array: Because you're simulating events from sensors provisioned to your Azure Digital Twins instance, the hardware ID and the names of the sensors in this file should match the sensors node of the provisionSample.yaml file.

    Adicione uma nova entrada para o sensor de temperatura.Add a new entry for the temperature sensor. O nó Sensors em appsettings.json deverá ser semelhante ao seguinte:The Sensors node in appsettings.json should look like the following:

    "Sensors": [{
      "DataType": "Motion",
      "HardwareId": "SAMPLE_SENSOR_MOTION"
    },{
      "DataType": "CarbonDioxide",
      "HardwareId": "SAMPLE_SENSOR_CARBONDIOXIDE"
    },{
      "DataType": "Temperature",
      "HardwareId": "SAMPLE_SENSOR_TEMPERATURE"
    }]
    
  4. Execute este comando para iniciar a simulação de eventos de dispositivo para temperatura, movimento e dióxido de carbono:Run this command to start simulating device events for temperature, motion, and carbon dioxide:

    dotnet run
    

    Observação

    Já que o exemplo de simulação não se comunica diretamente com a instância dos Gêmeos Digitais, ele não requer autenticação.Because the simulation sample does not directly communicate with your Digital Twins instance, it does not require you to authenticate.

Obter resultados da função definida pelo usuárioGet results of the user-defined function

A função definida pelo usuário é executada sempre que sua instância recebe dados de sensor e de dispositivo.The user-defined function runs every time your instance receives device and sensor data. Essa seção consulta sua instância dos Gêmeos Digitais do Azure para obter os resultados da função definida pelo usuário.This section queries your Azure Digital Twins instance to get the results of the user-defined function. Você verá em tempo real quando uma sala está disponível, se o ar está fresco e se temperatura está correta.You'll see in near real time, when a room is available, that the air is fresh and temperature is right.

  1. Abra a janela de comando que você usou para provisionar o exemplo, ou uma nova janela de comando, e vá para a pasta occupancy-quickstart\src do exemplo novamente.Open the command window that you used to provision the sample, or a new command window, and go to the occupancy-quickstart\src folder of the sample again.

  2. Execute o seguinte comando e entre quando solicitado:Run the following command and sign in when prompted:

    dotnet run GetAvailableAndFreshSpaces
    

A janela de saída mostra como a função definida pelo usuário é executada e intercepta eventos de simulação do dispositivo.The output window shows how the user-defined function runs and intercepts events from the device simulation.

Saída para a UDFOutput for the UDF

Se a condição monitorada for atendida, a função definida pelo usuário definirá o valor do espaço com a mensagem relevante, como vimos anteriormente.If the monitored condition is met, the user-defined function sets the value of the space with the relevant message, as we saw earlier. A função GetAvailableAndFreshSpaces imprime a mensagem no console.The GetAvailableAndFreshSpaces function prints out the message on the console.

Limpar recursosClean up resources

Se você quiser parar de explorar os Gêmeos Digitais do Azure neste momento, fique à vontade para excluir recursos criados neste tutorial:If you want to stop exploring Azure Digital Twins at this point, feel free to delete resources created in this tutorial:

  1. 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.From the left menu in the Azure portal, select All resources, select your Digital Twins resource group, and select Delete.

    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.If you experienced trouble deleting your Digital Twins instance, a service update has been rolled out with the fix. Tente novamente excluir a instância.Please retry deleting your instance.

  2. Se necessário, exclua os aplicativos de exemplo em seu computador de trabalho.If necessary, delete the sample applications on your work machine.

Próximas etapasNext steps

Agora que você provisionou os espaços e criou uma estrutura para disparar notificações personalizadas, vá para um dos tutoriais abaixo:Now that you have provisioned your spaces and created a framework to trigger custom notifications, you can go to either of the following tutorials: