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

發行項
06/27/2024

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

注意

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

使用裝置對應項以：

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

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

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

標籤。只有解決方案後端可存取裝置中繼資料。
預期屬性。 JSON 物件可由解決方案後端修改，並依裝置應用程式查看。
回報的屬性。 JSON 物件可由裝置應用程式修改，並由解決方案後端讀取。

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

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

裝置對應項概念圖的螢幕擷取畫面。

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

本文章說明如何：

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

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

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

注意

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

必要條件

Visual Studio。
Azure 訂用帳戶中的 IoT 中樞。如果您還沒有中樞，可遵循建立 IoT 中樞中的步驟。
在 IoT 中樞內註冊的裝置。如果 IoT 中樞中沒有裝置，請遵循註冊裝置中的步驟。
請確定您的防火牆已開啟連接埠 8883。本文中的裝置範例會使用 MQTT 通訊協定，其會透過連接埠 8883 進行通訊。某些公司和教育網路環境可能會封鎖此連接埠。如需此問題的詳細資訊和解決方法，請參閱連線至 IoT 中樞 (MQTT)。

取得 IoT 中樞連接字串

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

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

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

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

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

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

開啟 Visual Studio，然後選取 [建立新專案]。
選擇 [主控台應用程式 (.NET Framework)]，然後選取 [下一步]。
在 [設定新專案] 中，將專案命名為 ReportConnectivity，然後選取 [下一步]。
在 [方案總管] 中，以滑鼠右鍵按一下 [ReportConnectivity] 專案，然後選取 [管理 NuGet 套件]。
保留預設 .NET Framework，然後選取 [建立] 以建立專案。
選取 [瀏覽]，然後搜尋並選擇 [Microsoft.Azure.Devices.Client]。選取安裝。

此步驟會下載和安裝 Azure IoT 裝置 SDK NuGet 套件及其相依性，並新增其參考。

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

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

將下列欄位新增到 Program 類別。將 {device connection string} 取代為您在 IoT 中樞註冊新裝置時看到的裝置連接字串：

static string DeviceConnectionString = "HostName=<yourIotHubName>.azure-devices.net;DeviceId=<yourIotDeviceName>;SharedAccessKey=<yourIotDeviceAccessKey>";
static DeviceClient Client = null;

將下列方法加入至 Program 類別：

public static async void InitClient()
{
    try
    {
        Console.WriteLine("Connecting to hub");
        Client = DeviceClient.CreateFromConnectionString(DeviceConnectionString, 
          TransportType.Mqtt);
        Console.WriteLine("Retrieving twin");
        await Client.GetTwinAsync();
    }
    catch (Exception ex)
    {
        Console.WriteLine();
        Console.WriteLine("Error in sample: {0}", ex.Message);
    }
}

Client 物件會公開從裝置來與裝置對應項進行互動時所需的所有方法。以上所示的程式碼會初始化用戶端物件，然後擷取 myDeviceId 的裝置對應項。

將下列方法加入至 Program 類別：

public static async void ReportConnectivity()
{
    try
    {
        Console.WriteLine("Sending connectivity data as reported property");

        TwinCollection reportedProperties, connectivity;
        reportedProperties = new TwinCollection();
        connectivity = new TwinCollection();
        connectivity["type"] = "cellular";
        reportedProperties["connectivity"] = connectivity;
        await Client.UpdateReportedPropertiesAsync(reportedProperties);
    }
    catch (Exception ex)
    {
        Console.WriteLine();
        Console.WriteLine("Error in sample: {0}", ex.Message);
    }
}

上述程式碼會以連線資訊來更新 myDeviceId 的報告屬性。

最後，將下列幾行新增至 Main 方法：

try
{
    InitClient();
    ReportConnectivity();
}
catch (Exception ex)
{
    Console.WriteLine();
    Console.WriteLine("Error in sample: {0}", ex.Message);
}
Console.WriteLine("Press Enter to exit.");
Console.ReadLine();

