開始使用 IoT 中樞模組身分識別和模組身分識別對應項

發行項
12/04/2024

模組身分識別和模組身分識別對應項類似於 Azure IoT 中樞裝置身分識別和裝置對應項，但提供更精細的數據粒度。雖然 Azure IoT 中樞裝置身分識別和裝置對應項可讓後端應用程式設定裝置，並提供裝置條件的可見性，但模組身分識別和模組身分識別對應項會為裝置的個別元件提供這些功能。在具有多個元件的功能裝置上，例如操作系統裝置或韌體裝置、模組身分識別和模組身分識別對應項，允許每個元件的隔離元件和條件。如需詳細資訊，請參閱瞭解 Azure IoT 中樞模組對應項。

注意

本文中所述的功能僅適用於 IoT 中樞的標準層。如需有關基本和標準/免費 IoT 中樞服務層級的詳細資訊，請參閱為您的解決方案選擇適合的 IoT 中樞層 (部分機器翻譯)。

本文說明如何開發兩種類型的應用程式：

檢視和更新模組身分識別對應項屬性並處理更新所需屬性的要求的裝置應用程式。
可讀取和設定模組身分識別所需屬性的服務應用程式。

注意

本文旨在補充本文中參考的 Azure IoT SDK 範例。您可以使用 SDK 工具來建置裝置應用程式和後端應用程式。

必要條件

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

需要 Visual Studio

概觀

本文說明如何使用適用於 .NET 的 Azure IoT SDK 來建立模組身分識別對應項的裝置和後端服務應用程式程式代碼。

建立裝置應用程式

本節說明如何使用裝置應用程式碼來執行下列作業：

擷取模組識別對應項，並檢查報告的屬性
更新回報的模組身分識別對應項屬性
建立模組所需的屬性更新回呼處理程式

重要

本文包含使用共用存取簽章 (也稱為對稱金鑰驗證) 連線裝置的步驟。此驗證方法方便進行測試和評估，但使用 X.509 憑證來驗證裝置是更安全的方法。若要深入了解，請參閱安全性最佳做法>連線安全性。

必要的裝置 NuGet 套件

以 C# 撰寫的裝置用戶端應用程式需要 Microsoft.Azure.Devices.Client NuGet 套件。

新增這些 using 語句以使用裝置連結庫。

using Microsoft.Azure.Devices.Client;
using Microsoft.Azure.Devices.Shared;

連線到裝置

ModuleClient 類別會公開從裝置與模組身分識別對應項互動所需的所有方法。

使用 CreateFromConnectionString 方法搭配模組身分識別連接字串連線到裝置。

不使用傳輸參數呼叫 CreateFromConnectionString 會使用預設AMQP傳輸來連線。

此範例會使用預設AMQP傳輸連線到裝置。

static string ModuleConnectionString = "{Device module identity connection string}";
private static ModuleClient _moduleClient = null;

_moduleClient = ModuleClient.CreateFromConnectionString(ModuleConnectionString, null);

擷取模組識別對應項並檢查屬性

呼叫 GetTwinAsync ，將目前的模塊識別對應項屬性擷取到 Twin 物件中。

此範例會擷取並顯示 JSON 格式的模組識別對應項屬性。

Console.WriteLine("Retrieving twin...");
Twin twin = await _moduleClient.GetTwinAsync();
Console.WriteLine("\tModule identity twin value received:");
Console.WriteLine(JsonConvert.SerializeObject(twin.Properties));

更新模組身分識別對應項報告屬性

若要更新對應項的報告屬性，請執行下列動作：

為報告屬性更新建立 TwinCollection 物件
更新 TwinCollection 物件內的一或多個報告屬性
使用 UpdateReportedPropertiesAsync 將報告屬性變更推送至 IoT 中樞服務

例如：

try
{
  Console.WriteLine("Sending sample start time as reported property");
  TwinCollection reportedProperties = new TwinCollection();
  reportedProperties["DateTimeLastAppLaunch"] = DateTime.UtcNow;
  await _moduleClient.UpdateReportedPropertiesAsync(reportedProperties);
}
catch (Exception ex)
{
   Console.WriteLine();
   Console.WriteLine("Error in sample: {0}", ex.Message);
}

建立所需的屬性更新回呼處理常式

將回呼處理程式方法名稱傳遞至 SetDesiredPropertyUpdateCallbackAsync ，以建立所需的屬性更新回呼處理程式，以在模塊識別對應項中變更所需屬性時執行。

例如，此呼叫會設定系統，以在變更所需的模組屬性時通知名為 OnDesiredPropertyChangedAsync 的方法。

await _moduleClient.SetDesiredPropertyUpdateCallbackAsync(OnDesiredPropertyChangedAsync, null);

模組身分識別對應項屬性會以 TwinCollection 的形式傳遞至回呼方法，並可以檢查為KeyValuePair結構。

