了解 IoT 隨插即用數位分身

IoT 隨插即用裝置實作由數位對應項定義語言 (DTDL) 結構描述的模型。 該模型會描述特定裝置可擁有的元件、屬性、命令和遙測訊息集。

Azure IoT 服務 SDK 包括 API，可讓服務與裝置的數位對應項互動。 例如，服務可透過數位對應項讀取裝置屬性，或透過數位對應項呼叫裝置上的命令。 若要深入了解，請參閱 IoT 中樞數位對應項範例。

本文的 IoT 隨插即用裝置範例實作具有控溫器 元件的溫度控制器模型。

裝置對應項和數位對應項

除了數位對應項，Azure IoT 中樞也為每個連線的裝置維護裝置對應項。 裝置對應項類似數位對應項，都代表裝置的屬性。 IoT 中樞會在 IoT 隨插即用裝置首次佈建時初始化數位對應項和裝置對應項。 Azure IoT 服務 SDK 包括 API，可與裝置對應項互動。

裝置對應項是存放裝置狀態資訊的 JSON 文件，包括中繼資料、設定和條件。 若要深入了解，請參閱 IoT 中樞服務用戶端範例。 裝置和解決方案建置者可用相同的裝置對應項 API 和 SDK 集，實作使用 IoT 隨插即用慣例的裝置和解決方案。 在裝置對應項中，可寫入屬性的狀態分割為「所需屬性」和「報告屬性」區段。 所有唯讀屬性都可於報告屬性區段內存取。

數位對應項 API 可在高階 DTDL 建構中運作，例如元件、屬性和命令，方便解決方案建置者建立 IoT 隨插即用解決方案。 使用者可在數位對應項中統一檢視屬性的現有和所需狀態。 特定屬性的同步狀態則儲存在對應的預設元件 $metadata 區段。

裝置對應項 JSON 範例

下列程式碼片段顯示格式化為 JSON 物件的 IoT 隨插即用裝置對應項：

{
  "deviceId": "sample-device",
  "modelId": "dtmi:com:example:TemperatureController;1",
  "version": 15,
  "properties": {
    "desired": {
      "thermostat1": {
        "__t": "c",
        "targetTemperature": 21.8
      },
      "$metadata": {...},
      "$version": 4
    },
    "reported": {
      "serialNumber": "alwinexlepaho8329",
      "thermostat1": {
        "maxTempSinceLastReboot": 25.3,
        "__t": "c",
        "targetTemperature": {
          "value": 21.8,
          "ac": 200,
          "ad": "Successfully executed patch",
        }
      },
      "$metadata": {...},
      "$version": 11
    }
  }
}

數位對應項範例

下列程式碼片段顯示格式化為 JSON 物件的數位對應項：

{
  "$dtId": "sample-device",
  "serialNumber": "alwinexlepaho8329",
  "thermostat1": {
    "maxTempSinceLastReboot": 25.3,
    "targetTemperature": 21.8,
    "$metadata": {
      "targetTemperature": {
        "desiredValue": 21.8,
        "desiredVersion": 4,
        "ackVersion": 4,
        "ackCode": 200,
        "ackDescription": "Successfully executed patch",
        "lastUpdateTime": "2020-07-17T06:11:04.9309159Z"
      },
      "maxTempSinceLastReboot": {
         "lastUpdateTime": "2020-07-17T06:10:31.9609233Z"
      }
    }
  },
  "$metadata": {
    "$model": "dtmi:com:example:TemperatureController;1",
    "serialNumber": {
      "lastUpdateTime": "2020-07-17T06:10:31.9609233Z"
    }
  }
}

下表描述數位對應項 JSON 物件中的欄位：

屬性

屬性是可代表實體狀態的資料欄位，就如許多物件導向程式設計語言的屬性。

唯讀屬性

DTDL 結構描述：

{
    "@type": "Property",
    "name": "serialNumber",
    "displayName": "Serial Number",
    "description": "Serial number of the device.",
    "schema": "string"
}

在此範例中，alwinexlepaho8329 是裝置所回報 serialNumber 唯讀屬性目前的值。

下列程式碼片段顯示 serialNumber 屬性的並存 JSON 表示法：

"properties": {
"reported": {
"serialNumber": "alwinexlepaho8329"
}
}

"serialNumber": "alwinexlepaho8329"

可寫入的屬性

下列範例顯示預設元件中的可寫入屬性。

DTDL：

{
  "@type": "Property",
  "name": "fanSpeed",
  "displayName": "Fan Speed",
  "writable": true,
  "schema": "double"
}

{
"properties": {
"desired": {
"fanSpeed": 2.0,
},
"reported": {
"fanSpeed": {
"value": 3.0,
"ac": 200,
"av": 1,
"ad": "Successfully executed patch version 1"
}
}
},
}

