了解 IoT 隨插即用數位分身

IoT 隨插即用 裝置會實作 Digital Twins 定義語言 (DTDL) 架構所描述的模型。 模型描述特定裝置可以擁有的一元件、屬性、命令和遙測訊息。

注意

DTDL 不專屬於 IoT 隨插即用。 其他IoT服務,例如 Azure Digital Twins,會使用它來代表整個環境,例如建築物和能源網路。

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

下列代碼段顯示 屬性的並存 JSON 表示法 serialNumber

裝置對應項

"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中。

下列代碼段顯示元件的並存 JSON 表示法 thermostat1

裝置對應項

"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
  }
]

注意

在裝置和數字對應項變更通知中開啟時,對應項變更通知訊息會加倍。

下一步

既然您已瞭解數字對應項,以下是一些更多資源: