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

發行項
04/07/2024

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

注意

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

使用裝置對應項以：

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

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

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

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

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

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

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

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

本文章說明如何：

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

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

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

注意

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

必要條件

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

取得 IoT 中樞連接字串

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

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

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

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

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

在本節中，您會建立 .NET 控制台應用程式，以 myDeviceId 連線到您的中樞，然後更新其報告屬性，以確認其已使用行動數據網路連線。

開啟 Visual Studio，然後選取 [ 建立新專案]。
選擇 [控制台應用程式][.NET Framework]，然後選取 [ 下一步]。
在 [設定新專案] 中，將專案命名為 Report 連線 ivity，然後選取 [下一步]。
在方案總管中，以滑鼠右鍵按兩下 [報表連線 ivity 專案]，然後選取 [管理 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 物件會公開您需要從裝置與裝置對應項互動的所有方法。上述程式代碼會初始化 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();

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

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

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

在本節中，您會使用 C# 建立 .NET 控制台應用程式，以將位置元數據新增至與 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 工廠的裝置對應項，第二個查詢會精簡查詢，只選取也透過行動數據網路連線的裝置。

在建立查詢物件時，上述程式代碼會指定傳回的檔數目上限。查詢物件包含 HasMoreResults 布爾值屬性，可用來叫用 GetNextAsTwinAsync 方法多次擷取所有結果。稱為 GetNextAsJson 的方法可用於不是裝置對應項的結果，例如匯總查詢的結果。

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

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

以滑鼠右鍵按兩下 AddTagsAndQuery 項目並選取 [偵錯]，然後選取 [啟動新實例]，以執行此應用程式。您應該會在查詢結果中看到一個裝置，要求所有位於 Redmond43 的裝置，且查詢中沒有一個裝置，該查詢會將結果限製為使用行動數據網路的裝置。

在本文章中，您將：

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

下一步

若要了解如何：

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

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

必要條件

取得 IoT 中樞連接字串

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

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

下一步

其他資源

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