チュートリアル:Azure Digital Twins プレビューを使用して建物をプロビジョニングし、作業環境を監視するTutorial: Provision your building and monitor working conditions with Azure Digital Twins Preview

このチュートリアルでは、Azure Digital Twins プレビューを使用して、望ましい温度条件と快適度を基準に空間を監視する方法について説明します。This tutorial demonstrates how to use Azure Digital Twins Preview to monitor your spaces for desired temperature conditions and comfort level. サンプルの建物を構成した後、このチュートリアルの手順を使用して建物をプロビジョニングし、センサー データに対してカスタム関数を実行できます。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.

このチュートリアルでは、以下の内容を学習します。In this tutorial, you learn how to:

  • 監視する条件を定義する。Define conditions to monitor.
  • ユーザー定義関数 (UDF) を作成する。Create a user-defined function (UDF).
  • センサー データをシミュレートする。Simulate sensor data.
  • ユーザー定義関数の結果を取得する。Get results of a user-defined function.

前提条件Prerequisites

このチュートリアルでは、Azure Digital Twins の設定が完了していることを前提としています。This tutorial assumes that you have finished your Azure Digital Twins setup. 次に進む前に、以下が準備されていることを確認します。Before proceeding, make sure that you have:

ヒント

新しいインスタンスをプロビジョニングする場合は、一意の Digital Twins インスタンス名を使用します。Use a unique Digital Twins instance name if you're provisioning a new instance.

監視する条件を定義するDefine conditions to monitor

デバイスまたはセンサーのデータについて監視する特定の条件のセット ("マッチャー" と呼ばれます) を定義できます。You can define a set of specific conditions to monitor in the device or sensor data, called matchers. その後、"ユーザー定義関数" と呼ばれる関数を定義できます。You can then define functions called user-defined functions. ユーザー定義関数では、マッチャーによって指定された条件が発生したときに、空間およびデバイスから受け取ったデータに対してカスタム ロジックが実行されます。User-defined functions execute custom logic on data that comes from your spaces and devices, when the conditions specified by the matchers occur. 詳細については、「データ処理とユーザー定義関数」を参照してください。For more information, read Data processing and user-defined functions.

Visual Studio Code で、occupancy-quickstart サンプル プロジェクトの src\actions\provisionSample.yaml ファイルを開きます。From the occupancy-quickstart sample project, open the file src\actions\provisionSample.yaml in Visual Studio Code. matchers で始まるセクションに注目してください。Note the section that begins with the type matchers. この型の各エントリによって、指定された名前のマッチャーが作成されます。Each entry under this type creates a matcher with the specified Name. このマッチャーによって、型 dataTypeValue のセンサーが監視されます。The matcher will monitor a sensor of type dataTypeValue. これが Focus Room A1 という名前の空間とどのように関係しているかに注目してください。ここには、いくつかのセンサーがある devices ノードが含まれています。Notice how it relates to the space named Focus Room A1, which has a devices node that contains a few sensors. これらのセンサーの 1 つを追跡するマッチャーをプロビジョニングするには、その dataTypeValue がセンサーの dataType と一致している必要があります。To provision a matcher that will track one of these sensors, make sure that its dataTypeValue matches the sensor's dataType.

既存のマッチャーの下に次のマッチャーを追加します。Add the following matcher below the existing matchers. キーの位置が揃っていて、空白がタブで置き換えられていないことを確認してください。Make sure the keys are aligned and spaces are not replaced by tabs. これらの行は、コメントアウトされた行として provisionSample.yaml ファイル内にもあります。These lines are also present in the provisionSample.yaml file as commented-out lines. 各行の先頭にある # 文字を削除するだけでコメント解除することができます。You can uncomment them by removing the # character in front of each line.

      - name: Matcher Temperature
        dataTypeValue: Temperature

このマッチャーでは、最初のチュートリアルで追加した SAMPLE_SENSOR_TEMPERATURE センサーが追跡されます。This matcher will track the SAMPLE_SENSOR_TEMPERATURE sensor that you added in the first tutorial.

