通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Devices - Replace Twin

  • 参考
服务:
IoT Hub
API 版本:
2021-04-12

替换设备孪生的标记和所需属性。 有关详细信息，请参阅https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-device-twins。

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

URI 参数

名称 在 必需 类型 说明
id
 path True

string

设备的唯一标识符。
api-version
 query True

string

Api 的版本。

请求头

名称 必需 类型 说明
If-Match

string

表示设备孪生的弱 ETag 的字符串，根据 RFC7232。 它确定是否应执行替换操作。

请求正文

名称 类型 说明
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日期/时间格式分隔，例如 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 编码的，区分大小写，最大长度为 1KB。 允许的字符排除 (段 C0 和 C1) 、“.”、“$”和空格的 UNICODE 控制字符。 值为 JSON 对象，长度最大为 4KB。
version

integer

设备孪生的版本，包括标记和所需属性
x509Thumbprint

X509Thumbprint

设备的 X509 指纹。

响应

名称 类型 说明
200 OK

Twin

没问题。

定义

名称 说明
DeviceCapabilities

设备上启用的功能的状态。
Twin

设备或模块的状态信息。 在IoT 中心中创建或删除相应的设备/模块标识时，会隐式创建和删除此标识。
TwinProperties

孪生体的所需属性和报告属性。 对象的最大深度为 10。
X509Thumbprint

DeviceCapabilities

设备上启用的功能的状态。

名称 类型 说明
iotEdge

boolean

确定设备是否为边缘设备的属性。

Twin

设备或模块的状态信息。 在IoT 中心中创建或删除相应的设备/模块标识时，会隐式创建和删除此标识。

名称 类型 说明
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日期/时间格式分隔，例如 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 编码的，区分大小写，最大长度为 1KB。 允许的字符排除 (段 C0 和 C1) 、“.”、“$”和空格的 UNICODE 控制字符。 值为 JSON 对象，长度最大为 4KB。
version

integer

设备孪生的版本，包括标记和所需属性
x509Thumbprint

X509Thumbprint

设备的 X509 指纹。

TwinProperties

孪生体的所需属性和报告属性。 对象的最大深度为 10。

名称 类型 说明
desired

object

所需属性键值对的集合。 密钥采用 UTF-8 编码，区分大小写，最大长度为 1KB。 允许的字符排除 (段 C0 和 C1) 、“.”、“$”和空格的 UNICODE 控制字符。 所需的 porperty 值为 JSON 对象，长度最大为 4KB。
reported

object

报告的属性键值对的集合。 密钥采用 UTF-8 编码，区分大小写，最大长度为 1KB。 允许的字符排除 (段 C0 和 C1) 、“.”、“$”和空格的 UNICODE 控制字符。 报告的属性值是 JSON 对象，长度最大为 4KB。

X509Thumbprint

名称 类型 说明
primaryThumbprint

string

X509 客户端证书主指纹。
secondaryThumbprint

string

X509 客户端证书辅助指纹。