V2.1 Invoke Service¶

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

该 API 支持在 EnOS 2.1.0 及以上环境中使用。

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

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

操作权限¶

使用此 API 前，确保服务账号已被授予包含下列服务和操作权限的策略。有关授权服务账号的更多信息，参见管理服务账号。

需授权的服务	所需操作权限
资产	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。如何获取 assetId 信息>>
productKey	Query	可选（见上述注解）	String	设备的 product key，需与 `deviceKey` 一起使用。如何获取设备的三元组信息>>
deviceKey	Query	可选（见上述注解）	String	设备的 device key，需与 `productKey` 一起使用。如何获取设备的三元组信息>>
serviceId	Query	必需	String	被调用服务ID。前往模型详情的功能定义页，在功能 ID 列获取 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 的定义。

如果 ThingModel 中参数值为必填，参数值为 null，参数值将会用 ThingModel 中定义好的默认值替换。如果参数是 null，且没有默认值，就会返回错误消息。

响应参数¶

名称	数据类型	描述
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
    }
}

SDK 示例¶

你可以在 Github 上获取接入服务的 SDK 示例：

Java
Python