Modules - Update Twin

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

PATCH https://fully-qualified-iothubname.azure-devices.net/twins/{id}/modules/{mid}?api-version=2020-05-31-preview

URI Parameters

Name In Required Type Description
id
path True
  • string

The unique identifier of the device.

mid
path True
  • string

The unique identifier of the module.

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 update operation should be carried out.

Request Body

Name Type Description
authenticationType enum:
  • sas
  • selfSigned
  • certificateAuthority
  • none

The authentication type used by the device.

capabilities

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 {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}.

properties

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

The X509 thumbprint of the device.

Responses

Name Type Description
200 OK

OK.

Definitions

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

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 {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}.

properties

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

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.