此範例會接收所需屬性更新作為 TwinCollection，然後循環檢查並列印 KeyValuePair 集合更新。循環檢查 KeyValuePair 集合之後，程式碼會呼叫 UpdateReportedPropertiesAsync 以更新 DateTimeLastDesiredPropertyChangeReceived 報告屬性，使上次更新時間保持在最新狀態。

private async Task OnDesiredPropertyChangedAsync(TwinCollection desiredProperties, object userContext)
{
   var reportedProperties = new TwinCollection();

   Console.WriteLine("\tDesired properties requested:");
   Console.WriteLine($"\t{desiredProperties.ToJson()}");

   // For the purpose of this sample, we'll blindly accept all twin property write requests.
   foreach (KeyValuePair<string, object> desiredProperty in desiredProperties)
   {
         Console.WriteLine($"Setting {desiredProperty.Key} to {desiredProperty.Value}.");
         reportedProperties[desiredProperty.Key] = desiredProperty.Value;
   }

   Console.WriteLine("\tAlso setting current time as reported property");
   reportedProperties["DateTimeLastDesiredPropertyChangeReceived"] = DateTime.UtcNow;

   await _moduleClient.UpdateReportedPropertiesAsync(reportedProperties);
}

SDK 模組範例

適用於 .NET 的 Azure IoT SDK 提供處理模組身分識別對應項工作的裝置應用程式工作範例。如需詳細資訊，請參閱

建立後端應用程式

本節說明如何讀取和更新模組身分識別欄位。

RegistryManager 類別會公開建立後端應用程式以從服務與模組身分識別對應項互動所需的所有方法。

必要的服務 NuGet 套件

後端服務應用程式需要 Microsoft.Azure.Devices NuGet 套件。

新增這些 using 語句以使用服務連結庫。

using Microsoft.Azure.Devices;
using Microsoft.Azure.Devices.Shared;

連線到 IoT 中樞

您可以使用下列方法將後端服務連線到 IoT 中樞：

共用存取原則
Microsoft Entra

重要

本文包含使用共用存取簽章連線至服務的步驟。此驗證方法方便進行測試和評估，但使用 Microsoft Entra ID 或受控識別向服務進行驗證是更安全的方法。若要深入了解，請參閱安全性最佳做法 > 雲端安全性。

使用共用存取原則進行連線

使用 CreateFromConnectionString 將後端應用程式連線到 IoT 中樞。

UpdateModuleAsync本節中使用的方法需要 Service Connect 共用存取原則許可權，才能將所需的屬性新增至模組。作為的參數，CreateFromConnectionString請提供包含 Service Connect 許可權的共用存取原則連接字串。如需共用存取原則的詳細資訊，請參閱使用共用存取簽章控制對 IoT 中樞的存取。

例如：

static RegistryManager registryManager;
static string connectionString = "{IoT hub shared access policy connection string}";
registryManager = RegistryManager.CreateFromConnectionString(connectionString);

使用 Microsoft Entra 進行連線

使用 Microsoft Entra 的後端應用程式必須先成功驗證並取得安全性令牌認證，才能連線到 IoT 中樞。此令牌會傳遞至 IoT 中樞連接方法。如需設定和使用 Microsoft Entra 進行 IoT 中樞的一般資訊，請參閱使用 Microsoft Entra ID 控制對 IoT 中樞的存取。

設定 Microsoft Entra 應用程式

您必須設定已針對您慣用的驗證認證設定Microsoft Entra 應用程式。應用程式包含參數，例如後端應用程式用來驗證的客戶端密碼。可用的應用程式驗證群組態如下：

用戶端密碼
[MSSQLSERVER 的通訊協定內容]
同盟身分識別認證

Microsoft Entra 應用程式可能需要特定角色許可權，視執行的作業而定。例如，需要 IoT 中樞對應項參與者，才能啟用 IoT 中樞裝置和模塊對應項的讀取和寫入存取權。如需詳細資訊，請參閱使用 Azure RBAC 角色指派來管理 IoT 中樞的存取權。

如需設定 Microsoft Entra 應用程式的詳細資訊，請參閱快速入門：使用 Microsoft 身分識別平台註冊應用程式。

使用 DefaultAzureCredential 進行驗證

使用 Microsoft Entra 來驗證後端應用程式最簡單的方式是使用 DefaultAzureCredential，但建議在生產環境中使用不同的方法，包括特定TokenCredential或剖析。ChainedTokenCredential 為了簡單起見，本節說明使用 DefaultAzureCredential 和用戶端密碼的驗證。如需使用 DefaultAzureCredential之優缺點的詳細資訊，請參閱 DefaultAzureCredential 的使用指引。

DefaultAzureCredential 支援不同的驗證機制，並根據執行中的環境來判斷適當的認證類型。它會嘗試依序使用多個認證類型，直到找到有效的認證為止。

Microsoft Entra 需要下列 NuGet 套件和對應的 using 語句：

Azure.Core
Azure.Identity

