開始使用裝置對應項 (Node.js)

• CLI
• .NET
• Python
• Node.js
• Java

裝置對應項是存放裝置狀態資訊的 JSON 文件，包括中繼資料、設定和條件。 IoT 中樞會為其連線的每個裝置保存裝置對應項。

注意

本文中所述的功能僅適用於 IoT 中樞的標準層。 如需基本和標準/免費 IoT 中樞層的詳細資訊，請參閱選擇適合您解決方案的 IoT 中樞層。

使用裝置對應項以：

• 從您的解決方案後端儲存裝置中繼資料。

• 從裝置應用程式報告目前狀態資訊，例如可用功能和狀況 (例如，使用的連線方法)。

• 同步處理裝置應用程式與後端應用程式之間，長時間執行的工作流程狀態 (例如韌體和設定更新)。

• 查詢您的裝置中繼資料、設定或狀態。

裝置對應項是設計來進行同步處理和查詢裝置組態和條件。 如需裝置對應項的詳細資訊，包括何時使用裝置對應項，請參閱了解裝置對應項。

IoT 中樞會儲存裝置對應項，其包含下列元素：

• 標籤。 只有解決方案後端可存取裝置中繼資料。

• 預期屬性。 JSON 物件可由解決方案後端修改，並依裝置應用程式查看。

• 回報的屬性。 JSON 物件可由裝置應用程式修改，並由解決方案後端讀取。

標籤和屬性不能包含陣列，但可以包含巢狀物件。

下圖顯示裝置對應項的組織：

此外，解決方案後端可以根據上述的所有資料查詢裝置對應項。 如需裝置對應項的詳細資訊，請參閱了解裝置對應項。 如需查詢的詳細資訊，請參閱 IoT 中樞查詢語言。

本文章說明如何：

• 使用模擬裝置應用程式，將其連線通道報告為裝置對應項上的回報屬性。

• 使用先前建立的標籤和屬性上的篩選器，從您的後端應用程式查詢裝置。

在本文中，您會建立兩個 Node.js 主控台應用程式：

• AddTagsAndQuery.js：後端應用程式，可新增標籤和查詢裝置對應項。

• TwinSimulatedDevice.js：為模擬裝置應用程式，可連線至 IoT 中樞並報告其連線狀況。

注意

如需可用來建置裝置和後端應用程式的 SDK 工具詳細資訊，請參閱 Azure IoT SDK。

必要條件

若要完成本文，您需要：

• Azure 訂用帳戶中的 IoT 中樞。 如果您還沒有中樞，可遵循建立 IoT 中樞中的步驟。

• 在 IoT 中樞內註冊的裝置。 如果 IoT 中樞中沒有裝置，請遵循註冊裝置中的步驟。

• Node.js 10.0.x 版或更新版本。

• 請確定您的防火牆已開啟連接埠 8883。 本文中的裝置範例會使用 MQTT 通訊協定，其會透過連接埠 8883 進行通訊。 某些公司和教育網路環境可能會封鎖此連接埠。 如需此問題的詳細資訊和解決方法，請參閱連線至 IoT 中樞 (MQTT)。

取得 IoT 中樞連接字串

在本文中，您會建立後端服務，其會將所需的屬性新增至裝置對應項，然後查詢身分識別登錄，以尋找具有所報告屬性且已分別更新的所有裝置。 服務需要有服務連線權限，才能修改裝置對應項的所需屬性，也需要有登錄讀取權限才能查詢身分識別登錄。 沒有任何預設的共用存取原則只包含這兩項權限，所以必須自己建立一個。

若要建立共用存取原則，其會授與服務連線和登錄讀取權限，並取得此原則的連接字串，請遵循下列步驟：

1. 在 Azure 入口網站中，選取 [資源群組]。 選取中樞所在的資源群組，然後從資源清單選取中樞。

2. 在中樞的左側窗格上，選取 [共用存取原則]。

3. 從原則清單上方的頂端功能表中，選取 [新增共用存取原則]。

4. 在右側的 [新增共用存取原則] 窗格中，輸入原則的描述性名稱，例如 serviceAndRegistryRead。 在 [權限] 底下選取 [登錄讀取] 和 [服務連線]，然後選取 [新增]。

   

5. 從原則清單中選取新原則。

6. 選取 [主要連接字串] 的複製圖示，然後儲存值。

   

如需 IoT 中樞共用存取原則和權限的詳細資訊，請參閱存取控制及權限。

建立裝置應用程式來更新報告屬性

在本節中，您將建立一個 Node.js 主控台應用程式，此應用程式會以 myDeviceId 連線至您的中樞，然後更新其裝置對應項的回報屬性，確認目前使用行動電話通訊網路來連線。

1. 建立稱為 reportconnectivity 的新空白資料夾。 在 reportconnectivity 資料夾中，於命令提示字元使用下列命令建立新的 package.json 檔案。 --yes 參數接受所有預設值。

   npm init --yes
   

2. 在 reportconnectivity 資料夾中，於命令提示字元執行下列命令以安裝 azure-iot-device 和 azure-iot-device-mqtt 套件：

   npm install azure-iot-device azure-iot-device-mqtt --save
   

3. 使用文字編輯器，在 reportconnectivity 資料夾中建立新的 ReportConnectivity.js 檔案。

