Modifies a device shadow.

QPS limits

You can call this API operation up to 500 times per second per account.

Note The RAM users of an Alibaba Cloud account share the quota of the account.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter Type Required Example Description
Action String Yes UpdateDeviceShadow

The operation that you want to perform. Set the value to UpdateDeviceShadow.

DeviceName String Yes device1

The name of the device whose shadow information you want to modify.

ProductKey String Yes a1T27vz****

The ProductKey of the product to which the device belongs.

ShadowMessage String Yes {"method":"update","state":{"desired":{"color":"green"}},"version":2}

The information that you want to specify for the device shadow.

The information includes the following parameters:

  • method: the type of the operation. Data type: string. Set the value to update.
  • state: the status of the device shadow. Data type: string. The desired parameter specifies the expected shadow status.
  • version: the version of the device shadow. Data type: long.
    • If versioning is not required, set this parameter to 0.
    • If versioning is required, specify a version that is later than the current version.
Important If versioning is required, do not query the version of a device shadow in the IoT Platform console. If a large number of update and query operations are concurrently performed, multiple update operations may return the same version. In this case, the most recent update operation may first be completed. As a result, the current shadow information is not the latest shadow information. We recommend that you maintain the versions of device shadows on the on-premises device. When you call this operation, use an on-premises application to obtain the latest version of the device shadow.
IotInstanceId String No iot_instc_pu****_c*-v64********

The ID of the elastic container instance. You can view the ID of the instance on the Overview page in the IoT Platform console.

Important
  • If your instance has an ID, you must specify the ID for this parameter. Otherwise, the call fails.
  • If no Overview page or ID is generated for your instance, you do not need to configure this parameter.

For more information, see Overview.

DeltaUpdate Boolean No false

Specifies whether to perform an incremental update on the desired parameter. Valid values:

  • true: performs an incremental update.
  • false: performs a full update. This is the default value.

In addition to the preceding operation-specific request parameters, you must configure common request parameters when you call this operation. For more information about common request parameters, see Common parameters.

Response parameters

Parameter Type Example Description
Code String iot.system.SystemException

The error code returned if the call fails. For more information, see Error codes.

ErrorMessage String A system exception occurred.

The error message returned if the call fails.

RequestId String 6754C0E7-A35D-4CC8-A684-45EB1F0008D9

The ID of the request.

Success Boolean true

Indicates whether the call was successful. Valid values:

  • true: The call was successful.
  • false: The call failed.

Examples

Sample requests

https://iot.cn-shanghai.aliyuncs.com/?Action=UpdateDeviceShadow
&ProductKey=a1T27vz****
&DeviceName=device1
&ShadowMessage={"method":"update","state":{"desired":{"color":"green"}},"version":1}
&<Common request parameters>

Sample success responses

XML format

<UpdateDeviceShadowResponse>
        <RequestId>BB71E443-4447-4024-A000-EDE09922891E</RequestId>
        <Success>true</Success>
  </UpdateDeviceShadowResponse>

JSON format

{
	"RequestId": "6754C0E7-A35D-4CC8-A684-45EB1F0008D9",
	"Success": true
}

Error codes

For a list of error codes, see Service error codes.