using Azure.Core;
using Azure.Identity;

在此範例中，Microsoft Entra 應用程式註冊客戶端密碼、用戶端標識碼和租使用者標識元會新增至環境變數。這些環境變數是用來 DefaultAzureCredential 驗證應用程式。成功Microsoft Entra 驗證的結果是傳遞至 IoT 中樞連線方法的安全性令牌認證。

string clientSecretValue = "xxxxxxxxxxxxxxx";
string clientID = "xxxxxxxxxxxxxx";
string tenantID = "xxxxxxxxxxxxx";

Environment.SetEnvironmentVariable("AZURE_CLIENT_SECRET", clientSecretValue);
Environment.SetEnvironmentVariable("AZURE_CLIENT_ID", clientID);
Environment.SetEnvironmentVariable("AZURE_TENANT_ID", tenantID);

TokenCredential tokenCredential = new DefaultAzureCredential();

接著，產生的 TokenCredential 可以傳遞給任何接受 Microsoft Entra 認證的 SDK 用戶端的連線至 IoT 中樞方法：

在此範例中， TokenCredential 會傳遞至 ServiceClient.Create 以建立 ServiceClient 連接物件。

string hostname = "xxxxxxxxxx.azure-devices.net";
using var serviceClient = ServiceClient.Create(hostname, tokenCredential, TransportType.Amqp);

在此範例中， TokenCredential 會傳遞至 RegistryManager.Create 以建立 RegistryManager 物件。

string hostname = "xxxxxxxxxx.azure-devices.net";
registryManager = RegistryManager.Create(hostname, tokenCredential);

程式碼範例

如需Microsoft Entra 服務驗證的運作範例，請參閱角色型驗證範例。

讀取和更新模組身分識別欄位

呼叫 GetModuleAsync ，將目前的模塊識別對應項欄位擷取到 Module 物件中。

類別 Module 包含 properties 對應模組身分識別對應項的區段。使用Module類別屬性來檢視和更新模組身分識別對應項欄位。您可以使用 Module 物件屬性來更新多個字段，再使用 UpdateModuleAsync將更新寫入裝置。

進行模組身分識別對應項欄位更新之後，請呼叫 UpdateModuleAsync 將物件字段更新寫 Module 回裝置。使用 try 和 catch 邏輯與錯誤處理常式結合，從 UpdateModuleAsync 中攔截格式不正確的修補檔錯誤。

此範例會將模組擷取至 Module 物件、更新 module LastActivityTime 屬性，然後使用更新 IoT 中樞 UpdateModuleAsync中的模組。

// Retrieve the module
var module = await registryManager.GetModuleAsync("myDeviceId","myModuleId");

// Update the module object
module.LastActivityTime = DateTime.Now;

// Apply the patch to update the device twin tags section
try
{
   await registryManager.UpdateModuleAsync(module);
}
catch (Exception e)
{
   console.WriteLine("Module update failed.", e.Message);
}

其他模組 API

GetModulesOnDeviceAsync - 擷取裝置上的模組身分識別
RemoveModuleAsync - 從裝置刪除先前註冊的模組

SDK 服務範例

適用於 .NET 的 Azure IoT SDK 提供可處理模組身分識別對應項工作之服務應用程式的工作範例。如需詳細資訊，請參閱登錄管理員 E2E 測試。

建議使用 Python 3.7 版或更新版本。請務必使用安裝程式所需的 32 位元或 64 位元安裝。在安裝期間出現系統提示時，務必將 Python 新增至平台特有的環境變數。

概觀

本文說明如何使用適用於 Python 的 Azure IoT SDK 來建立模組身分識別對應項的裝置和後端服務應用程式程式代碼。

安裝套件

必須安裝 azure-iot-device 連結庫，才能建立裝置應用程式。

pip install azure-iot-device

必須安裝 azure-iot-hub 連結庫，才能建立後端服務應用程式。

pip install azure-iot-hub

msrest 連結庫可用來攔截 HTTPOperationError 例外狀況。

pip install msrest

建立裝置應用程式

本節說明如何使用裝置應用程式碼來執行下列作業：

擷取模組識別對應項，並檢查報告的屬性
更新模組身分識別對應項報告屬性
建立模組身分識別對應項所需的屬性更新回呼處理程式

重要

Import 語句

新增此 import 語句以使用裝置連結庫。

# import the device client library
import asyncio
from azure.iot.device.aio import IoTHubDeviceClient

連線到裝置

IoTHubModuleClient 類別包含可用來處理模組身分識別對應項的方法。

若要將應用程式連線到裝置，請執行下列動作：

呼叫create_from_connection_string以新增模組身分識別連接字串
呼叫 connect 將裝置用戶端連線到 Azure IoT 中樞

# import the device client library
import asyncio
from azure.iot.device.aio import IoTHubDeviceClient

