開始使用裝置對應項目（Azure CLI）

發行項
01/29/2024

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

注意

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

使用裝置對應項以：

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

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

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

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

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

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

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

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

本文章說明如何：

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

如需使用裝置對應項報告屬性的詳細資訊，請參閱裝置到雲端通訊指引。

本文說明如何建立兩個 Azure CLI 會話：

建立模擬裝置的會話。模擬裝置會在初始化時，將其連線通道報告為裝置對應裝置對應項上的報告屬性。
更新模擬裝置之裝置對應項標籤的工作階段，然後從IoT中樞查詢裝置。查詢會根據先前在這兩個會話中更新的標記和屬性使用篩選。

必要條件

Azure CLI。您也可以使用 Azure Cloud Shell 來執行本文中的命令，這是在瀏覽器中或應用程式中執行的互動式 CLI 殼層，例如 Windows 終端機。如果您使用 Cloud Shell，則不需要安裝任何專案。如果您想要在本機使用 CLI，本文需要 Azure CLI 2.36 版或更新版本。執行 az --version 以尋找版本。若要在本機安裝或升級 Azure CLI，請參閱安裝 Azure CLI。
一個 IoT 中樞。使用 CLI 或 Azure 入口網站建立一個。
請確定您的防火牆中已開啟埠 8883。本文中的範例會使用透過埠 8883 通訊的 MQTT 通訊協定。在某些公司和教育網路環境中，此埠可能會遭到封鎖。如需此問題的詳細資訊和解決方法，請參閱連線至 IoT 中樞 (MQTT)。

準備 Cloud Shell

如果您想要使用 Azure Cloud Shell，您必須先啟動並設定它。如果您在本機使用 CLI，請跳至準備兩個 CLI 會話一節。

從 Azure 入口網站的頁首選取 Cloud Shell 圖示。

注意

如果這是您第一次使用 Cloud Shell，它會提示您建立記憶體，這是使用 Cloud Shell 的必要專案。選取用來建立儲存體帳戶和 Microsoft Azure 檔案共用的訂用帳戶。
使用 Cloud Shell 工具列中的環境選取器來選取您慣用的 CLI 環境。本文使用 Bash 環境。您也可以使用 PowerShell 環境。

注意

某些命令在 Bash 和 PowerShell 環境中需要不同的語法或格式設定。 如需詳細資訊，請參閱成功使用 Azure CLI 的提示。

準備兩個 CLI 工作階段

接下來，您必須準備兩個 Azure CLI 工作階段。如果您使用 Cloud Shell，您可以在個別的 Cloud Shell 索引標籤中執行這些工作階段。如果使用本機 CLI 用戶端，您可以執行個別的 CLI 實例。針對下列工作使用個別的 CLI 工作階段：

第一個會話會模擬與IoT中樞通訊的IoT裝置。
第二個會話會更新模擬裝置，並查詢IoT中樞。

如果您使用 Cloud Shell，請跳至下一個步驟。否則，請在第一個 CLI 會話中執行 az login 命令，以登入您的 Azure 帳戶。

如果您使用 Cloud Shell，則會自動登入您的 Azure 帳戶。 Azure CLI 會話與 IoT 中樞之間的所有通訊都會經過驗證和加密。因此，本文不需要搭配實際裝置使用的額外驗證，例如連接字串。如需使用 Azure CLI 登入的詳細資訊，請參閱使用 Azure CLI 登入。
```
az login
```
在第一個 CLI 工作階段中，執行 az extension add 命令。此命令會將適用於 Azure CLI 的 Microsoft Azure IoT 擴充功能新增至 CLI 殼層。此擴充功能會將 IoT 中樞、IoT Edge 和 IoT 裝置佈建服務（DPS）特定命令新增至 Azure CLI。安裝擴充功能之後，您不需要在任何 Cloud Shell 工作階段中再次安裝。
```
az extension add --name azure-iot
```
注意

本文使用最新版的 Azure IoT 擴充功能，稱為 azure-iot。舊版則稱為 azure-cli-iot-ext。您一次只能安裝一個版本。您可以使用 az extension list 命令來驗證目前安裝的延伸模組。

使用 az extension remove --name azure-cli-iot-ext 移除舊版的擴充功能。

使用 az extension add --name azure-iot 新增新版的擴充功能。