ユーザー定義関数を作成するCreate a user-defined function

ユーザー定義関数を使用すると、センサー データの処理をカスタマイズできます。You can use user-defined functions to customize the processing of your sensor data. これらは、マッチャーによって記述された特定の条件が発生したときに Azure Digital Twins インスタンス内で実行できるカスタム JavaScript コードです。They're custom JavaScript code that can run within your Azure Digital Twins instance, when specific conditions as described by the matchers occur. マッチャーとユーザー定義関数は、監視したいセンサーごとに作成できます。You can create matchers and user-defined functions for each sensor that you want to monitor. 詳細については、「データ処理とユーザー定義関数」を参照してください。For more information, read Data processing and user-defined functions.

サンプルの provisionSample.yaml ファイルで、型 userdefinedfunctions で始まるセクションを見つけます。In the sample provisionSample.yaml file, look for a section that begins with the type userdefinedfunctions. このセクションによって、指定された名前のユーザー定義関数がプロビジョニングされます。This section provisions a user-defined function with a given Name. この UDF は、matcherNames の下のマッチャーの一覧を対象にして動作します。This UDF acts on the list of matchers under matcherNames. 独自の JavaScript ファイルをスクリプトとして UDF に提供する方法に注目してください。Notice how you can provide your own JavaScript file for the UDF as the script.

さらに、roleassignments という名前のセクションに注目してください。Also note the section named roleassignments. これによって、ユーザー定義関数にスペース管理者ロールが割り当てられます。It assigns the Space Administrator role to the user-defined function. このロールでは、すべてのプロビジョニング済み空間から届いたイベントへのアクセスが許可されます。This role allows it to access the events that come from any of the provisioned spaces.

  1. 温度マッチャーを含めるように UDF を構成します。そのためには、provisionSample.yaml ファイルの matcherNames ノードに次の行を追加するか、この行をコメント解除します。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. エディターで src\actions\userDefinedFunctions\availability.js ファイルを開きます。Open the file src\actions\userDefinedFunctions\availability.js in your editor. これは、provisionSample.yamlscript 要素で参照されているファイルです。This is the file referenced in the script element of provisionSample.yaml. このファイル内のユーザー定義関数では、室内でモーションが検出されず、二酸化炭素レベルが 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.

    温度とその他の条件を監視するように JavaScript ファイルを変更します。Modify the JavaScript file to monitor temperature and other conditions. 室内でモーションが検出されず、二酸化炭素レベルが 1,000 ppm 未満、温度が華氏 78 度未満の条件を検索するために、次のコード行を追加します。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.

    注意

    このセクションでは、ユーザー定義関数の 1 つの記述方法を詳しく学習できるように、ファイル src\actions\userDefinedFunctions\availability.js を変更しています。This section modifies the file src\actions\userDefinedFunctions\availability.js so you can learn in detail one way to write a user-defined function. ただし、セットアップ内の src\actions\userDefinedFunctions\availabilityForTutorial.js ファイルを直接使用してもかまいません。However, you can choose to directly use the file src\actions\userDefinedFunctions\availabilityForTutorial.js in your setup. このファイルには、このチュートリアルに必要なすべての変更が含まれています。This file has all the changes required for this tutorial. 代わりにこのファイルを使用する場合は、src\actions\provisionSample.yaml 内の script キーに適切なファイル名を使用するようにしてください。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. ファイルの先頭で、コメント // 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. var motionSensor を定義するステートメントの後ろにあるコメント // 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. var carbonDioxideValue を定義するステートメントの後ろにあるコメント // 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. コメント // 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;
       }
    

    それらを次の行に置き換えます。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. コメント // 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";
    

    それらを次の行に置き換えます。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. コメント // Modify this code block for your sensor の後ろにある次の if-else コード ブロックを削除します。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));
        }
    

    これを次の if-else ブロックに置き換えます。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);
        }
    

    変更後の UDF では、部屋が使用可能で、二酸化炭素と温度が許容限度内にある状態が検索されます。The modified UDF will look for a condition where a room becomes available and has the carbon dioxide and temperature within tolerable limits. この条件が満たされると、parentSpace.Notify(JSON.stringify(alert)); ステートメントによって通知が生成されます。It will generate a notification with the statement parentSpace.Notify(JSON.stringify(alert)); when this condition is met. 条件が満たされているかどうかに関係なく、監視されている空間の値が対応するメッセージと共に設定されます。It will set the value of the monitored space regardless of whether the condition is met, with the corresponding message.

    g.g. ファイルを保存します。Save the file.

  3. コマンド ウィンドウを開き、occupancy-quickstart\src フォルダーに移動します。Open a command window, and go to the folder occupancy-quickstart\src. 次のコマンドを実行して、空間インテリジェンス グラフおよびユーザー定義関数をプロビジョニングします。Run the following command to provision your spatial intelligence graph and user-defined function:

    dotnet run ProvisionSample
    

    重要

    Digital Twins Management API への不正アクセスを防ぐために、occupancy-quickstart アプリケーションでは 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. 資格情報は一時的に保存されるため、実行するたびにサインインする必要はありません。It saves your credentials for a brief period, so you might not need to sign in every time you run it. このプログラムを初めて実行したときと、その後保存された資格情報が期限切れになったときは、アプリケーションによってサインイン ページが表示され、そのページに入力するセッション固有のコードが与えられます。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. プロンプトに従って、Azure アカウントを使用してサインインします。Follow the prompts to sign in with your Azure account.

  4. アカウントが認証された後、アプリケーションによって、provisionSample.yaml の構成どおりにサンプル空間グラフの作成が開始されます。After your account is authenticated, the application starts creating a sample spatial graph as configured in provisionSample.yaml. プロビジョニングが完了するまで待機します。Wait until the provisioning finishes. これには数分かかります。It will take a few minutes. その後、コマンド ウィンドウのメッセージを見て、空間グラフがどのように作成されているかを確認します。After that, observe the messages in the command window and notice how your spatial graph is created. アプリケーションによってルート ノードまたは Venue に IoT ハブがどのように作成されているかに注目します。Notice how the application creates an IoT hub at the root node or the Venue.

  5. コマンド ウィンドウの出力から、Devices セクションの ConnectionString の値をクリップボードにコピーします。From the output in the command window, copy the value of ConnectionString, under the Devices section, to your clipboard. この値は、次のセクションでデバイス接続をシミュレートするために必要です。You'll need this value to simulate the device connection in the next section.

    サンプルをプロビジョニングするProvision sample