# substitute the device connection string in conn_str
# and add it to the IoTHubDeviceClient object
conn_str = "{Device module identity connection string}"
device_client = IoTHubDeviceClient.create_from_connection_string(conn_str)

# connect the application to the device
await device_client.connect()

擷取模組識別對應項並檢查屬性

呼叫 get_twin，從 Azure IoT 中樞服務擷取模組識別對應項。對應項資訊會放入可檢查的變數中。

此範例會擷取裝置對應項，並使用 print 命令來檢視 JSON 格式的裝置對應項。

# get the twin
twin = await device_client.get_twin()
print("Twin document:")
print("{}".format(twin))

更新模組身分識別對應項報告屬性

您可以套用修補程式來更新 JSON 格式的模組身分識別對應項報告屬性。

若要套用修補檔以更新報告屬性，請執行下列動作：

將報告屬性 JSON 修補檔指派給變數。
呼叫 patch_twin_reported_properties 將 JSON 修補檔套用至報告屬性。

例如：

# create the reported properties patch
reported_properties = {"temperature": random.randint(320, 800) / 10}
print("Setting reported temperature to {}".format(reported_properties["temperature"]))
# update the reported properties and wait for the result
await device_client.patch_twin_reported_properties(reported_properties)

建立模組身分識別對應項所需的屬性更新回呼處理程式

呼叫 on_twin_desired_properties_patch_received ，以建立接收模塊識別對應項所需屬性修補程式時所呼叫的處理程式函式或協同程式。處理常式會採用一個引數，該引數是 JSON 字典物件形式的對應項修補檔。

此範例會設定名為 twin_patch_handler 的所需屬性修補檔處理常式。

例如：

try:
    # Set handlers on the client
    device_client.on_twin_desired_properties_patch_received = twin_patch_handler
except:
    # Clean up in the event of failure
    client.shutdown()

twin_patch_handler 會接收並列印 JSON 所需屬性更新。

    # Define behavior for receiving twin desired property patches
    def twin_patch_handler(twin_patch):
        print("Twin patch received:")
        print(twin_patch)

SDK 裝置範例

適用於 Python 的 Azure IoT SDK 提供處理模組身分識別對應項工作的裝置應用程式工作範例：

get_twin - 連線到裝置並擷取對應項資訊。
update_twin_reported_properties - 更新對應項報告屬性。
receive_twin_desired_properties - 接收和更新所需屬性。

建立後端應用程式

本節說明如何建立後端應用程式，以擷取和更新模組身分識別對應項所需的屬性。

IoTHubRegistryManager 類別會公開建立後端應用程式以從服務與模組身分識別對應項互動所需的所有方法。

服務 import 陳述式

新增此 import 語句以使用服務連結庫。

import sys
from azure.iot.hub import IoTHubRegistryManager
from azure.iot.hub.models import Twin, TwinProperties, QuerySpecification, QueryResult

連線至 IoT 中樞

您可以使用下列方法，將後端服務連線到 IoT 中樞：

共用存取原則
Microsoft Entra

重要

使用共用存取原則進行連線

使用 from_connection_string 連線到 IoT 中樞。

update_module_twin本節中使用的方法需要 Service Connect 共用存取原則許可權，才能將所需的屬性新增至模組。作為的參數，from_connection_string請提供包含 Service Connect 許可權的共用存取原則連接字串。如需共用存取原則的詳細資訊，請參閱使用共用存取簽章控制對 IoT 中樞的存取。

例如：

# Connect to IoT hub
IOTHUB_CONNECTION_STRING = "{IoT hub shared access policy connection string}"
iothub_registry_manager = IoTHubRegistryManager.from_connection_string(IOTHUB_CONNECTION_STRING)

使用 Microsoft Entra 進行連線

如需 Python SDK 驗證的概觀，請參閱使用適用於 Python 的 Azure SDK 向 Azure 服務驗證 Python 應用程式

設定 Microsoft Entra 應用程式

用戶端密碼
[MSSQLSERVER 的通訊協定內容]
同盟身分識別認證

Microsoft Entra 應用程式可能需要特定角色許可權，視執行的作業而定。例如，需要 IoT 中樞對應項參與者，才能對 IoT 中樞裝置和模組對應項啟用讀取和寫入存取權。如需詳細資訊，請參閱使用 Azure RBAC 角色指派來管理 IoT 中樞的存取權。

如需設定Microsoft Entra 應用程式的詳細資訊，請參閱快速入門：使用 Microsoft 身分識別平台註冊應用程式。

使用 DefaultAzureCredential 進行驗證

DefaultAzureCredential 支援不同的驗證機制，並根據執行中的環境來判斷適當的認證類型。它會嘗試依序使用多個認證類型，直到找到有效的認證為止。

Microsoft Entra 需要此匯入套件和對應的 import 語句：

pip install azure-identity

from azure.identity import DefaultAzureCredential