若要查看您已安裝的擴充功能，請使用 az extension list。
開啟第二個 CLI 工作階段。如果您在瀏覽器中使用 Cloud Shell，請選取 第一個 CLI 工作階段工具列上的 [開啟新工作階段 ] 圖示。如果在本機使用 CLI，請開啟第二個 CLI 實例。

建立和模擬裝置

在本節中，您會在第一個 CLI 工作階段中為您的 IoT 中樞建立裝置身分識別，然後使用該裝置身分識別模擬裝置。模擬裝置會回應您在第二個 CLI 工作階段中排程的工作。

若要建立並啟動模擬裝置：

在第一個 CLI 工作階段中，執行 az iot hub device-identity create 命令，以對應的值取代下列佔位符。此命令會建立模擬裝置的裝置身分識別。

{DeviceName}。模擬裝置的名稱。

{HubName}。 IoT 中樞的名稱。
```
az iot hub device-identity create --device-id {DeviceName} --hub-name {HubName} 
```
在第一個 CLI 工作階段中，執行 az iot device simulate 命令，以對應的值取代下列佔位元。此命令會模擬您在上一個步驟中建立的裝置。此命令也會設定模擬裝置在初始化時，將其連線通道報告為裝置對應裝置對應裝置對應項上的報告屬性。

{DeviceName}。模擬裝置的名稱。

{HubName}。 IoT 中樞的名稱。
```
az iot device simulate --device-id {DeviceName} --hub-name {HubName} \
                       --init-reported-properties '{"connectivity":{"type": "cellular"}}'
```
提示

根據預設， az iot device simulate 命令會在訊息之間傳送 100 個裝置到雲端訊息，間隔為 3 秒。模擬會在傳送所有訊息之後結束。如果您想要讓模擬執行更長的時間，您可以使用 --msg-count 參數來指定更多訊息，或 --msg-interval 參數來指定訊息之間的較長間隔。您也可以再次執行命令，以重新啟動模擬裝置。

更新裝置對應項

建立裝置身分識別之後，會在 IoT 中樞中隱含建立裝置對應項。在本節中，您會使用第二個 CLI 工作階段來更新與上一節中建立之裝置身分識別相關聯的裝置對應項上的一組標籤。您可以使用裝置對應項標籤來組織和管理IoT解決方案中的裝置。如需使用標籤管理裝置的詳細資訊，請參閱如何在 Azure IoT 中樞中使用裝置對應項標籤來管理裝置。

確認第一個 CLI 工作階段中的模擬裝置正在執行。如果沒有，請從建立並模擬裝置，再次執行 az iot device simulate 命令來重新啟動它。
在第二個 CLI 工作階段中，執行 az iot hub device-twin update 命令，以對應的值取代下列佔位符。在此範例中，我們會針對我們在上一節中建立的裝置身分識別，更新裝置對應項上的多個標籤。

{DeviceName}。裝置的名稱。

{HubName}。 IoT 中樞的名稱。
```
az iot hub device-twin update --device-id {DeviceName} --hub-name {HubName} \
                              --tags '{"location":{"region":"US","plant":"Redmond43"}}'
```

在第二個 CLI 工作階段中，確認 JSON 回應顯示更新作業的結果。在下列 JSON 回應範例中，我們用於 SampleDevice{DeviceName} CLI 命令中的 az iot hub device-twin update 佔位元。

{
  "authenticationType": "sas",
  "capabilities": {
    "iotEdge": false
  },
  "cloudToDeviceMessageCount": 0,
  "connectionState": "Connected",
  "deviceEtag": "MTA2NTU1MDM2Mw==",
  "deviceId": "SampleDevice",
  "deviceScope": null,
  "etag": "AAAAAAAAAAI=",
  "lastActivityTime": "0001-01-01T00:00:00+00:00",
  "modelId": "",
  "moduleId": null,
  "parentScopes": null,
  "properties": {
    "desired": {
      "$metadata": {
        "$lastUpdated": "2023-02-21T10:40:10.5062402Z"
      },
      "$version": 1
    },
    "reported": {
      "$metadata": {
        "$lastUpdated": "2023-02-21T10:40:43.8539917Z",
        "connectivity": {
          "$lastUpdated": "2023-02-21T10:40:43.8539917Z",
          "type": {
            "$lastUpdated": "2023-02-21T10:40:43.8539917Z"
          }
        }
      },
      "$version": 2,
      "connectivity": {
        "type": "cellular"
      }
    }
  },
  "status": "enabled",
  "statusReason": null,
  "statusUpdateTime": "0001-01-01T00:00:00+00:00",
  "tags": {
    "location": {
      "plant": "Redmond43",
      "region": "US"
    }
  },
  "version": 4,
  "x509Thumbprint": {
    "primaryThumbprint": null,
    "secondaryThumbprint": null
  }
}

