SetDeviceDesiredProperty - IoT Platform - Centro de documentación de Alibaba Cloud

Establece los valores deseados para varias propiedades del dispositivo en una sola llamada.

Notas de uso

No es posible consultar los valores deseados de propiedades de solo lectura.
Puede especificar hasta 10 valores de propiedad deseados por llamada.
Tras crear un dispositivo, el valor del parámetro Version es 0. Si desea configurar el parámetro Version la primera vez que establece un valor de propiedad deseado, asigne al parámetro Version el valor 0.

Importante

Si los datos del Thing Specification Language (TSL) son de tipo float o double, los valores de parámetro correspondientes deben incluir como mínimo un decimal. Ejemplos: 10.0 y 11.1.

Límites de QPS

Cada cuenta de Alibaba Cloud admite hasta 50 consultas por segundo (QPS).

Nota

Los usuarios RAM de una cuenta de Alibaba Cloud comparten la cuota de dicha cuenta.

Depuración

OpenAPI Explorer calcula automáticamente el valor de la firma. Para mayor comodidad, se recomienda ejecutar esta operación desde OpenAPI Explorer. Esta herramienta genera dinámicamente código de ejemplo para distintos SDK.

Parámetros de solicitud

Parámetro	Tipo	Obligatorio	Ejemplo	Descripción
Action	String	Sí	SetDeviceDesiredProperty	La operación que se va a ejecutar. Establezca el valor en SetDeviceDesiredProperty.
Items	String	Sí	{"Temperature":35}	El valor de propiedad que desea especificar. El valor de este parámetro es una cadena JSON con formato: Key:Value. Ejemplo: {"Temperature":35}. Puede definir hasta 10 valores de propiedad deseados. Key indica el identificador de la propiedad. Consulte el identificador en la pestaña Define Feature de la página de detalles del producto en la consola de IoT Platform. También puede ejecutar la operación QueryThingModel y revisar el identificador en los datos TSL devueltos. Si la propiedad de temperatura pertenece a un módulo personalizado llamado testFb, establezca este parámetro como {"testFb:temperature":35}. Nota La propiedad especificada debe permitir acceso de lectura y escritura. Si define una propiedad de solo lectura, la configuración fallará. El identificador de la propiedad debe ser único. Value indica el valor deseado de la propiedad. Este debe coincidir con el tipo de dato y el rango de valores definidos para dicha propiedad. Nota Si establece Value en null, se borrará el valor deseado de la propiedad.
Versions	String	Sí	{"Temperature":2}	El número de versión del valor de propiedad deseado. El valor de este parámetro es una cadena JSON con formato Key:Value. Ejemplo: {"Temperature":2}. Key indica el identificador de la propiedad. Consulte este identificador en la pestaña Define Feature de la página de detalles del producto en la consola de IoT Platform. Nota El identificador de la propiedad debe ser único. Value indica el número de versión del valor de propiedad deseado. La primera vez que especifique un valor de propiedad deseado, establezca el parámetro Value en 0. Tras definir el valor, la versión cambiará a 1. Cada vez que actualice el valor deseado, IoT Platform incrementará automáticamente la versión en 1. En la segunda actualización, la versión será 2. Cuando vaya a realizar un tercer cambio, configure la versión en 2; tras aplicar el nuevo valor, la versión pasará a 3. Nota Si el número de versión especificado no coincide con la versión actual, el servidor rechazará la solicitud. Si desconoce la versión actual, no es necesario indicarla, pero debe proporcionar un objeto JSON válido {}.
IotInstanceId	String	No	iot_instc_pu***_c-v64********	El ID de la instancia. Consulte el ID en la página Overview de la consola de IoT Platform. Importante Si su instancia tiene un ID asignado, debe especificarlo en este parámetro; de lo contrario, la llamada fallará. Si su instancia no cuenta con una página Overview ni un ID generado, omita la configuración de este parámetro. Para más información, consulte Descripción general.
IotId	String	No	Q7uOhVRdZRRlDnTLv****00100	El ID del dispositivo. Es un identificador único que IoT Platform asigna al dispositivo. Importante El parámetro IotId funciona como un identificador globalmente único (GUID) para el dispositivo. Su valor equivale a la combinación de los parámetros IotId, ProductKey y DeviceName. Si proporciona este parámetro, no necesitará indicar ProductKey ni DeviceName. En caso de especificar simultáneamente IotId, ProductKey y DeviceName, prevalecerá el valor de IotId.
DeviceName	String	No	light	El nombre del dispositivo. Importante Si especifica un valor para este parámetro, también debe proporcionar el valor del parámetro ProductKey.
ProductKey	String	No	a1BwAGV****	La ProductKey del producto al que pertenece el dispositivo. Importante Si configura este parámetro, también debe especificar un valor para el parámetro DeviceName.

Además de los parámetros específicos mencionados anteriormente, debe configurar los parámetros comunes de solicitud al ejecutar esta operación. Para obtener más detalles sobre estos parámetros, consulte Parámetros comunes.

Parámetros de respuesta

Parámetro	Tipo	Ejemplo	Descripción
Code	String	iot.system.SystemException	El código de error devuelto cuando la llamada falla. Para más información, consulte Códigos de error.
Data	Struct		Los datos devueltos cuando la llamada es exitosa. Consulte los siguientes parámetros para más detalles.
MessageId	String	300511751	El ID del mensaje que IoT Platform envía al dispositivo para establecer los valores de propiedad deseados.
Versions	String	{\"Temperature\":2}	Los números de versión actuales de los valores de propiedad deseados.
ErrorMessage	String	A system exception occurred.	El mensaje de error devuelto cuando la llamada falla.
RequestId	String	E55E50B7-40EE-4B6B-8BBE-D3ED55CCF565	El ID de la solicitud.
Success	Boolean	true	Indica si la llamada fue exitosa. Valores válidos: true: La llamada fue exitosa. false: La llamada falló.

Ejemplos

Solicitudes de ejemplo

https://iot.cn-shanghai.aliyuncs.com/?Action=SetDeviceDesiredProperty
&ProductKey=a1BwAGV****
&DeviceName=device1
&Items=%7B%22LightAdjustLevel%22%3A1%7D
&Versions=%7B%22LightAdjustLevel%22%3A10%7D
&<Common request parameters>

Respuestas exitosas de ejemplo

Formato XML

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

Formato JSON

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

Códigos de error

Para obtener una lista de códigos de error, consulte Códigos de error del servicio.