在此範例中，Microsoft Entra 應用程式註冊客戶端密碼、用戶端標識碼和租使用者標識碼已新增至環境變數。這些環境變數是用來 DefaultAzureCredential 驗證應用程式。成功Microsoft Entra 驗證的結果是傳遞至 IoT 中樞連線方法的安全性令牌認證。

from azure.identity import DefaultAzureCredential
credential = DefaultAzureCredential()

接著，產生的AccessToken可以傳遞至 from_token_credential ，以連線到任何接受 Microsoft Entra 認證的 SDK 用戶端 IoT 中樞：

IoTHubRegistryManager，使用 Entra 令牌認證建立與 IoT 中樞的服務連線。
IoTHubJobManager
DigitalTwinClient
IoTHubHttpRuntimeManager
IoTHubConfigurationManager

from_token_credential 需要兩個參數：

Azure 服務 URL - Azure 服務 URL 的格式 {Your Entra domain URL}.azure-devices.net 應該不含 https:// 前置詞。例如： MyAzureDomain.azure-devices.net 。
Azure 認證令牌

在此範例中，會使用 DefaultAzureCredential取得 Azure 認證。接著會提供 Azure 服務 URL 和認證，IoTHubRegistryManager.from_token_credential以建立與 IoT 中樞的連線。

import sys
import os

from azure.identity import DefaultAzureCredential
from azure.iot.hub import IoTHubRegistryManager

# Define the client secret values
clientSecretValue = 'xxxxxxxxxxxxxxx'
clientID = 'xxxxxxxxxxxxxx'
tenantID = 'xxxxxxxxxxxxx'

# Set environment variables
os.environ['AZURE_CLIENT_SECRET'] = clientSecretValue
os.environ['AZURE_CLIENT_ID'] = clientID
os.environ['AZURE_TENANT_ID'] = tenantID

# Acquire a credential object
credential = DefaultAzureCredential()

# Use Entra to authorize IoT Hub service
print("Connecting to IoTHubRegistryManager...")
iothub_registry_manager = IoTHubRegistryManager.from_token_credential(
url="MyAzureDomain.azure-devices.net",
token_credential=credential)

程式碼範例

如需Microsoft Entra 服務驗證的工作範例，請參閱適用於 Python 的Microsoft驗證連結庫（MSAL）。

擷取和更新模組識別對應項所需的屬性

您可以使用update_module_twin，從後端應用程式更新所需的屬性。

若要擷取和更新模組識別對應項所需的屬性：

呼叫 get_module_twin 以取得模組識別對應項的目前版本。
使用 Twin 類別，以 JSON 格式新增所需的屬性。
呼叫 update_module_twin 將修補檔套用至裝置對應項。您也可以使用 replace_module_twin 來取代模組身分識別對應項所需的屬性和標籤。

這個範例會將 telemetryInterval 所需的屬性更新為 122。

try:
    module_twin = iothub_registry_manager.get_module_twin(DEVICE_ID, MODULE_ID)
    print ( "" )
    print ( "Module identity twin properties before update:" )
    print ( "{0}".format(module_twin.properties) )

    # Update twin
    twin_patch = Twin()
    twin_patch.properties = TwinProperties(desired={"telemetryInterval": 122})
    updated_module_twin = iothub_registry_manager.update_module_twin(
        DEVICE_ID, MODULE_ID, twin_patch, module_twin.etag
    )
    print ( "" )
    print ( "Module identity twin properties after update     :" )
    print ( "{0}".format(updated_module_twin.properties) )

except Exception as ex:
    print ( "Unexpected error {0}".format(ex) )
except KeyboardInterrupt:
    print ( "IoTHubRegistryManager sample stopped" )

SDK 服務範例

適用於 Python 的 Azure IoT SDK 提供可處理裝置身分識別模組對應項工作之服務應用程式的工作範例。如需詳細資訊，請參閱測試 IoTHub 登錄管理員。

需要Node.js 10.0.x 版或更新版本

概觀

本文說明如何使用適用於 Node.js 的 Azure IoT SDK 來建立模組身分識別對應項的裝置和後端服務應用程式程式代碼。

建立裝置應用程式

本節說明如何在 Azure IoT SDK for Node.js 中使用 azure-iot-device 套件來建立裝置應用程式以執下列作業：

擷取模組識別對應項，並檢查報告的屬性
更新模組身分識別報告對應項屬性
接收模組身分識別對應項所需屬性變更的通知

重要

安裝 SDK 套件

執行此命令，在開發電腦上安裝 azure-iot-device 裝置 SDK：

npm install azure-iot-device --save

azure-iot-device 套件包含與 IoT 裝置互動的物件。 Twin 類別包含對應項特有物件。本節描述 Client 用來讀取和寫入裝置模組身分識別對應項數據的類別程序代碼。

選擇傳輸通訊協定

Client 物件支援這些通訊協定：

Amqp
Http - 使用 Http 時，Client 執行個體會不常檢查來自 IoT 中樞的訊息 (至少每25分鐘)。
Mqtt
MqttWs
AmqpWs

