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

發行項
05/30/2024

模組身分識別與模組對應項類似於 Azure IoT 中樞裝置身分識別與裝置對應項，但提供更精細的細微性。雖然 Azure IoT 中樞裝置身分識別與裝置對應項可讓後端應用程式設定裝置並提供裝置狀況的可見性，但模組身分識別和模組對應項可提供裝置個別元件的上述功能。在具有多個元件的支援裝置 (例如作業系統裝置或韌體裝置) 上，模組身分識別和模組對應項允許每個元件使用獨立的設定和條件。

注意

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

在本文結尾處，您會有兩個 .NET 主控台應用程式：

CreateIdentities：這會建立裝置身分識別、模組身分識別和相關聯的安全性金鑰，以連線到您的裝置和模組用戶端。
UpdateModuleTwinReportedProperties：這會將已更新的模組對應項報告的屬性傳送到您的 IoT 中樞。

注意

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

必要條件

Visual Studio。
IoT 中樞。使用 CLI 或 Azure 入口網站建立一個。

模組驗證

您可以使用對稱金鑰或 X.509 憑證來驗證模組身分識別。針對 X.509 憑證驗證，模組憑證的一般名稱 (CN)「必須」具有如 CN=<deviceid>/<moduleid> 的格式。例如：

openssl req -new -key d1m1.key.pem -out d1m1.csr -subj "/CN=device01\/module01"

取得 IoT 中樞連接字串

在本文中，您會建立後端服務，以在身分識別登錄中新增裝置，然後將模組新增至該裝置。您的服務需要登錄寫入權限。根據預設，每個 IoT 中樞都是使用授與此權限且名為 registryReadWrite 的共用存取原則所建立。

若要取得 registryReadWrite 原則的 IoT 中樞連接字串，請遵循下列步驟：

在 Azure 入口網站中，選取 [資源群組]。選取中樞所在的資源群組，然後從資源清單選取中樞。
在中樞的左側窗格中，選取 [共用存取原則]。
從原則清單中，選取 registryReadWrite 原則。
複製 [主要連接字串] 並儲存該值。

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

建立模組身分識別

在本節中，您會建立 .NET 主控台應用程式，其會在中樞的身分識別登錄中建立裝置身分識別和模組身分識別。裝置或模組無法連線到中樞，除非其在身分識別登錄中具有輸入。如需詳細資訊，請參閱 IoT 中樞開發人員指南的＜身分識別登錄＞一節。

當您執行此主控台應用程式時，它會針對裝置和模組產生唯一的識別碼和金鑰。當裝置和模組將裝置到雲端的訊息傳送給 IoT 中樞時，裝置和模組會使用這些值來識別自己。識別碼會區分大小寫。

開啟 Visual Studio，然後選取 [建立新專案]。
在 [建立新專案] 中，選取 [主控台應用程式 (.NET Framework)]。
選取 [下一步] 以開啟 [設定您的新專案]。將專案命名為 CreateIdentities，然後選取 [下一步]。
保留預設的 .NET Framework 選項，然後選取 [建立] 以建立專案。
在 Visual Studio 中，依序開啟 [工具]> [NuGet 套件管理員]> [管理解決方案的 NuGet 套件]。選取 [瀏覽] 索引標籤。
搜尋 Microsoft.Azure.Devices。加以選取，然後選取 [安裝]。

在 Program.cs 檔案開頭處新增下列 using 陳述式：

using Microsoft.Azure.Devices;
using Microsoft.Azure.Devices.Common.Exceptions;

將下列欄位新增到 Program 類別。將預留位置的值替換為您在上一節中為中樞所建立的 IoT 中樞連接字串。

const string connectionString = "<replace_with_iothub_connection_string>";
const string deviceID = "myFirstDevice";
const string moduleID = "myFirstModule";

將以下程式碼新增至 Main 類別。

static void Main(string[] args)
{
    AddDeviceAsync().Wait();
    AddModuleAsync().Wait();
}

將下列方法新增至 Program 類別：

private static async Task AddDeviceAsync()
{
   RegistryManager registryManager = 
     RegistryManager.CreateFromConnectionString(connectionString);
   Device device;

   try
   {
       device = await registryManager.AddDeviceAsync(new Device(deviceID));
   }
   catch (DeviceAlreadyExistsException)
    {
        device = await registryManager.GetDeviceAsync(deviceID);
    }

    Console.WriteLine("Generated device key: {0}", 
      device.Authentication.SymmetricKey.PrimaryKey);
}

private static async Task AddModuleAsync()
{
    RegistryManager registryManager = 
      RegistryManager.CreateFromConnectionString(connectionString);
    Module module;

    try
    {
        module = 
          await registryManager.AddModuleAsync(new Module(deviceID, moduleID));
    }
    catch (ModuleAlreadyExistsException)
    {
        module = await registryManager.GetModuleAsync(deviceID, moduleID);
    }

    Console.WriteLine("Generated module key: {0}", module.Authentication.SymmetricKey.PrimaryKey);
}

AddDeviceAsync 方法會建立具有識別碼 myFirstDevice 的裝置身分識別。如果該裝置識別碼已經存在身分識別登錄中，程式碼就只會擷取現有的裝置資訊。接著，應用程式會顯示該身分識別的主要金鑰。您會在模擬裝置應用程式中使用此金鑰來連線到中樞。

AddModuleAsync 方法會在裝置 myFirstDevice 之下建立具有識別碼 myFirstModule 的模組身分識別。如果該模組識別碼已經存在身分識別登錄中，程式碼就只會擷取現有的模組資訊。接著，應用程式會顯示該身分識別的主要金鑰。您會在模擬模組應用程式中使用此金鑰來連線到中樞。

重要

