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

發行項
08/25/2023

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

注意

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

本文說明如何建立 Azure CLI 會話，在其中：

建立裝置身分識別，然後為該裝置建立模組身分識別。
更新與模組身分識別相關聯之模組對應項的一組所需屬性。

必要條件

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

模組驗證

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

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

準備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 實例中執行會話。

如果您使用 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 Shell。擴充功能會將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 會話中建立 IoT 中樞的裝置身分識別，然後使用該裝置身分識別建立模組身分識別。您可以在每個裝置身分識別下建立最多 50 個模組身分識別。

若要建立裝置身分識別和模組身分識別：

在 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 hub module-identity create 命令，並將下列預留位置取代為其對應的值。此命令會在您在上一個步驟中建立的裝置身分識別下，為您的模組建立模組身分識別。

{DeviceName}。裝置的名稱。

{HubName}。您 IoT 中樞的名稱。

{ModuleName}。裝置模組的名稱。
```
az iot hub module-identity create --device-id {DeviceName} --hub-name {HubName} \
                                  --module-id {ModuleName}
```

更新模組對應項

一旦建立模組身分識別，模組對應項會隱含地建立於 IoT 中樞中。在本節中，您會使用 CLI 會話，在與上一節中建立之模組身分識別相關聯的模組對應項上更新一組所需的屬性。

在 CLI 會話中，執行 az iot hub module-twin update 命令，並將下列預留位置取代為其對應的值。在此範例中，我們會針對我們在上一節中建立的模組身分識別，更新模組對應項上的多個所需屬性。

{DeviceName}。裝置的名稱。

{HubName}。您 IoT 中樞的名稱。

{ModuleName}。裝置模組的名稱。
```
az iot hub module-twin update --device-id {DeviceName} --hub-name {HubName} \
                              --module-id {ModuleName} \
                              --desired '{"conditions":{"temperature":{"warning":75, "critical":100}}}'
```

在 CLI 會話中，確認 JSON 回應顯示更新作業的結果。在下列 JSON 回應範例中，我們在 CLI 命令中分別針對和預留位置使用 SampleDevice 和 SampleModule{ModuleName} 。 {DeviceName}az iot hub module-twin update

{
  "authenticationType": "sas",
  "capabilities": null,
  "cloudToDeviceMessageCount": 0,
  "connectionState": "Disconnected",
  "deviceEtag": "Mzg0OEN1NzW=",
  "deviceId": "SampleDevice",
  "deviceScope": null,
  "etag": "AAAAAAAAAAI=",
  "lastActivityTime": "0001-01-01T00:00:00+00:00",
  "modelId": "",
  "moduleId": "SampleModule",
  "parentScopes": null,
  "properties": {
    "desired": {
      "$metadata": {
        "$lastUpdated": "2023-02-17T21:26:10.5835633Z",
        "$lastUpdatedVersion": 2,
        "conditions": {
          "$lastUpdated": "2023-02-17T21:26:10.5835633Z",
          "$lastUpdatedVersion": 2,
          "temperature": {
            "$lastUpdated": "2023-02-17T21:26:10.5835633Z",
            "$lastUpdatedVersion": 2,
            "critical": {
              "$lastUpdated": "2023-02-17T21:26:10.5835633Z",
              "$lastUpdatedVersion": 2
            },
            "warning": {
              "$lastUpdated": "2023-02-17T21:26:10.5835633Z",
              "$lastUpdatedVersion": 2
            }
          }
        }
      },
      "$version": 2,
      "conditions": {
        "temperature": {
          "critical": 100,
          "warning": 75
        }
      }
    },
    "reported": {
      "$metadata": {
        "$lastUpdated": "0001-01-01T00:00:00Z"
      },
      "$version": 1
    }
  },
  "status": "enabled",
  "statusReason": null,
  "statusUpdateTime": "0001-01-01T00:00:00+00:00",
  "tags": null,
  "version": 3,
  "x509Thumbprint": {
    "primaryThumbprint": null,
    "secondaryThumbprint": null
  }
}

後續步驟

若要瞭解如何使用 Azure CLI 擴充 IoT 解決方案，並排程裝置上的更新，請參閱排程和廣播作業。

若要繼續開始使用IoT 中樞和裝置管理模式，例如端對端映射式更新，請參閱使用 Raspberry Pi 3 B+ 參考映射的裝置更新一文，以取得Azure IoT 中樞的裝置更新。