共用方式為

Devices - Update Twin

  • 參考
服務:
IoT Hub
API 版本:
2021-04-12

匯報 裝置對應項的標記和所需屬性。 如需相關資訊，請參閱 https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-device-twins 。

PATCH https://fully-qualified-iothubname.azure-devices.net/twins/{id}?api-version=2021-04-12

URI 參數

名稱 位於 必要 類型 Description
id
 path True

string

裝置的唯一識別碼。
api-version
 query True

string

Api 的版本。

要求標頭

名稱 必要 類型 Description
If-Match

string

表示裝置對應項弱式 ETag 的字串，根據RFC7232。 它會判斷是否應該執行更新作業。

要求本文

名稱 類型 Description
authenticationType enum:
  • sas
  • selfSigned
  • certificateAuthority
  • none

裝置所使用的驗證類型。
capabilities

DeviceCapabilities

裝置上啟用的功能狀態。
cloudToDeviceMessageCount

integer

傳送的雲端到裝置訊息數目。
connectionState enum:
  • Disconnected
  • Connected

裝置的連線狀態。
deviceEtag

string

代表裝置 ETag 的字串，根據RFC7232。
deviceId

string

IoT 中樞 身分識別登錄中裝置的唯一標識符。 這是區分大小寫的字串， (最多 128 個字元長) ASCII 7 位英數位元字元， 和下列特殊字元 {'-'、'：'、'.'、'+'、'%'、'_'、'#'、'*'、'？'、'！'、' ('、') '、'='、'@'、';'、'$'、'''}。
deviceScope

string

裝置的範圍。
etag

string

代表裝置對應項 ETag 的字串，根據RFC7232。
lastActivityTime

string

裝置上次連線或接收或傳送訊息的日期和時間。 日期和時間是以 UTC ISO8601 datetime 格式分隔，例如 2015-01-28T16：24：48.789Z。 如果裝置使用 HTTP/1 通訊協定來執行傳訊作業，則不會更新此值。
moduleId

string

IoT 中樞 身分識別登錄中模組的唯一標識符。 這是區分大小寫的字串， (最多 128 個字元長) ASCII 7 位英數位元字元， 和下列特殊字元 {'-'、'：'、'.'、'+'、'%'、'_'、'#'、'*'、'？'、'！'、' ('、') '、'='、'@'、';'、'$'、'''}。
parentScopes

string[]

如果適用，則為上層邊緣裝置的範圍。 僅適用於邊緣裝置。
properties

TwinProperties

對應項的所需和報告屬性。
status enum:
  • enabled
  • disabled

裝置的啟用狀態。 如果停用，裝置就無法連線到服務。
statusReason

string

如果有任何狀態，則為裝置目前狀態的原因。
statusUpdateTime

string

上次更新裝置狀態的日期和時間。
tags

object

由解決方案後端讀取和寫入索引鍵/值組的集合。 裝置應用程式看不到它們。 這些金鑰的長度為 UTF-8 編碼、區分大小寫且長度上限為 1 KB。 允許的字元會排除 UNICODE 控制字元 (區段 C0 和 C1) 、'.'、'$' 和空格。 這些值是 JSON 對象，長度上限為 4 KB。
version

integer

裝置對應項的版本，包括標記和所需屬性
x509Thumbprint

X509Thumbprint

裝置的 X509 指紋。

回應

名稱 類型 Description
200 OK

Twin

正常。

定義

名稱 Description
DeviceCapabilities

裝置上啟用的功能狀態。
Twin

裝置或模組的狀態資訊。 這會在 IoT 中樞 中建立或刪除對應的裝置/模組身分識別時隱含建立和刪除。
TwinProperties

對應項的所需和報告屬性。 物件的深度上限為 10。
X509Thumbprint

DeviceCapabilities

裝置上啟用的功能狀態。

名稱 類型 Description
iotEdge

boolean

判斷裝置是否為邊緣裝置的屬性。

Twin

裝置或模組的狀態資訊。 這會在 IoT 中樞 中建立或刪除對應的裝置/模組身分識別時隱含建立和刪除。

名稱 類型 Description
authenticationType enum:
  • certificateAuthority
  • none
  • sas
  • selfSigned

裝置所使用的驗證類型。
capabilities

DeviceCapabilities

裝置上啟用的功能狀態。
cloudToDeviceMessageCount

integer

傳送的雲端到裝置訊息數目。
connectionState enum:
  • Connected
  • Disconnected

裝置的連線狀態。
deviceEtag

string

代表裝置 ETag 的字串，根據RFC7232。
deviceId

string

IoT 中樞 身分識別登錄中裝置的唯一標識符。 這是區分大小寫的字串， (最多 128 個字元長) ASCII 7 位英數位元字元， 和下列特殊字元 {'-'、'：'、'.'、'+'、'%'、'_'、'#'、'*'、'？'、'！'、' ('、') '、'='、'@'、';'、'$'、'''}。
deviceScope

string

裝置的範圍。
etag

string

代表裝置對應項 ETag 的字串，根據RFC7232。
lastActivityTime

string

裝置上次連線或接收或傳送訊息的日期和時間。 日期和時間是以 UTC ISO8601 datetime 格式分隔，例如 2015-01-28T16：24：48.789Z。 如果裝置使用 HTTP/1 通訊協定來執行傳訊作業，則不會更新此值。
moduleId

string

IoT 中樞 身分識別登錄中模組的唯一標識符。 這是區分大小寫的字串， (最多 128 個字元長) ASCII 7 位英數位元字元， 和下列特殊字元 {'-'、'：'、'.'、'+'、'%'、'_'、'#'、'*'、'？'、'！'、' ('、') '、'='、'@'、';'、'$'、'''}。
parentScopes

string[]

如果適用，則為上層邊緣裝置的範圍。 僅適用於邊緣裝置。
properties

TwinProperties

對應項的所需和報告屬性。
status enum:
  • disabled
  • enabled

裝置的啟用狀態。 如果停用，裝置就無法連線到服務。
statusReason

string

如果有任何狀態，則為裝置目前狀態的原因。
statusUpdateTime

string

上次更新裝置狀態的日期和時間。
tags

object

由解決方案後端讀取和寫入索引鍵/值組的集合。 裝置應用程式看不到它們。 這些金鑰的長度為 UTF-8 編碼、區分大小寫且長度上限為 1 KB。 允許的字元會排除 UNICODE 控制字元 (區段 C0 和 C1) 、'.'、'$' 和空格。 這些值是 JSON 對象，長度上限為 4 KB。
version

integer

裝置對應項的版本，包括標記和所需屬性
x509Thumbprint

X509Thumbprint

裝置的 X509 指紋。

TwinProperties

對應項的所需和報告屬性。 物件的深度上限為 10。

名稱 類型 Description
desired

object

所需屬性索引鍵/值組的集合。 索引鍵的長度為UTF-8編碼、區分大小寫且長度上限為1 KB。 允許的字元會排除 UNICODE 控制字元 (區段 C0 和 C1) 、'.'、'$' 和空格。 所需的 porperty 值是 JSON 對象，長度上限為 4 KB。
reported

object

報告屬性索引鍵/值組的集合。 索引鍵的長度為UTF-8編碼、區分大小寫且長度上限為1 KB。 允許的字元會排除 UNICODE 控制字元 (區段 C0 和 C1) 、'.'、'$' 和空格。 報告屬性值為 JSON 對象，長度上限為 4KB。

X509Thumbprint

名稱 類型 Description
primaryThumbprint

string

X509 用戶端憑證主要指紋。
secondaryThumbprint

string

X509 用戶端憑證次要指紋。