InvokeThingService - IoT Platform

Calls a service of a device.

Usage notes

When you define a service in a Thing Specification Language (TSL) model, the mode in which the service is called is specified. When you call a service by using this operation, IoT Platform uses a call mode based on the value of the Identifier parameter.

Synchronous mode: IoT Platform sends a revert-remote procedure call (RRPC) request to a device. Then, the device synchronously returns an RRPC response. For more information about how to use an RRPC, see What is RRPC?
Asynchronous mode: IoT Platform sends an RRPC request to a device. Then, the device asynchronously returns an RRPC response. For more information about topics, see Device properties, events, and services.

Important If you set the Checksum Type parameter to Verification-free when you create a product, the asynchronous mode is used.

When the device receives the service call, the device returns a response to the service caller. When you configure the device, you must specify the response logic and response parameters. The data formats of response parameters must comply with the Alink protocol. Example:


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

Note

The id parameter specifies the unique identifier of the request. The ID is generated by IoT Platform. The device can obtain the ID from the request parameters and then return the ID.
The code parameter specifies the result of the service call. The value of the parameter is an integer.
The data parameter specifies the result of the service call. This parameter is returned to the service caller. You can specify the parameters that you want to include in the returned result. The data must be in the JSON format.
The message and localizedMsg parameters are optional.
Link SDK for C of IoT Platform provides an example on how to use a TSL model. For more information, see Call device services.

Limits

If you synchronously call a service, the timeout period is 8 seconds. If a server does not receive a response within 8 seconds, a timeout error occurs. No limit is imposed on the timeout period of asynchronous calls.

Limit for QPS

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	InvokeThingService	The operation that you want to perform. Set the value to InvokeThingService.
Args	String	Yes	{"param1":1}	The input parameter of the service. The value is a JSON string. Example: Args={"param1": 1}. If you do not want to configure an input parameter for the service, set the value to Args={}. Important If the TSL data is of the float type or double type, the parameter values that correspond to the TSL data contain at least one decimal place. Examples: 10.0 and 11.1.
Identifier	String	Yes	Set	The identifier of the service. To view the identifier of the service, you can use one of the following methods: Log on to the IoT Platform console. On the Define Feature tab of the product to which the device belongs, view the identifier. Call the QueryThingModel operation and view the identifier in the TSL information that is returned. Note If a service named testService belongs to a custom module named testFb, you can set this parameter to testFb:testService. The custom module is not the default module.
IotInstanceId	String	No	iot_instc_pu***_c-v64********	The ID of the IoT instance. On the Overview page in the IoT Platform console, you can view the ID of the instance. Important If your instance has an ID, you must specify the ID for the 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 Instance overview.
ProductKey	String	No	a1BwAGV****	The ProductKey of the product to which the device belongs. Important If you specify a value for this parameter, you must configure the DeviceName parameter.
DeviceName	String	No	light	The DeviceName of the device to which the required service belongs. Important If you specify a value for this parameter, you must configure the ProductKey parameter.
IotId	String	No	Q7uOhVRdZRRlDnTLv****00100	The ID of the device. The ID is a unique identifier that is issued by IoT Platform to the device. Important The IotId parameter specifies a GUID for the device. The value of the IotId parameter is equivalent to a combination of the values of the ProductKey and DeviceName parameters. If you specify a value for the IotId parameter, you do not need to specify values for the ProductKey and DeviceName parameters. If you specify values for the IotId,ProductKey, and DeviceName parameters, the value of the IotId parameter takes precedence.
Qos	Integer	No	1	The quality of service (QoS) level of the message. Valid values: 0 (default): The system sends the message at most once. 1: The system sends the message at least once. If a PUBACK response is not returned after you publish a QoS 1 message, the message is resent to the device when the device reconnects to IoT Platform.

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.
Data	Struct		The data returned if the call is successful.
MessageId	String	abcabcabc1234****	The ID of the message. IoT Platform sends the message to the device to call the service.
Result	String	{"param1":1}	The result of the synchronous call. If you asynchronously call the service, this parameter is not returned.
ErrorMessage	String	A system exception occurred.	The error message returned if the call fails.
RequestId	String	E55E50B7-40EE-4B6B-8BBE-D3ED55CCF565	The ID of the request.
Success	Boolean	true	Indicates whether the call was successful. Valid values true: The call was successful. However, this value does not indicate that the service is executed. To obtain the execution result, view the logs of the device. false: The call failed.

Examples

Sample requests

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

Sample success responses

XML format

<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>

JSON format

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

Error codes

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