在開發電腦上安裝所需的傳輸通訊協定。

例如，此命令會安裝 Amqp 通訊協定：

npm install azure-iot-device-amqp --save

如需 MQTT、AMQP 和 HTTPS 支援之間差異的詳細資訊，請參閱雲端到裝置通訊指引和選擇裝置通訊協定。

建立用戶端物件

使用已安裝的套件建立 Client 物件。

例如：

const Client = require('azure-iot-device').Client;

建立通訊協議物件

使用已安裝的傳輸套件建立 Protocol 物件。

此範例會指派AMQP通訊協定：

const Protocol = require('azure-iot-device-amqp').Amqp;

新增裝置連接字串和傳輸通訊協定

呼叫 fromConnectionString 以提供裝置連線參數：

connStr - IoT 中樞身分識別模組連接字串。
transportCtor - 傳輸通訊協定。

此範例會使用 Amqp 傳輸通訊協定：

const deviceConnectionString = "{IoT hub identity module connection string}"
const Protocol = require('azure-iot-device-mqtt').Amqp;
let client = Client.fromConnectionString(deviceConnectionString, Protocol);

開啟連線到 IoT 中樞

使用 open 方法來開啟 IoT 裝置與 IoT 中樞之間的連線。

例如：

client.open(function(err) {
  if (err) {
    console.error('error connecting to hub: ' + err);
    process.exit(1);
  }
})

擷取模組識別對應項，並檢查報告的屬性

呼叫 getTwin ，將目前的模組識別對應項資訊擷取到 Twin 物件。

裝置程式代碼接著可以存取模組身分識別對應項屬性。

例如：

// Retrieve the current module identity twin
client.getTwin(function(err, twin))
if (err)
    console.error('could not get twin');

// Display the current properties
console.log('twin contents:');
console.log(twin.properties);

更新模組身分識別對應項報告屬性

使用 update 來更新裝置報告屬性。包含 JSON 格式的修補檔作為第一個參數，並包含函式執行狀態回呼方法作為方法的第二個參數。

在此範例中，JSON 格式的模組身分識別對應項修補程式會儲存在變數中 patch 。修補程式包含的cellular模組識別對應項connectivity更新值。修補檔和錯誤處理常式會傳遞至 update 方法。如果發生錯誤，則系統會顯示主控台錯誤訊息。

// Create a patch to send to IoT Hub
var patch = {
  updateTime: new Date().toString(),
  firmwareVersion:'1.2.1',
  weather:{
    temperature: 72,
    humidity: 17
  }
};

// Apply the patch
twin.properties.reported.update(patch, function(err)
  {
    if (err)
      {
        console.error('could not update twin');
      } 
    else
      {
        console.log('twin state reported');
        process.exit();
      }
  });

接收模組身分識別對應項所需屬性變更的通知

建立模組身分識別對應項所需屬性更新事件接聽程式，此接聽程式會藉由將回呼處理程式方法名稱傳遞至 twin.on，以在變更所需屬性時執行。

所需的屬性事件接聽程式可以採用下列形式：

使用單一事件處理常式接收所有修補檔
屬性群組下有任何變更時接收事件
接收單一屬性變更的事件

使用單一事件處理常式接收所有修補檔

您可以建立接聽程式來接收任何所需屬性變更。

此範例程式碼會輸出從服務接收的任何屬性。

twin.on('properties.desired', function (delta) {
    console.log('new desired properties received:');
    console.log(JSON.stringify(delta));
});

屬性群組下有任何變更時接收事件

如果屬性群組下有任何變更，您可以建立接聽程式來接收事件。

例如：

minTemperature 和 maxTemperature 屬性位於名為 properties.desired.climate changes 的屬性群組之下。

後端服務應用程式會套用此修補檔來更新 minTemperature 和 maxTemperature 所需屬性：

const twinPatch1 = {
properties: {
   desired: {
    climate: { minTemperature: 68, maxTemperature: 76, },
    },
  },
 };

此程式代碼會設定所需的屬性變更事件接聽程式，以觸發屬性群組內 properties.desired.climate 的任何變更。如果此群組內有想要的屬性變更，則會向主控台顯示最小和最大溫度變更訊息：

twin.on('properties.desired.climate', function (delta) {
    if (delta.minTemperature || delta.maxTemperature) {
        console.log('updating desired temp:');
        console.log('min temp = ' + twin.properties.desired.climate.minTemperature);
        console.log('max temp = ' + twin.properties.desired.climate.maxTemperature);
    }
});

接收單一屬性變更的事件

您可以為單一屬性變更設定接聽程式。在此範例中，只有當 fanOn 布林值是修補檔的一部分時，才會執行此事件的程式碼。每當服務更新時，程式碼就會輸出新的所需 fanOn 狀態。

後端應用程式會套用這個所需屬性修補檔：

 const twinPatch2 = {
  properties: {
    desired: {
      climate: {
        hvac: {
          systemControl: { fanOn: true, },
        },
      },
    },
  },
};