ヒント

プロビジョニングの途中で "The I/O operation has been aborted because of either a thread exit or an application request (スレッドの終了またはアプリケーション要求のため I/O 操作が中止されました)" のようなエラー メッセージが表示された場合は、コマンドをもう一度実行してみてください。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. これは、ネットワークの問題が原因で HTTP クライアントがタイムアウトしたときに発生する可能性があります。This might happen if the HTTP client timed out from a network issue.

センサー データをシミュレートするSimulate sensor data

このセクションでは、サンプル内の device-connectivity という名前のプロジェクトを使用します。In this section, you'll use the project named device-connectivity in the sample. モーション、温度、二酸化炭素を検出するためのセンサー データをシミュレートします。You'll simulate sensor data for detecting motion, temperature, and carbon dioxide. このプロジェクトでは、センサーのランダムな値が生成され、デバイス接続文字列を使用してそれらが IoT ハブに送信されます。This project generates random values for the sensors, and sends them to the IoT hub by using the device connection string.

  1. 別のコマンド ウィンドウで、Azure Digital Twins サンプルに移動し、device-connectivity フォルダーに移動します。In a separate command window, go to the Azure Digital Twins sample and then to the device-connectivity folder.

  2. 次のコマンドを実行して、プロジェクトの依存関係が正しいことを確認します。Run this command to make sure the dependencies for the project are correct:

    dotnet restore
    
  3. エディターで appsettings.json ファイルを開き、次の値を編集します。Open the appsettings.json file in your editor, and edit the following values:

    a.a. DeviceConnectionString: 前のセクションの出力ウィンドウに含まれている ConnectionString の値を割り当てます。DeviceConnectionString: Assign the value of ConnectionString in the output window from the previous section. シミュレーターが IoT ハブに正常に接続できるように、引用符で囲まれたこの文字列を完全にコピーしてください。Copy this string completely, within the quotes, so the simulator can connect properly with the IoT hub.

    b.b. Sensors 配列内の HardwareId: Azure Digital Twins インスタンスにプロビジョニングされたセンサーからのイベントをシミュレートしているので、このファイル内のハードウェア ID とセンサーの名前が provisionSample.yaml ファイルの sensors ノードと一致している必要があります。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.

    温度センサーの新しいエントリを追加します。Add a new entry for the temperature sensor. appsettings.jsonSensors ノードは次のようになります。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. 次のコマンドを実行して、温度、モーション、二酸化炭素に関するデバイス イベントのシミュレーションを開始します。Run this command to start simulating device events for temperature, motion, and carbon dioxide:

    dotnet run
    

    注意

    シミュレーション サンプルは Digital Twins インスタンスと直接通信しないため、認証を行う必要はありません。Because the simulation sample does not directly communicate with your Digital Twins instance, it does not require you to authenticate.

