Invoke Service

向设备下发服务调用接口。

这个接口可以执行缓存命令或者即时命令。当执行即时命令时,需要等待设备返回服务调用的结果后,才返回接口响应数据。如果设备在规定的服务执行超时时间内,未返回服务调用的结果,EnOS服务调用会等待到超时时间后,返回接口超时响应数据。

如果是缓存命令,则直接放入缓存后返回用户。

操作权限

需授权的资源

所需操作权限

资产

Control

请求格式

POST https://{apigw-address}/connect-service/v2.1/commands?action=invokeService

请求参数(URI)

备注

以下非必须字段中,必须提供 assetIdproductKey + 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值类型需要符合 ThingModel 的定义。

响应参数

名称

数据类型

描述

data

InvokeService结构体

服务调用结果,见 服务调用返回结构体>>

InvokeService结构体

名称

数据类型

描述

commandId

String

命令ID。

outputData

Map(Key为String,Value为String,Number,Array或Object)

当请求的pendingTtl为0,即请求命令即时执行时,返回设备服务调用结果,需要符合 ThingModel 的定义。当请求的 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);
    }
}