只有在 fanOn 屬性變更時，才會觸發接聽程式：

 twin.on('properties.desired.climate.hvac.systemControl', function (fanOn) {
     console.log('setting fan state to ' + fanOn);
  });

完整範例

此範例會封裝本節的原則，包括多層級回呼函式巢狀。

var Client = require('azure-iot-device').Client;
var Protocol = require('azure-iot-device-amqp').Amqp;
// Copy/paste your module connection string here.
var connectionString = 'HostName=xxx.azure-devices.net;DeviceId=myFirstDevice2;ModuleId=myFirstModule2;SharedAccessKey=xxxxxxxxxxxxxxxxxx';
// Create a client using the Amqp protocol.
var client = Client.fromConnectionString(connectionString, Protocol);
client.on('error', function (err) {
  console.error(err.message);
});
// connect to the hub
client.open(function(err) {
  if (err) {
    console.error('error connecting to hub: ' + err);
    process.exit(1);
  }
  console.log('client opened');
// Create device Twin
  client.getTwin(function(err, twin) {
    if (err) {
      console.error('error getting twin: ' + err);
      process.exit(1);
    }
    // Output the current properties
    console.log('twin contents:');
    console.log(twin.properties);
    // Add a handler for desired property changes
    twin.on('properties.desired', function(delta) {
        console.log('new desired properties received:');
        console.log(JSON.stringify(delta));
    });
    // create a patch to send to the hub
    var patch = {
      updateTime: new Date().toString(),
      firmwareVersion:'1.2.1',
      weather:{
        temperature: 75,
        humidity: 20
      }
    };
    // send the patch
    twin.properties.reported.update(patch, function(err) {
      if (err) throw err;
      console.log('twin state reported');
    });

  });
});

裝置 SDK 範例

適用於 Node.js的 Azure IoT SDK 提供處理模組身分識別對應項工作的裝置應用程式工作範例。如需詳細資訊，請參閱

建立後端應用程式

本節說明如何建立可擷取模組身分識別對應項和更新所需屬性的後端應用程式。

安裝服務 SDK 套件

執行此命令，在開發電腦上安裝 azure-iothub：

npm install azure-iothub --save

建立登錄物件

Registry 類別會公開從後端應用程式與模組身分識別對應項互動所需的所有方法。

let Registry = require('azure-iothub').Registry;

連線至 IoT 中樞

您可以使用下列方法將後端服務連線至 IoT 中樞：

共用存取原則
Microsoft Entra

重要

使用共用存取原則進行連線

使用 fromConnectionString 連線到 IoT 中樞。

update本節中使用的方法需要 Service Connect 共用存取原則許可權，才能將所需的屬性新增至模組。作為的參數，fromConnectionString請提供包含 Service Connect 許可權的共用存取原則連接字串。如需共用存取原則的詳細資訊，請參閱使用共用存取簽章控制對 IoT 中樞的存取。

let connectionString = '{IoT hub shared access policy connection string}';
let registry = Registry.fromConnectionString(serviceConnectionString);

使用 Microsoft Entra 進行連線

使用 Microsoft Entra 的後端應用程式必須先成功驗證並取得安全性令牌認證，才能連線到 IoT 中樞。此令牌會傳遞至 IoT 中樞連接方法。如需設定和使用 Microsoft Entra 進行 IoT 中樞的一般資訊，請參閱使用 Microsoft Entra 識別符控制對 IoT 中樞的存取。

如需Node.js SDK 驗證的概觀，請參閱：

設定 Microsoft Entra 應用程式

用戶端密碼
[MSSQLSERVER 的通訊協定內容]
同盟身分識別認證

如需設定 Microsoft Entra 應用程式的詳細資訊，請參閱快速入門：向 Microsoft 身分識別平台註冊應用程式。

使用 DefaultAzureCredential 進行驗證

DefaultAzureCredential 支援不同的驗證機制，並根據執行中的環境來判斷適當的認證類型。它會嘗試依序使用多個認證類型，直到找到有效的認證為止。

Microsoft Entra 需要此套件：

npm install --save @azure/identity

import { DefaultAzureCredential } from "@azure/identity";

// Azure SDK clients accept the credential as a parameter
const credential = new DefaultAzureCredential();

然後，產生的認證令牌可以傳遞至 fromTokenCredential，以連線到任何接受 Microsoft Entra 認證的 SDK 用戶端 IoT 中樞：

fromTokenCredential 需要兩個參數：

Azure 服務 URL - Azure 服務 URL 的格式 {Your Entra domain URL}.azure-devices.net 應該不含 https:// 前置詞。例如： MyAzureDomain.azure-devices.net 。
Azure 認證令牌

在此範例中，會使用 DefaultAzureCredential取得 Azure 認證。接著會提供 Azure 網域 URL 和認證，Registry.fromTokenCredential以建立 IoT 中樞的連線。

