了解 IoT 隨插即用數位分身

發行項
05/30/2024

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

注意

DTDL 並非 IoT 隨插即用專屬。其他 IoT 服務，例如 Azure 數位對應項，即用其來代表建築和能源網路等整個環境。

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 物件中的欄位：

欄位名稱	描述
`$dtId`	使用者提供的字串，代表裝置數位對應項的識別碼。
`{propertyName}`	JSON 中屬性的值。
`$metadata.$model`	[選擇性] 模型介面的識別碼，描述此數位對應項的特性。
`$metadata.{propertyName}.desiredValue`	[僅適用於可寫入的屬性] 指定的屬性所需的值。
`$metadata.{propertyName}.desiredVersion`	[僅適用於可寫入的屬性] 所需值的版本，由 IoT 中樞維護。
`$metadata.{propertyName}.ackVersion`	[必要，僅適用於可寫入的屬性] 實作數位對應項的裝置認可的版本，必須大於或等於所需版本。
`$metadata.{propertyName}.ackCode`	[必要，僅適用於可寫入的屬性] 實作數位對應項的裝置應用程式傳回的 `ack` 程式碼。
`$metadata.{propertyName}.ackDescription`	[選擇性，僅適用於可寫入的屬性] 實作數位對應項裝置應用程式傳回的 `ack` 描述。
`$metadata.{propertyName}.lastUpdateTime`	IoT 中樞會維護裝置上次更新屬性的時間戳記。時間戳記採用 UTC 格式，並以 ISO8601 格式 YYYY-MM-DDTHH:MM:SS.mmmZ 進行編碼。
`{componentName}`	JSON 物件包含元件的屬性值和中繼資料。
`{componentName}.{propertyName}`	以 JSON 表示的元件屬性值。
`{componentName}.$metadata`	元件的中繼資料資訊。

屬性

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

唯讀屬性

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 隨插即用數位分身

裝置對應項和數位對應項

裝置對應項 JSON 範例

數位對應項範例

屬性

唯讀屬性

可寫入的屬性

元件

數位對應項 API

數位分身變更事件

下一步

意見反應

其他資源