{
"fanSpeed": 3.0,
"$metadata": {
"fanSpeed": {
"desiredValue": 2.0,
"desiredVersion": 2,
"ackVersion": 1,
"ackCode": 200,
"ackDescription": "Successfully executed patch version 1",
"lastUpdateTime": "2020-07-17T06:10:31.9609233Z"
}
}
}

在此範例中，3.0 是裝置所回報 fanSpeed 屬性目前的值。 2.0 是解決方案設定的所需值。 根層級屬性的所需值和同步處理狀態，設定在數位對應項的根層級 $metadata 中。 裝置上線後，即可套用此更新並回報更新的值。

元件

元件可讓您建立模型介面作為其他介面的組件。 例如，控溫器介面可在溫度控制器模型中整合為元件 thermostat1 和 thermostat2。

在裝置對應項中，元件由 { "__t": "c"} 標記所識別。 在數位對應項中，$metadata 即代表元件。

在此範例中，thermostat1 是擁有兩個屬性的元件：

• maxTempSinceLastReboot 是唯讀屬性。
• targetTemperature 是由裝置成功同步的可寫入屬性。 這些屬性的所需值和同步狀態都在元件的 $metadata 中。

下列程式碼片段顯示 thermostat1 元件的並存 JSON 表示法：

"properties": {
"desired": {
"thermostat1": {
"__t": "c",
"targetTemperature": 21.8
},
"$metadata": {
},
"$version": 4
},
"reported": {
"thermostat1": {
"maxTempSinceLastReboot": 25.3,
"__t": "c",
"targetTemperature": {
"value": 21.8,
"ac": 200,
"ad": "Successfully executed patch",
"av": 4
}
},
"$metadata": {
},
"$version": 11
}
}

"thermostat1": {
"maxTempSinceLastReboot": 25.3,
"targetTemperature": 21.8,
"$metadata": {
"targetTemperature": {
"desiredValue": 21.8,
"desiredVersion": 4,
"ackVersion": 4,
"ackCode": 200,
"ackDescription": "Successfully executed patch",
"lastUpdateTime": "2020-07-17T06:11:04.9309159Z"
},
"maxTempSinceLastReboot": {
"lastUpdateTime": "2020-07-17T06:10:31.9609233Z"
}
}
}

數位對應項 API

數位對應項 API 包括取得數位對應項、更新數位對應項、叫用元件以及叫用命令作業，有助管理數位對應項。 您可以直接或透過其中一個服務 SDK 來使用 REST API。

數位分身變更事件

當數位分身變更事件啟用時，每當元件或屬性的目前值或所需值變更時，就會觸發事件。 數位對應項變更事件會以 JSON 修補檔 格式產生。 如果啟用對應項變更事件，則對應的事件會以裝置對應項格式產生。

若要了解如何為裝置和數位對應項事件啟用路由，請參閱使用 IoT 中樞訊息路由，將裝置到雲端的訊息傳送至不同端點。 若要了解訊息格式，請參閱建立和讀取 IoT 中樞訊息。

例如，當解決方案設定 targetTemperature 時，會觸發以下數位對應項變更事件：

iothub-connection-device-id:sample-device
iothub-enqueuedtime:7/17/2020 6:11:04 AM
iothub-message-source:digitalTwinChangeEvents
correlation-id:275d463fa034
content-type:application/json-patch+json
content-encoding:utf-8
[
  {
    "op": "add",
    "path": "/thermostat1/$metadata/targetTemperature",
    "value": {
      "desiredValue": 21.8,
      "desiredVersion": 4
    }
  }
]

當裝置報告已套用上述所需變更時，就會觸發下列數位對應項變更事件：

iothub-connection-device-id:sample-device
iothub-enqueuedtime:7/17/2020 6:11:05 AM
iothub-message-source:digitalTwinChangeEvents
correlation-id:275d464a2c80
content-type:application/json-patch+json
content-encoding:utf-8
[
  {
    "op": "add",
    "path": "/thermostat1/$metadata/targetTemperature/ackCode",
    "value": 200
  },
  {
    "op": "add",
    "path": "/thermostat1/$metadata/targetTemperature/ackDescription",
    "value": "Successfully executed patch"
  },
  {
    "op": "add",
    "path": "/thermostat1/$metadata/targetTemperature/ackVersion",
    "value": 4
  },
  {
    "op": "add",
    "path": "/thermostat1/$metadata/targetTemperature/lastUpdateTime",
    "value": "2020-07-17T06:11:04.9309159Z"
  },
  {
    "op": "add",
    "path": "/thermostat1/targetTemperature",
    "value": 21.8
  }
]

下一步

現在您了解數位對應項了，以下有一些額外的資源可供參考：

• 如何使用 IoT 隨插即用數位對應項 API
• 從您的解決方案與裝置互動
• IoT 數位對應項 REST API
• Azure IoT 總管