ユーザー定義関数の結果を取得するGet results of the user-defined function

ユーザー定義関数は、インスタンスがデバイスとセンサーのデータを受信するたびに実行されます。The user-defined function runs every time your instance receives device and sensor data. このセクションでは、Azure Digital Twins インスタンスに対するクエリを実行して、ユーザー定義関数の結果を取得します。This section queries your Azure Digital Twins instance to get the results of the user-defined function. 部屋が使用可能な場合、空気が新鮮であり温度が適切であることが、ほぼリアルタイムでわかります。You'll see in near real time, when a room is available, that the air is fresh and temperature is right.

  1. サンプルのプロビジョニングに使用したコマンド ウィンドウを開くか、新しいコマンド ウィンドウを開き、再度サンプルの occupancy-quickstart\src フォルダーに移動します。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. 次のコマンドを実行します。メッセージが表示されたら、サインインします。Run the following command and sign in when prompted:

    dotnet run GetAvailableAndFreshSpaces
    

出力ウィンドウに、どのようにユーザー定義関数が実行され、デバイス シミュレーションからのイベントがインターセプトされているかが表示されます。The output window shows how the user-defined function runs and intercepts events from the device simulation.

UDF の出力Output for the UDF

監視されている条件が満たされると、前述のとおりに、ユーザー定義関数によって空間の値が関連メッセージと共に設定されます。If the monitored condition is met, the user-defined function sets the value of the space with the relevant message, as we saw earlier. メッセージは、GetAvailableAndFreshSpaces 関数によってコンソールに出力されます。The GetAvailableAndFreshSpaces function prints out the message on the console.

リソースのクリーンアップClean up resources

この時点で Azure Digital Twins の探索を中止する場合は、このチュートリアルで作成されたリソースを削除してかまいません。If you want to stop exploring Azure Digital Twins at this point, feel free to delete resources created in this tutorial:

  1. Azure portal の左側のメニューにある [すべてのリソース] をクリックし、目的の Digital Twins リソース グループを選択して [削除] を選択します。From the left menu in the Azure portal, select All resources, select your Digital Twins resource group, and select Delete.

    ヒント

    ご自分の Digital Twins インスタンスの削除で問題が発生していた場合は、サービス更新が修正と共にロールアウトされています。If you experienced trouble deleting your Digital Twins instance, a service update has been rolled out with the fix. ご自分のインスタンスの削除を再試行してください。Please retry deleting your instance.

  2. 必要に応じて、作業マシン上のサンプル アプリケーションを削除します。If necessary, delete the sample applications on your work machine.

次の手順Next steps

これで、空間をプロビジョニングし、カスタム通知をトリガーするフレームワークを作成できたので、次のいずれかのチュートリアルに進むことができます。Now that you have provisioned your spaces and created a framework to trigger custom notifications, you can go to either of the following tutorials: