SetDeviceDesiredProperty - IoT Platform

使用說明

唯讀屬性不支援設定期望屬性值。
一次調用最多可設定10個期望屬性值。
裝置建立後，期望屬性值的版本（Version）為0。首次設定期望屬性值時，如果指定Version參數，則需指定Version值為0。

重要物模型功能定義資料類型為float或double時，對應參數值（即使值為整數）至少攜帶一位小數位。例如10.0、11.1。

QPS限制

單個阿里雲帳號調用該介面的每秒請求數（QPS）最大限制為50。

說明 RAM使用者共用阿里雲帳號配額。

調試

您可以在OpenAPI Explorer中直接運行該介面，免去您計算簽名的困擾。運行成功後，OpenAPI Explorer可以自動產生SDK程式碼範例。

請求參數

名稱	類型	是否必選	樣本值	描述
Action	String	是	SetDeviceDesiredProperty	系統規定參數。取值：SetDeviceDesiredProperty。
Items	String	是	{"Temperature":35}	要設定的期望屬性值，組成為屬性的Key:Value，資料格式為JSON String，例如{"Temperature":35}。最多可輸入10個期望屬性值。 Key取值為屬性的標識符（identifier）。可在控制台中，裝置所屬產品的功能定義中查看；或調用QueryThingModel，從返回的物模型資料中查看。如果是自訂（非預設）模組testFb下屬性temperature，則參數值為{"testFb:temperature":35}。說明指定屬性必須是讀寫型。如果您指定了一個唯讀型的屬性，設定將會失敗。並且，一次調用中，不能傳入重複的屬性標識符。 Value取值為要設定的期望屬性值。取值需符合您為該屬性定義的資料類型和取值範圍。說明若屬性值設定為null，則表示清空期望屬性值。
Versions	String	是	{"Temperature":2}	當前期望屬性值版本，組成為Key:Value，資料格式為JSON String，例如{"Temperature":2}。 Key取值為屬性的標識符（identifier）。可在控制台中，裝置所屬產品的功能定義中查看屬性的identifier。說明一次調用中，key的取值（即屬性的identifier）不能重複。 Value取值為當前期望屬性值的版本號碼。首次設定期望屬性值時，指定該參數值為0。首次設定期望屬性值後，期望值版本號碼為1。以後每次設定期望值後，物聯網平台自動將期望值版本加1（即第二次設定期望屬性值時，指定該參數值為1。設定成功後，版本號碼自動變為2；第三次設定時，指定該參數值為2。設定成功後，版本號碼自動變為3；以此類推）。說明如果傳入的版本號碼與目前的版本不符，伺服器將拒絕此次請求。若您不確定當前期望值的版本號碼，可以不傳入版本號碼，但仍需傳入有效JSON，即傳入{}。
IotInstanceId	String	否	iot_instc_pu***_c-v64********	執行個體ID。您可在物聯網平台控制台的執行個體概覽頁面，查看當前執行個體的ID。重要若有ID值，必須傳入該ID值，否則調用會失敗。若無執行個體概覽頁面或ID值，則無需傳入。執行個體的更多資訊，請參見執行個體概述。
IotId	String	否	Q7uOhVRdZRRlDnTLv****00100	要設定期望屬性值的裝置ID。物聯網平台為該裝置頒發的ID，裝置的唯一識別碼。重要 IotId作為裝置唯一識別碼，和ProductKey與DeviceName組合是一一對應的關係。如果傳入該參數，則無需傳入ProductKey和DeviceName。如果您同時傳入IotId和ProductKey與DeviceName組合，則以IotId為準。
DeviceName	String	否	light	要設定期望屬性值的裝置名稱。重要如果傳入該參數，需同時傳入ProductKey。
ProductKey	String	否	a1BwAGV****	要設定期望屬性值的裝置所隸屬的產品ProductKey。重要如果傳入該參數，需同時傳入DeviceName。

調用API時，除了本文介紹的該API的特有請求參數，還需傳入公用請求參數。公用請求參數說明，請參見公用參數文檔。

返回資料

名稱	類型	樣本值	描述
Code	String	iot.system.SystemException	調用失敗時，返回的錯誤碼。更多資訊，請參見錯誤碼。
Data	Struct		調用成功時，返回的資料。詳情請參見以下參數。
MessageId	String	300511751	雲端下發給裝置的設定期望屬性值的訊息ID。
Versions	String	{\"Temperature\":2}	本次設定期望屬性值後，期望屬性值的目前的版本號。
ErrorMessage	String	系統異常	調用失敗時，返回的出錯資訊。
RequestId	String	E55E50B7-40EE-4B6B-8BBE-D3ED55CCF565	阿里雲為該請求產生的唯一識別碼。
Success	Boolean	true	是否調用成功。 true：調用成功。 false：調用失敗。

樣本

請求樣本

https://iot.cn-shanghai.aliyuncs.com/?Action=SetDeviceDesiredProperty
&ProductKey=a1BwAGV****
&DeviceName=device1
&Items=%7B%22LightAdjustLevel%22%3A1%7D
&Versions=%7B%22LightAdjustLevel%22%3A10%7D
&<公用請求參數>

正常返回樣本

XML格式

<SetDeviceDesiredPropertyResponse>
  <Data>
        <MessageId>300511751</MessageId>
        <Versions>{"LightAdjustLevel":2}</Versions>
  </Data>
  <RequestId>AADE79D2-B328-4FC6-A3E0-34BB23BCA440</RequestId>
  <Success>true</Success>
</SetDeviceDesiredPropertyResponse>

JSON格式

{
    "Data": {
        "MessageId": "300511751",
        "Versions": "{\"LightAdjustLeve\":2}"
    },
    "RequestId": "AADE79D2-B328-4FC6-A3E0-34BB23BCA440",
    "Success": true
}

錯誤碼

訪問錯誤中心查看更多錯誤碼。