裝置識別碼可能會顯示在為了客戶支援和疑難排解而收集的記錄中，因此務必避免在命名時使用任何敏感性資訊。

執行此應用程式，並記下裝置金鑰和模組金鑰。

注意

IoT 中樞身分識別登錄只會儲存裝置和模組身分識別，以啟用對中樞的安全存取。身分識別登錄會儲存裝置識別碼和金鑰，以作為安全性認證使用。身分識別登錄也會儲存每個裝置的已啟用/已停用旗標，以便您用來停用該裝置的存取權。如果您的應用程式需要儲存其他裝置特定的中繼資料，其應該使用應用程式特定的存放區。模組身分識別沒有啟用/停用旗標。如需詳細資訊，請參閱 IoT 中樞開發人員指南。

使用 .NET 裝置 SDK 更新模組對應項

接著，我們要從模擬裝置與雲端通訊。一旦建立模組身分識別，模組對應項會隱含地建立於 IoT 中樞中。在這一節中，您會在模擬裝置上建立 .NET 主控台應用程式，以便更新模組對應項報告的屬性。

如要擷取您的模組連接字串，請巡覽至 IoT 中樞，然後選取 [裝置]。找到並選取 myFirstDevice 加以開啟，然後選取 myFirstModule 加以開啟。在 [模組身分識別詳細資料] 中，複製 [連接字串 (主索引鍵)]，並為主控台應用程式儲存該項目。

在 Visual Studio 中，選取 [檔案]> [新增]> [專案]，將新專案新增至解決方案。在 [建立新專案] 中，選取 [主控台應用程式 (.NET Framework)]，然後選取 [下一步]。
在 [設定新專案] 中，將專案命名為 UpdateModuleTwinReportedProperties 然後選取 [下一步]。
保留預設的 .NET Framework 選項，然後選取 [建立] 以建立專案。
在 Visual Studio 中，依序開啟 [工具]> [NuGet 套件管理員]> [管理解決方案的 NuGet 套件]。選取 [瀏覽] 索引標籤。
搜尋並選取 [Microsoft.Azure.Devices.Client]，然後選取 [安裝]。

在 Program.cs 檔案開頭處新增下列 using 陳述式：

using Microsoft.Azure.Devices.Client;
using Microsoft.Azure.Devices.Shared;
using System.Threading.Tasks;
using Newtonsoft.Json;

將下列欄位新增到 Program 類別。使用模組連接字串取代預留位置值。

private const string ModuleConnectionString = "<Your module connection string>";
private static ModuleClient Client = null;
static void ConnectionStatusChangeHandler(ConnectionStatus status, 
  ConnectionStatusChangeReason reason)
{
    Console.WriteLine("Connection Status Changed to {0}; the reason is {1}", 
      status, reason);
}

將下列方法 OnDesiredPropertyChanged 新增至 Program 類別：

private static async Task OnDesiredPropertyChanged(TwinCollection desiredProperties, 
  object userContext)
    {
        Console.WriteLine("desired property change:");
        Console.WriteLine(JsonConvert.SerializeObject(desiredProperties));
        Console.WriteLine("Sending current time as reported property");
        TwinCollection reportedProperties = new TwinCollection
        {
            ["DateTimeLastDesiredPropertyChangeReceived"] = DateTime.Now
        };

        await Client.UpdateReportedPropertiesAsync(reportedProperties).ConfigureAwait(false);
    }

在 Main 方法中新增下列幾行：

static void Main(string[] args)
{
    Microsoft.Azure.Devices.Client.TransportType transport = 
      Microsoft.Azure.Devices.Client.TransportType.Amqp;

    try
    {
        Client = 
          ModuleClient.CreateFromConnectionString(ModuleConnectionString, transport);
        Client.SetConnectionStatusChangesHandler(ConnectionStatusChangeHandler);
        Client.SetDesiredPropertyUpdateCallbackAsync(OnDesiredPropertyChanged, null).Wait();

        Console.WriteLine("Retrieving twin");
        var twinTask = Client.GetTwinAsync();
        twinTask.Wait();
        var twin = twinTask.Result;
        Console.WriteLine(JsonConvert.SerializeObject(twin.Properties)); 

        Console.WriteLine("Sending app start time as reported property");
        TwinCollection reportedProperties = new TwinCollection();
        reportedProperties["DateTimeLastAppLaunch"] = DateTime.Now;

        Client.UpdateReportedPropertiesAsync(reportedProperties);
    }
    catch (AggregateException ex)
    {
        Console.WriteLine("Error in sample: {0}", ex);
    }

    Console.WriteLine("Waiting for Events.  Press enter to exit...");
    Console.ReadLine();
    Client.CloseAsync().Wait();
}

您現在已了解如何擷取模組對應項，並使用 AMQP 通訊協定更新報告的屬性。

您可以選擇性地將這些陳述式新增至 Main 方法，以從模組將事件傳送至 IoT 中樞。將這些行放在 try catch 區塊下方。

Byte[] bytes = new Byte[2];
bytes[0] = 0;
bytes[1] = 1;
var sendEventsTask = Client.SendEventAsync(new Message(bytes));
sendEventsTask.Wait();
Console.WriteLine("Event sent to IoT Hub.");

執行應用程式

您現在可以執行應用程式。

在 Visual Studio 的方案總管中，以滑鼠右鍵按一下解決方案，然後選取 [設定啟始專案]。
在 [通用屬性] 下，選取 [啟始專案]。
選取 [多個起始專案]，然後選取 [啟動] 做為應用程式的動作，然後選取 [確定] 以接受變更。
按 F5 鍵啟動應用程式。

下一步

若要繼續開始使用 IoT 中樞並瀏覽其他 IoT 案例，請參閱︰

共用方式為