const { DefaultAzureCredential } = require("@azure/identity");

let Registry = require('azure-iothub').Registry;

// Define the client secret values
clientSecretValue = 'xxxxxxxxxxxxxxx'
clientID = 'xxxxxxxxxxxxxx'
tenantID = 'xxxxxxxxxxxxx'

// Set environment variables
process.env['AZURE_CLIENT_SECRET'] = clientSecretValue;
process.env['AZURE_CLIENT_ID'] = clientID;
process.env['AZURE_TENANT_ID'] = tenantID;

// Acquire a credential object
const credential = new DefaultAzureCredential()

// Create an instance of the IoTHub registry
hostName = 'MyAzureDomain.azure-devices.net';
let registry = Registry.fromTokenCredential(hostName,credential);

程式碼範例

如需Microsoft Entra 服務驗證的工作範例，請參閱 Azure 身分識別範例。

擷取模組身分識別對應項並更新所需的屬性

您可以建立包含模組識別對應項所需屬性更新的修補程式。

若要更新模組身分識別對應項：

呼叫 getModuleTwin 以擷取裝置 Twin 物件。
格式化包含模組身分識別對應項更新的修補程式。如 Twin 類別中所述，修補檔的格式為 JSON。後端服務修補程式包含所需的屬性更新。如需更多修補檔格式資訊，請參閱標籤和屬性格式。
呼叫更新以使用修補程式更新模組識別對應項。

在此範例中，會針對 myDeviceId 和 myModuleId擷取模組識別對應項。然後，會將修補程式套用至包含信息的對應項 climate 。

// Insert your device ID and moduleId here.
var deviceId = 'myFirstDevice2';
var moduleId = 'myFirstModule2';

// Retrieve the current module identity twin
registry.getModuleTwin(deviceId, moduleId, function (err, twin) {
  console.log('getModuleTwin returned ' + (err ? err : 'success'));
  if (err) {
    console.log(err);
  } else {
    console.log('success');
    console.log('Current twin:' + JSON.stringify(twin))

    // Format a desired property patch
    const twinPatch1 = {
      properties: {
        desired: {
          climate: { minTemperature: 69, maxTemperature: 77, },
        },
      },
    };

    // Send the desired property patch to IoT Hub
    twin.update(twinPatch1, function(err) {
    if (err) throw err;
    console.log('twin state reported');
    });
  }
});

服務 SDK 範例

適用於Node.js的 Azure IoT SDK 提供處理模組身分識別對應項工作之服務應用程式的工作範例。如需詳細資訊，請參閱

共用方式為

開始使用 IoT 中樞 模組身分識別和模組身分識別對應項

必要條件

概觀

建立裝置應用程式

必要的裝置 NuGet 套件

連線到裝置

擷取模組識別對應項並檢查屬性

更新模組身分識別對應項報告屬性

建立所需的屬性更新回呼處理常式

SDK 模組範例

建立後端應用程式

必要的服務 NuGet 套件

連線到 IoT 中樞

使用共用存取原則進行連線

使用 Microsoft Entra 進行連線

設定 Microsoft Entra 應用程式

使用 DefaultAzureCredential 進行驗證

程式碼範例

讀取和更新模組身分識別欄位

其他模組 API

SDK 服務範例

概觀

安裝套件

建立裝置應用程式

Import 語句

連線到裝置

擷取模組識別對應項並檢查屬性

更新模組身分識別對應項報告屬性

建立模組身分識別對應項所需的屬性更新回呼處理程式

SDK 裝置範例

建立後端應用程式

服務 import 陳述式

連線至 IoT 中樞

使用共用存取原則進行連線

使用 Microsoft Entra 進行連線

設定 Microsoft Entra 應用程式

使用 DefaultAzureCredential 進行驗證

程式碼範例

擷取和更新模組識別對應項所需的屬性

SDK 服務範例

概觀

建立裝置應用程式

安裝 SDK 套件

選擇傳輸通訊協定

建立用戶端物件

建立通訊協議物件

新增裝置連接字串和傳輸通訊協定

開啟連線到 IoT 中樞

擷取模組識別對應項，並檢查報告的屬性

更新模組身分識別對應項報告屬性

接收模組身分識別對應項所需屬性變更的通知

使用單一事件處理常式接收所有修補檔

屬性群組下有任何變更時接收事件

接收單一屬性變更的事件

完整範例

裝置 SDK 範例

建立後端應用程式

安裝服務 SDK 套件

建立登錄物件

連線至 IoT 中樞

使用共用存取原則進行連線

使用 Microsoft Entra 進行連線

設定 Microsoft Entra 應用程式

使用 DefaultAzureCredential 進行驗證

程式碼範例

擷取模組身分識別對應項並更新所需的屬性

服務 SDK 範例

意見反應

其他資源

開始使用 IoT 中樞模組身分識別和模組身分識別對應項