Invoke Service¶
向设备下发服务调用接口。
这个接口可以执行缓存命令或者即时命令。当执行即时命令时,需要等待设备返回服务调用的结果后,才返回接口响应数据。如果设备在规定的服务执行超时时间内,未返回服务调用的结果,EnOS服务调用会等待到超时时间后,返回接口超时响应数据。
如果是缓存命令,则直接放入缓存后返回用户。
操作权限¶
需授权的资源 |
所需操作权限 |
---|---|
资产 |
Control |
请求格式¶
POST https://{apigw-address}/connect-service/v2.1/commands?action=invokeService
请求参数(URI)¶
备注
以下非必须字段中,必须提供 assetId
或 productKey
+ deviceKey
的组合,用于指定设备。
名称 |
位置(Path/Query) |
必需/可选 |
数据类型 |
描述 |
---|---|---|---|---|
orgId |
Query |
必需 |
String |
资产所属的组织ID。 如何获取orgId信息>> |
assetId |
Query |
可选 |
String |
资产ID。 如何获取Asset ID信息>> |
productKey |
Query |
可选 |
String |
Product Key. |
deviceKey |
Query |
可选 |
String |
Device Key. |
serviceId |
Query |
必需 |
String |
被调用服务ID。 |
pendingTtl |
Query |
可选 |
Long |
缓存存储时间,单位为秒,范围[0 - 172800(即48小时)],默认值为0。当pendingTtl为0时,表示命令即时执行。 |
timeout |
Query |
可选 |
Integer |
服务执行超时时间,单位为秒,范围[1 - 60],默认值为30秒。 |
请求参数(Body)¶
名称 |
必需/可选 |
数据类型 |
描述 |
---|---|---|---|
inputData |
可选 |
Map(Key为String,Value为String,Number,Array或Object) |
服务调用的输入参数,key为参数标识符,value值类型需要符合 |
响应参数¶
名称 |
数据类型 |
描述 |
---|---|---|
data |
InvokeService结构体 |
服务调用结果,见 服务调用返回结构体>> |
InvokeService结构体¶
名称 |
数据类型 |
描述 |
---|---|---|
commandId |
String |
命令ID。 |
outputData |
Map(Key为String,Value为String,Number,Array或Object) |
当请求的pendingTtl为0,即请求命令即时执行时,返回设备服务调用结果,需要符合 |
错误码¶
有关错误码的描述,参见 错误码。
示例¶
请求示例¶
https://{apigw-address}/connect-service/v2.1/commands?action=invokeService&deviceKey=yourDeviceKey&pendingTtl=1000&productKey=yourProductKey&serviceId=identifier&orgId=yourOrgId&timeout=30
method: POST
requestBody:
{
"inputData":{
"parameter_1":22.2,
"parameter_2":11
}
}
返回示例¶
{
"code":0,
"msg":"OK",
"requestId":"7d863d517eae4f18a2776452eb1305bb",
"data":{
"commandId":"2078724684846989312",
"outputData":null
}
}
Java SDK调用示例¶
package com.envisioniot.enos.api.sample.connect_service.command;
import com.envision.apim.poseidon.config.PConfig;
import com.envision.apim.poseidon.core.Poseidon;
import com.envisioniot.enos.connect_service.v2_1.service.InvokeServiceRequest;
import com.envisioniot.enos.connect_service.v2_1.service.InvokeServiceResponse;
import com.google.common.collect.ImmutableMap;
public class InvokeService {
public static void main(String[] args) {
String appKey = "yourAppKey";
String appSecret = "yourAppSecret";
String serverUrl = "yourServerUrl";
String orgId = "yourOrgId";
String productKey = "yourProductKey";
String deviceKey = "yourDeviceKey";
String serviceIdentifier = "yourServiceIdentifier";
InvokeServiceRequest request = new InvokeServiceRequest();
request.setOrgId(orgId);
request.setProductKey(productKey);
request.setDeviceKey(deviceKey);
request.setServiceId(serviceIdentifier);
request.setInputData(ImmutableMap.of("parameter_1", 22.2, "parameter_2", 11));
request.setPendingTtl(3600L); // e.g. pending TTL is 1 hour
request.setTimeout(30); // timeout is 30 seconds
InvokeServiceResponse response = Poseidon.config(PConfig.init().appKey(appKey).appSecret(appSecret).debug())
.url(serverUrl)
.getResponse(request, InvokeServiceResponse.class);
}
}