Calls multiple device services at a time.

Usage notes

This operation can only be asynchronously called.

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 return the ID.
  • The code parameter specifies the result of the service call. The value is an integer.
  • The data parameter indicates the result of the service call. This parameter is returned to the service caller. You can specify the parameters included in the returned result. The data must be in JSON format.

  • The message and localizedMsg parameters are optional.

    Link SDK for C of IoT Platform provides an example on how to use a Thing Specification Language (TSL) model. For more information, see Call device services.

QPS limits

You can call this API operation up to 10 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

ParameterTypeRequiredExampleDescription
ActionStringYesInvokeThingsService

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

ArgsStringYes{"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.
DeviceName.NRepeatListYesdevice1

The name of the device whose service is called. You can specify up to 100 device names.

IdentifierStringYesSet

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, you can 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.
ProductKeyStringYesa1BwAGV****

The ProductKey of the product to which the device belongs.

IotInstanceIdStringNoiot_instc_pu****_c*-v64********

The ID of the IoT 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 Instance overview.

QosIntegerNo1

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, see Common parameters.

Response parameters

ParameterTypeExampleDescription
CodeStringiot.system.SystemException

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

ErrorMessageStringA system exception occurred.

The error message returned if the call fails.

RequestIdStringE55E50B7-40EE-4B6B-8BBE-D3ED55CCF565

The ID of the request.

SuccessBooleantrue

Indicates whether the call was successful. Valid values:

  • true: The call was successful. However, this result 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=InvokeThingsService
&Args=%7B%20%20%20%20%20%22walk%22%3A%22a~z%22%2C%20%20%20%20%20%22city%22%3A%22shanghai%22%20%7D
&DeviceName.1=1102andriod02
&DeviceName.2=1102android01
&Identifier=TimeReset
&ProductKey=a1hWjHD****
&<Common request parameters>

Sample success responses

XML format

<InvokeThingsServiceResponse>
  <RequestId>059C3274-6197-4BEC-95E4-49A076330E57</RequestId>
  <Success>true</Success>
</InvokeThingsServiceResponse>

JSON format

{
  "RequestId": "059C3274-6197-4BEC-95E4-49A076330E57",
  "Success": true
}

Error codes

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