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

Invoca un servicio de un dispositivo.

Notas de uso

Al definir un servicio en un modelo de Thing Specification Language (TSL), se especifica el modo de invocación. Cuando invoca un servicio mediante esta operación, IoT Platform utiliza un modo de llamada basado en el valor del parámetro Identifier.

Modo síncrono: IoT Platform envía una solicitud de llamada a procedimiento remoto revertido (RRPC) al dispositivo y este devuelve una respuesta RRPC de forma síncrona. Para obtener más información sobre cómo usar RRPC, consulte ¿Qué es RRPC?.
Modo asíncrono: IoT Platform envía una solicitud RRPC al dispositivo y este devuelve una respuesta RRPC de forma asíncrona. Para obtener más información sobre los temas, consulte Propiedades, eventos y servicios del dispositivo.

Importante

Si establece el parámetro Checksum Type en

Verification-free

al crear un producto, se utiliza el modo asíncrono.

Cuando el dispositivo recibe la llamada al servicio, devuelve una respuesta al invocador. Al configurar el dispositivo, debe especificar la lógica de respuesta y los parámetros de respuesta. Los formatos de datos de los parámetros de respuesta deben cumplir con el protocolo Alink. Ejemplo:

{
    "id": "58***89",
    "code": 200,
    "data": {},
    "message": "success",
    "localizedMsg": "localizedMsg"
}

Nota

El parámetro id especifica el identificador único de la solicitud. IoT Platform genera este ID. El dispositivo puede obtenerlo de los parámetros de la solicitud y devolverlo posteriormente.
El parámetro code especifica el resultado de la llamada al servicio. El valor del parámetro es un número entero.
El parámetro data especifica el resultado de la llamada al servicio. Este parámetro se devuelve al invocador del servicio. Puede especificar los parámetros que desea incluir en el resultado devuelto. Los datos deben estar en formato JSON.
Los parámetros message y localizedMsg son opcionales.

Link SDK for C de IoT Platform proporciona un ejemplo sobre cómo utilizar un modelo TSL. Para obtener más información, consulte Invocar servicios del dispositivo.

Límites

Si invoca un servicio de forma síncrona, el tiempo de espera es de 8 segundos. Si un servidor no recibe una respuesta dentro de los 8 segundos, se produce un error de tiempo de espera. No existe límite de tiempo de espera para las llamadas asíncronas.

Límite de QPS

Puede llamar a esta operación de API hasta 500 veces por segundo por cuenta.

Nota

Los usuarios de 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 su comodidad, le recomendamos que llame a esta operación en OpenAPI Explorer. OpenAPI Explorer genera dinámicamente el código de muestra de la operación para diferentes SDK.

Parámetros de solicitud

Parámetro	Tipo	Obligatorio	Ejemplo	Descripción
Action	String	Sí	InvokeThingService	La operación que desea ejecutar. Establezca el valor en InvokeThingService.
Args	String	Sí	{"param1":1}	El parámetro de entrada del servicio. El valor es una cadena JSON. Ejemplo: Args={"param1": 1}. Si no desea configurar un parámetro de entrada para el servicio, establezca el valor en Args={}. Importante Si los datos TSL son de tipo float o double, los valores de parámetro correspondientes a los datos TSL deben contener como mínimo un decimal. Ejemplos: 10.0 y 11.1.
Identifier	String	Sí	Set	El identificador del servicio. Para consultar el identificador del servicio, utilice uno de los siguientes métodos: Inicie sesión en la consola de IoT Platform. En la pestaña Define Feature del producto al que pertenece el dispositivo, consulte el identificador. Llame a la operación QueryThingModel y consulte el identificador en la información TSL devuelta. Nota Si un servicio llamado testService pertenece a un módulo personalizado llamado testFb, puede establecer este parámetro en testFb:testService. El módulo personalizado no es el módulo predeterminado.
IotInstanceId	String	No	iot_instc_pu***_c-v64********	El ID de la instancia de IoT. En la página Overview de la consola de IoT Platform, puede consultar el ID de la instancia. Importante Si su instancia tiene un ID, debe especificarlo en el parámetro. De lo contrario, la llamada fallará. Si no se ha generado ninguna página de Overview o ID para su instancia, no necesita configurar este parámetro. Para obtener más información, consulte Descripción general de instancias.
ProductKey	String	No	a1BwAGV****	La ProductKey del producto al que pertenece el dispositivo. Importante Si especifica un valor para este parámetro, debe configurar el parámetro DeviceName.
DeviceName	String	No	light	El DeviceName del dispositivo al que pertenece el servicio requerido. Importante Si especifica un valor para este parámetro, debe configurar el parámetro ProductKey.
IotId	String	No	Q7uOhVRdZRRlDnTLv****00100	El ID del dispositivo. Es un identificador único que IoT Platform asigna al dispositivo. Importante El parámetro IotId especifica un GUID para el dispositivo. El valor del parámetro IotId equivale a una combinación de los valores de los parámetros ProductKey y DeviceName. Si especifica un valor para el parámetro IotId, no necesita especificar valores para los parámetros ProductKey y DeviceName. Si especifica valores para los parámetros IotId, ProductKey y DeviceName, el valor del parámetro IotId tendrá prioridad.
Qos	Integer	No	1	El nivel de calidad de servicio (QoS) del mensaje. Valores válidos: 0 (predeterminado): El sistema envía el mensaje como máximo una vez. 1: El sistema envía el mensaje como mínimo una vez. Si no se devuelve una respuesta PUBACK después de publicar un mensaje QoS 1, el mensaje se reenvía al dispositivo cuando este se reconecta a IoT Platform.

Además de los parámetros de solicitud específicos de la operación mencionados anteriormente, debe configurar los parámetros de solicitud comunes al llamar a esta operación. Para obtener más información sobre los parámetros de solicitud comunes, 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 si la llamada falla. Para obtener más información, consulte Códigos de error.
Data	Struct		Los datos devueltos si la llamada es exitosa.
MessageId	String	abcabcabc1234****	El ID del mensaje. IoT Platform envía el mensaje al dispositivo para invocar el servicio.
Result	String	{"param1":1}	El resultado de la llamada síncrona. Si invoca el servicio de forma asíncrona, este parámetro no se devuelve.
ErrorMessage	String	A system exception occurred.	El mensaje de error devuelto si 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. Sin embargo, este valor no indica que el servicio se haya ejecutado. Para obtener el resultado de la ejecución, consulte los registros del dispositivo. false: La llamada falló.

Ejemplos

Solicitudes de muestra

https://iot.cn-shanghai.aliyuncs.com/?Action=InvokeThingService
&ProductKey=a1BwAGV****
&DeviceName=device1
&Identifier=service1
&Args=%7B%22param1%22%3A1%7D
&<Common request parameters>

Respuestas exitosas de muestra

Formato XML

<InvokeThingServiceResponse>
  <Data>
        <Result>{"code":200,"data":{},"id":"100686","message":"success","version":"1.0"}</Result>
        <MessageId>abcabc123</MessageId>
  </Data>
  <RequestId>A44C818E-FA7F-4765-B1E7-01D14AE01C6A</RequestId>
  <Success>true</Success>
</InvokeThingServiceResponse>

Formato JSON

{
  "Data": {
    "Result": "{\"code\":200,\"data\":{},\"id\":\"100686\",\"message\":\"success\",\"version\":\"1.0\"}", 
    "MessageId": "abcabc123"
  }, 
  "RequestId": "A44C818E-FA7F-4765-B1E7-01D14AE01C6A", 
  "Success": true
}

Códigos de error

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