4. 將下列程式碼新增至 ReportConnectivity.js 檔案。 將 {device connection string} 取代為您在 IoT 中樞註冊新裝置時看到的裝置連接字串：

       'use strict';
       var Client = require('azure-iot-device').Client;
       var Protocol = require('azure-iot-device-mqtt').Mqtt;
   
       var connectionString = '{device connection string}';
       var client = Client.fromConnectionString(connectionString, Protocol);
   
       client.open(function(err) {
       if (err) {
           console.error('could not open IotHub client');
       }  else {
           console.log('client opened');
   
           client.getTwin(function(err, twin) {
           if (err) {
               console.error('could not get twin');
           } else {
               var patch = {
                   connectivity: {
                       type: 'cellular'
                   }
               };
   
               twin.properties.reported.update(patch, function(err) {
                   if (err) {
                       console.error('could not update twin');
                   } else {
                       console.log('twin state reported');
                       process.exit();
                   }
               });
           }
           });
       }
       });
   

   Client 物件會公開從裝置來與裝置對應項進行互動時所需的所有方法。 先前的程式碼在初始化 Client 物件之後，會擷取 myDeviceId 的裝置對應項，並以連線資訊來更新其報告屬性。

5. 執行裝置應用程式

       node ReportConnectivity.js
   

   您應該會看見訊息 twin state reported。

6. 現在，裝置已回報其連線資訊，它應該會出現在這兩個查詢中。 回到 addtagsandqueryapp 資料夾，並再次執行查詢︰

       node AddTagsAndQuery.js
   

   這次，myDeviceId 應該會出現在這兩個查詢結果中。

   

建立服務應用程式來更新所需的屬性和查詢對應項

在本節中，您將建立一個 Node.js 主控台應用程式，此應用程式會將位置中繼資料新增至與 myDeviceId 相關聯的裝置對應項。 應用程式會先查詢 IoT 中樞是否有位於美國的裝置，再查詢是否有回報行動電話通訊網路連線的裝置。

1. 建立稱為 addtagsandqueryapp 的新空白資料夾。 在 addtagsandqueryapp 資料夾中，於命令提示字元使用下列命令建立新的 package.json 檔案。 --yes 參數接受所有預設值。

   npm init --yes
   

2. 在命令提示字元下，於 addtagsandqueryapp 資料夾中執行下列命令以安裝 azure-iothub 套件：

   npm install azure-iothub --save
   

3. 使用文字編輯器，在 addtagsandqueryapp 資料夾中建立新的 AddTagsAndQuery.js 檔案。

4. 將下列程式碼新增至 AddTagsAndQuery.js 檔案。 將 {iot hub connection string} 取代為在取得 IoT 中樞連接字串中複製的 IoT 中樞連接字串。

        'use strict';
        var iothub = require('azure-iothub');
        var connectionString = '{iot hub connection string}';
        var registry = iothub.Registry.fromConnectionString(connectionString);
   
        registry.getTwin('myDeviceId', function(err, twin){
            if (err) {
                console.error(err.constructor.name + ': ' + err.message);
            } else {
                var patch = {
                    tags: {
                        location: {
                            region: 'US',
                            plant: 'Redmond43'
                      }
                    }
                };
   
                twin.update(patch, function(err) {
                  if (err) {
                    console.error('Could not update twin: ' + err.constructor.name + ': ' + err.message);
                  } else {
                    console.log(twin.deviceId + ' twin updated successfully');
                    queryTwins();
                  }
                });
            }
        });
   

   Registry 物件會公開從服務來與裝置對應項進行互動時所需的所有方法。 先前的程式碼會先初始化 Registry 物件，然後擷取 myDeviceId 的裝置對應項，最後會以所需的位置資訊來更新其標籤。

   更新標籤之後，它會呼叫 queryTwins 函式。

5. 在 AddTagsAndQuery.js 結尾處新增下列程式碼來實作 queryTwins 函式︰

        var queryTwins = function() {
            var query = registry.createQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'", 100);
            query.nextAsTwin(function(err, results) {
                if (err) {
                    console.error('Failed to fetch the results: ' + err.message);
                } else {
                    console.log("Devices in Redmond43: " + results.map(function(twin) {return twin.deviceId}).join(','));
                }
            });
   
            query = registry.createQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity.type = 'cellular'", 100);
            query.nextAsTwin(function(err, results) {
                if (err) {
                    console.error('Failed to fetch the results: ' + err.message);
                } else {
                    console.log("Devices in Redmond43 using cellular network: " + results.map(function(twin) {return twin.deviceId}).join(','));
                }
            });
        };
   

   先前的程式碼會執行兩個查詢︰第一個只選取位於 Redmond43 工廠的裝置的裝置對應項，第二個會修改查詢，只選取也透過行動電話網路來連接的裝置。

   當程式碼建立查詢物件時，會在第二個參數中指定傳回的最大文件數。 query 物件包含 hasMoreResults 布林值屬性，可用來多次叫用 nextAsTwin 方法以擷取所有結果。 有一個稱為 next 的方法，其適用於非裝置對應項的結果，例如彙總查詢的結果。

6. 使用下列命令執行應用程式：

       node AddTagsAndQuery.js
   

   如果是查詢所有位於 Redmond43 中的裝置，您在結果中會看到一個裝置，而如果查詢將結果限於使用行動電話網路的裝置，則您不會看到任何裝置。

   

在本文章中，您將：

• 從後端應用程式將裝置中繼資料新增為標籤
• 回報裝置對應項中的裝置連線資訊
• 使用類似 SQL 的 IoT 中樞查詢語言來查詢裝置對應項資訊

下一步

若要了解如何：

• 從裝置傳送遙測，請參閱快速入門：將遙測資料從 IoT 隨插即用裝置傳送至 IoT 中樞

• 使用裝置對應項所需的屬性設定裝置，請參閱教學課程：從後端服務設定您的裝置

• 以互動方式控制裝置，例如從使用者控制的應用程式開啟風扇，請參閱快速入門：控制連線至 IoT 中樞的裝置