在 [方案總管] 中，以滑鼠右鍵按一下方案，然後選取 [設定啟始專案]。
在 [通用屬性]>[啟始專案] 中，選取 [多個啟始專案]。針對 [ReportConnectivity]，選取 [啟動] 作為 [動作]。選取 [確定] 以儲存您的變更。
以滑鼠右鍵按一下 [ReportConnectivity] 專案，然後依序選取 [偵錯]和 [開始新執行個體] 來執行此應用程式。您應該會看到應用程式取得對應項資訊，然後傳送連線作為報告屬性。

在裝置回報其連線資訊之後，應該會出現在這兩個查詢中。
以滑鼠右鍵按一下 [AddTagsAndQuery] 專案，然後選取 [偵錯]>[開始新執行個體] 以再次執行查詢。這次，myDeviceId 應該會出現在這兩個查詢結果中。

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

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

在 Visual Studio 中，選取 [檔案] -> [新增] -> [專案]。在 [建立新專案] 中，選取 [主控台應用程式 (.NET Framework)]，然後選取 [下一步]。
在 [設定新專案] 中，將專案命名為 AddTagsAndQuery，然後選取 [下一步]。
接受預設版本的 .NET Framework，然後選取 [建立] 以建立專案。
在 [方案總管] 中，以滑鼠右鍵按一下 [AddTagsAndQuery] 專案，然後選取 [管理 NuGet 套件]。
選取 [瀏覽]，然後搜尋並選取 [Microsoft.Azure.Devices]。選取 [安裝]。

此步驟會下載及安裝 Azure IoT 服務 SDK NuGet 套件與其相依性，並加入對它的參考。
在 Program.cs 檔案開頭處新增下列 using 陳述式：
```
using Microsoft.Azure.Devices;
```
將下列欄位新增到 Program 類別。將 {iot hub connection string} 取代為在取得 IoT 中樞連接字串內複製的 IoT 中樞連接字串。
```
static RegistryManager registryManager;
static string connectionString = "{iot hub connection string}";
```

將下列方法加入至 Program 類別：

public static async Task AddTagsAndQuery()
{
    var twin = await registryManager.GetTwinAsync("myDeviceId");
    var patch =
        @"{
            tags: {
                location: {
                    region: 'US',
                    plant: 'Redmond43'
                }
            }
        }";
    await registryManager.UpdateTwinAsync(twin.DeviceId, patch, twin.ETag);

    var query = registryManager.CreateQuery(
      "SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'", 100);
    var twinsInRedmond43 = await query.GetNextAsTwinAsync();
    Console.WriteLine("Devices in Redmond43: {0}", 
      string.Join(", ", twinsInRedmond43.Select(t => t.DeviceId)));

    query = registryManager.CreateQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity.type = 'cellular'", 100);
    var twinsInRedmond43UsingCellular = await query.GetNextAsTwinAsync();
    Console.WriteLine("Devices in Redmond43 using cellular network: {0}", 
      string.Join(", ", twinsInRedmond43UsingCellular.Select(t => t.DeviceId)));
}

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

在更新後，它會執行兩個查詢：第一個只選取位於 Redmond43 工廠的裝置對應項，第二個會修改查詢，只選取也透過行動電話網路來連接的裝置。

先前的程式碼在建立查詢物件時，指定傳回的最大文件數。 query 物件包含 HasMoreResults 布林值屬性，可用來多次叫用 GetNextAsTwinAsync 方法以擷取所有結果。有一個稱為 GetNextAsJson 的方法適用於不是裝置對應項的結果，例如彙總查詢的結果。

最後，將下列幾行新增至 Main 方法：

registryManager = RegistryManager.CreateFromConnectionString(connectionString);
AddTagsAndQuery().Wait();
Console.WriteLine("Press Enter to exit.");
Console.ReadLine();

以滑鼠右鍵按一下 AddTagsAndQuery 專案，並選取 [偵錯]，後面接著 [開始新執行個體] 來執行此應用程式。如果是查詢所有位於 Redmond43 中的裝置，您在結果中會看到一個裝置，而如果查詢將結果限於使用行動電話網路的裝置，則您不會看到任何裝置。

在本文章中，您將：

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

下一步

若要了解如何：

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

共用方式為

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

必要條件

取得 IoT 中樞連接字串

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

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

下一步

意見反應

意見反應

其他資源