開始使用裝置對應項目（Node.js）

發行項
01/29/2024

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

注意

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

使用裝置對應項以：

從解決方案後端儲存裝置元數據。
從您的裝置應用程式報告目前的狀態資訊，例如可用的功能和條件，例如所使用的連線方法。
同步處理裝置應用程式與後端應用程式之間長時間執行的工作流程狀態，例如韌體和組態更新。
查詢您的裝置中繼資料、設定或狀態。

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

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

標籤。裝置元數據只能由解決方案後端存取。
預期屬性。解決方案後端可修改的 JSON 物件，並可由裝置應用程式觀察。
回報的屬性。裝置應用程式可修改的 JSON 物件，並可由解決方案後端讀取。

標記和屬性不能包含數位，但可以包含巢狀物件。

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

裝置對應項概念圖表的螢幕快照。

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

本文章說明如何：

使用模擬裝置應用程式，將其連線通道報告為裝置對應項上的報告屬性。
使用先前建立之標籤和屬性的篩選，從後端應用程式查詢裝置。

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

AddTagsAndQuery.js：可新增標籤和查詢裝置對應項的後端應用程式。
TwinSimulatedDevice.js：連線到IoT中樞並報告其連線狀況的模擬裝置應用程式。

注意

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

必要條件

若要完成本文，您需要：

一個 IoT 中樞。使用 CLI 或 Azure 入口網站建立一個。
已註冊的裝置。在 Azure 入口網站中註冊一個。
Node.js 10.0.x 版或更新版本。
請確定您的防火牆中已開啟埠 8883。本文中的裝置範例會使用 MQTT 通訊協定，其會透過連接埠 8883 進行通訊。某些公司和教育網路環境可能會封鎖此連接埠。如需此問題的詳細資訊和解決方法，請參閱連線至 IoT 中樞 (MQTT)。

取得 IoT 中樞連接字串

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

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

在 Azure 入口網站中，選取 [資源群組]。選取中樞所在的資源群組，然後從資源清單選取中樞。
在中樞的左側窗格中，選取 [共用存取原則]。
從原則清單上方的頂端功能表中，選取 [ 新增共用原則存取原則]。
在右側的 [ 新增共用存取原則 ] 窗格中，輸入原則的描述性名稱，例如 serviceAndRegistryRead。在 [許可權] 底下，選取 [登錄讀取和服務 連線]，然後選取 [新增]。
從原則清單中選取您的新原則。
選取主要連接字串的複製圖示，然後儲存值。

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

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

在本節中，您會建立Node.js控制台應用程式，以 myDeviceId 連線到您的中樞，然後更新其裝置對應項的報告屬性，以確認其已使用行動電話通訊網路連線。

建立名為 reportconnectivity 的新空白資料夾。在 reportconnectivity 資料夾中，於命令提示字元使用下列命令建立新的package.json檔案。參數 --yes 會接受所有預設值。
```
npm init --yes
```
在 reportconnectivity 資料夾中的命令提示字元中，執行下列命令以安裝 azure-iot-device 和 azure-iot-device-mqtt 套件：
```
npm install azure-iot-device azure-iot-device-mqtt --save
```
使用文本編輯器，在 reportconnectivity 資料夾中建立新的報表連線 ivity.js 檔案。

將下列程式代碼新增至 Report 連線 ivity.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 的裝置對應項，並使用連線資訊更新其報告屬性。

執行裝置應用程式
```
    node ReportConnectivity.js
```
您應該會看到訊息 twin state reported。
既然裝置回報其連線資訊，它應該會出現在這兩個查詢中。返回 addtagsandqueryapp 資料夾中，然後再次執行查詢：
```
    node AddTagsAndQuery.js
```
這次 myDeviceId 應該會出現在這兩個查詢結果中。

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

在本節中，您會建立Node.js控制台應用程式，將位置元數據新增至與 myDeviceId 相關聯的裝置對應項。應用程式會針對位於美國的裝置查詢IoT中樞，然後查詢報告行動數據網路連線的裝置。

建立名為 addtagsandqueryapp 的新空白資料夾。在 addtagsandqueryapp 資料夾中，於命令提示字元使用下列命令建立新的package.json檔案。參數 --yes 會接受所有預設值。
```
npm init --yes
```
在 addtagsandqueryapp 資料夾中的命令提示字元中，執行下列命令以安裝 azure-iothub 套件：
```
npm install azure-iothub --save
```
使用文本編輯器，在 addtagsandqueryapp 資料夾中建立新的AddTagsAndQuery.js檔案。

將下列程式代碼新增至 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 函 式。

在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 工廠的裝置裝置對應項，第二個查詢會精簡查詢，只選取也透過行動數據網路連線的裝置。

當程式代碼建立查詢物件時，它會指定第二個參數中傳回的檔數目上限。查詢物件包含 hasMoreResults 布爾值屬性，可用來叫用 nextAsTwin 方法多次擷取所有結果。稱為 next 的方法可用於不是裝置對應項的結果，例如匯總查詢的結果。

使用下列項目執行應用程式：
```
    node AddTagsAndQuery.js
```
您應該會在查詢結果中看到一個裝置，要求所有位於 Redmond43 的裝置，且查詢中沒有一個裝置，該查詢會將結果限製為使用行動數據網路的裝置。

在本文章中，您將：

已從後端應用程式新增裝置元數據作為標籤
裝置對應項中回報的裝置連線資訊
使用類似 SQL 的查詢 IoT 中樞查詢語言來查詢裝置對應項資訊

下一步

若要了解如何：

從裝置傳送遙測，請參閱快速入門：將遙測從 IoT 隨插即用裝置傳送至 Azure IoT 中樞
使用裝置對應項所需的屬性設定裝置，請參閱教學課程：從後端服務設定您的裝置
以互動方式控制裝置，例如從使用者控制的應用程式開啟風扇，請參閱快速入門：控制連線到IoT中樞的裝置

開始使用裝置對應項目 （Node.js）

必要條件

取得 IoT 中樞連接字串

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

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

下一步

其他資源

開始使用裝置對應項目（Node.js）