Devices - Replace Twin

Service:

IoT Hub

API Version:

2021-04-12

Replaces the tags and desired properties of a device twin. See https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-device-twins for more information.

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

URI Parameters

Name	In	Required	Type	Description
id	path	True	string	The unique identifier of the device.
api-version	query	True	string	Version of the Api.

Request Header

Name	Required	Type	Description
If-Match		string	The string representing a weak ETag for the device twin, as per RFC7232. It determines if the replace operation should be carried out.

Request Body

Name	Type	Description
authenticationType	enum: sas selfSigned certificateAuthority none	The authentication type used by the device.
capabilities	DeviceCapabilities	The status of capabilities enabled on the device.
cloudToDeviceMessageCount	integer	The number of cloud-to-device messages sent.
connectionState	enum: Disconnected Connected	The connection state of the device.
deviceEtag	string	The string representing a ETag for the device, as per RFC7232.
deviceId	string	The unique identifier of the device in the identity registry of the IoT Hub. It is a case-sensitive string (up to 128 char long) of ASCII 7-bit alphanumeric chars, and the following special characters {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}.
deviceScope	string	The scope of the device.
etag	string	The string representing a ETag for the device twin, as per RFC7232.
lastActivityTime	string	The date and time when the device last connected or received or sent a message. The date and time is sepecified in ISO8601 datetime format in UTC, for example, 2015-01-28T16:24:48.789Z. This value is not updated if the device uses the HTTP/1 protocol to perform messaging operations.
moduleId	string	The unique identifier of the module in the identity registry of the IoT Hub. It is a case-sensitive string (up to 128 char long) of ASCII 7-bit alphanumeric chars, and the following special characters {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}.
parentScopes	string[]	The scopes of the upper level edge devices if applicable. Only available for edge devices.
properties	TwinProperties	The desired and reported properties of the twin.
status	enum: enabled disabled	The enabled status of the device. If disabled, the device cannot connect to the service.
statusReason	string	The reason for the current status of the device, if any.
statusUpdateTime	string	The date and time when the status of the device was last updated.
tags	object	The collection of key-value pairs read and written by the solution back end. They are not visible to device apps. They keys are UTF-8 encoded, case-sensitive and up-to 1KB in length. Allowed characters exclude UNICODE control characters (segments C0 and C1), '.', '$' and space. The values are JSON objects, up-to 4KB in length.
version	integer	The version for the device twin including tags and desired properties
x509Thumbprint	X509Thumbprint	The X509 thumbprint of the device.

Responses

Name	Type	Description
200 OK	Twin	OK.

Definitions

Name	Description
DeviceCapabilities	The status of capabilities enabled on the device.
Twin	The state information for a device or module. This is implicitly created and deleted when the corresponding device/ module identity is created or deleted in the IoT Hub.
TwinProperties	The desired and reported properties of the twin. The maximum depth of the object is 10.
X509Thumbprint

DeviceCapabilities

The status of capabilities enabled on the device.

Name	Type	Description
iotEdge	boolean	The property that determines if the device is an edge device or not.

Twin

The state information for a device or module. This is implicitly created and deleted when the corresponding device/ module identity is created or deleted in the IoT Hub.

Name	Type	Description
authenticationType	enum: certificateAuthority none sas selfSigned	The authentication type used by the device.
capabilities	DeviceCapabilities	The status of capabilities enabled on the device.
cloudToDeviceMessageCount	integer	The number of cloud-to-device messages sent.
connectionState	enum: Connected Disconnected	The connection state of the device.
deviceEtag	string	The string representing a ETag for the device, as per RFC7232.
deviceId	string	The unique identifier of the device in the identity registry of the IoT Hub. It is a case-sensitive string (up to 128 char long) of ASCII 7-bit alphanumeric chars, and the following special characters {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}.
deviceScope	string	The scope of the device.
etag	string	The string representing a ETag for the device twin, as per RFC7232.
lastActivityTime	string	The date and time when the device last connected or received or sent a message. The date and time is sepecified in ISO8601 datetime format in UTC, for example, 2015-01-28T16:24:48.789Z. This value is not updated if the device uses the HTTP/1 protocol to perform messaging operations.
moduleId	string	The unique identifier of the module in the identity registry of the IoT Hub. It is a case-sensitive string (up to 128 char long) of ASCII 7-bit alphanumeric chars, and the following special characters {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}.
parentScopes	string[]	The scopes of the upper level edge devices if applicable. Only available for edge devices.
properties	TwinProperties	The desired and reported properties of the twin.
status	enum: disabled enabled	The enabled status of the device. If disabled, the device cannot connect to the service.
statusReason	string	The reason for the current status of the device, if any.
statusUpdateTime	string	The date and time when the status of the device was last updated.
tags	object	The collection of key-value pairs read and written by the solution back end. They are not visible to device apps. They keys are UTF-8 encoded, case-sensitive and up-to 1KB in length. Allowed characters exclude UNICODE control characters (segments C0 and C1), '.', '$' and space. The values are JSON objects, up-to 4KB in length.
version	integer	The version for the device twin including tags and desired properties
x509Thumbprint	X509Thumbprint	The X509 thumbprint of the device.

TwinProperties

The desired and reported properties of the twin. The maximum depth of the object is 10.

Name	Type	Description
desired	object	The collection of desired property key-value pairs. The keys are UTF-8 encoded, case-sensitive and up-to 1KB in length. Allowed characters exclude UNICODE control characters (segments C0 and C1), '.', '$' and space. The desired porperty values are JSON objects, up-to 4KB in length.
reported	object	The collection of reported property key-value pairs. The keys are UTF-8 encoded, case-sensitive and up-to 1KB in length. Allowed characters exclude UNICODE control characters (segments C0 and C1), '.', '$' and space. The reported property values are JSON objects, up-to 4KB in length.

X509Thumbprint

Name	Type	Description
primaryThumbprint	string	The X509 client certificate primary thumbprint.
secondaryThumbprint	string	The X509 client certificate secondary thumbprint.