查詢IoT中樞是否有裝置對應項

IoT 中樞會將IoT中樞的裝置對應項公開為稱為裝置的檔集合。在本節中，您會使用第二個 CLI 工作階段，在 IoT 中樞的裝置對應項集上執行兩個查詢：第一個查詢只會選取位於 Redmond43 工廠的裝置裝置對應項，第二個查詢會精簡查詢，只選取也透過行動數據網路連線的裝置。這兩個查詢只會傳回結果集中的前100個裝置。如需裝置對應項查詢的詳細資訊，請參閱 IoT 中樞裝置和模組對應項的查詢。

確認第一個 CLI 工作階段中的模擬裝置正在執行。如果沒有，請從建立並模擬裝置，再次執行 az iot device simulate 命令來重新啟動它。
在第二個 CLI 工作階段中，執行 az iot hub query 命令，以對應的值取代下列佔位元。在此範例中，我們會篩選查詢，只傳回位於 Redmond43 工廠之裝置的裝置對應項。

{HubName}。 IoT 中樞的名稱。
```
az iot hub query --hub-name {HubName} \
                 --query-command "SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'" \
                 --top 100
```

在第二個 CLI 工作階段中，確認 JSON 回應會顯示查詢的結果。

{
  "authenticationType": "sas",
  "capabilities": {
    "iotEdge": false
  },
  "cloudToDeviceMessageCount": 0,
  "connectionState": "Connected",
  "deviceEtag": "MTA2NTU1MDM2Mw==",
  "deviceId": "SampleDevice",
  "deviceScope": null,
  "etag": "AAAAAAAAAAI=",
  "lastActivityTime": "0001-01-01T00:00:00+00:00",
  "modelId": "",
  "moduleId": null,
  "parentScopes": null,
  "properties": {
    "desired": {
      "$metadata": {
        "$lastUpdated": "2023-02-21T10:40:10.5062402Z"
      },
      "$version": 1
    },
    "reported": {
      "$metadata": {
        "$lastUpdated": "2023-02-21T10:40:43.8539917Z",
        "connectivity": {
          "$lastUpdated": "2023-02-21T10:40:43.8539917Z",
          "type": {
            "$lastUpdated": "2023-02-21T10:40:43.8539917Z"
          }
        }
      },
      "$version": 2,
      "connectivity": {
        "type": "cellular"
      }
    }
  },
  "status": "enabled",
  "statusReason": null,
  "statusUpdateTime": "0001-01-01T00:00:00+00:00",
  "tags": {
    "location": {
      "plant": "Redmond43",
      "region": "US"
    }
  },
  "version": 4,
  "x509Thumbprint": {
    "primaryThumbprint": null,
    "secondaryThumbprint": null
  }
}

在第二個 CLI 工作階段中，執行 az iot hub query 命令，以對應的值取代下列佔位元。在此範例中，我們會篩選查詢，只傳回位於 Redmond43 工廠的裝置對應項，這些裝置也會透過行動數據網路連線。

{HubName}。 IoT 中樞的名稱。
```
az iot hub query --hub-name {HubName} \
                 --query-command "SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' \
                                  AND properties.reported.connectivity.type = 'cellular'" \
                 --top 100
```
在第二個 CLI 工作階段中，確認 JSON 回應會顯示查詢的結果。此查詢的結果應該符合本節中上一個查詢的結果。

在本文章中，您將：

從 Azure CLI 工作階段新增裝置元資料作為標籤
模擬裝置對應項中回報裝置連線資訊的裝置
在 Azure CLI 工作階段中使用類似 SQL 的 IoT 中樞查詢語言來查詢裝置對應項資訊

下一步

若要了解如何：

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

Share via

開始使用裝置對應項目（Azure CLI）

必要條件

準備 Cloud Shell

準備兩個 CLI 工作階段

建立和模擬裝置

更新裝置對應項

查詢IoT中樞是否有裝置對應項

下一步

其他資源

Share via

開始使用裝置對應項目 （Azure CLI）

必要條件

準備 Cloud Shell

準備兩個 CLI 工作階段

建立和模擬裝置

更新裝置對應項

查詢IoT中樞是否有裝置對應項

下一步

其他資源

開始使用裝置對應項目（Azure CLI）