QueryDeviceBySQL - 阿里云物联网平台

使用说明

仅支持搜索华东2（上海）、日本（东京）地域企业版实例中的设备。
调用该接口，单次最多查询到10,000个设备。使用说明，请参见下文SQL语句的LIMIT子句说明。

QPS限制

单个阿里云账号调用该接口的每秒请求数（QPS）最大限制为10。

说明 RAM用户共享阿里云账号配额。

调试

您可以在OpenAPI Explorer中直接运行该接口，免去您计算签名的困扰。运行成功后，OpenAPI Explorer可以自动生成SDK代码示例。

请求参数


名称	类型	是否必选	示例值	描述
Action	String	是	QueryDeviceBySQL	系统规定参数。取值：QueryDeviceBySQL。
SQL	String	是	SELECT * FROM device where product_key = "a1*********" limit 100, 20	查询设备的类SQL语句。具体要求和示例见下文请求参数补充说明。
IotInstanceId	String	否	iot-cn-0pp1n8t****	实例ID。您可在物联网平台控制台的实例概览页面，查看当前实例的ID。重要若有ID值，必须传入该ID值，否则调用会失败。若无实例概览页面或ID值，则无需传入。实例的更多信息，请参见实例概述。

使用QueryDeviceBySQL进行设备高级搜索时，类SQL语句由SELECT子句、WHERE子句、ORDER BY子句（可选）、LIMIT子句（可选）组成。长度限制400个字符。

示例：

SELECT * FROM device WHERE product_key = "a1*********" order by active_time limit 0,10


SQL子句	说明
SELECT子句	`SELECT [field]/[count()] FROM device` 其中field为需要获取的字段，请参见下面的检索字段说明。也可填，获取所有字段。如果需要获取count计数，则填count(*)。
WHERE子句	`WHERE [condition1] AND [condition2]` 最多使用5个condition，且不支持嵌套，请参见下面的检索字段说明、运算符说明。连接词支持AND、OR，最多使用5个连接词。
ORDER BY子句（可选）	ORDER BY子句用于实现自定义排序，可自定义排序的字段包括gmt_create、gmt_modified、active_time。该子句可不填，不填时随机排序。
LIMIT子句（可选）	LIMIT子句用于控制查询的偏移量，有两种用法，参见下表“LIMIT子句使用方法”。如果不填LIMIT子句，则默认为`limit 20`。

LIMIT子句使用方法：


方法	说明
limit k	限制k<=50，即单页最大为50。示例： `SELECT * FROM device WHERE product_key = "a1*****" limit 10`
limit n,k	限制n+k<=10000且k<=50，即最大偏移量为10000且单页最大为50。示例： `SELECT * FROM device WHERE product_key = "a1*****" limit 40,10`

检索字段说明


字段名	类型	说明
product_key	text	设备所属产品ProductKey。
iot_id	text	设备标识符。默认返回iot_id。
name	text	设备名称。
active_time	date	设备激活时间。格式为yyyy-MM-dd HH:mm:ss.SSS，精确到毫秒。
nickname	text	设备备注名称。
gmt_create	date	设备创建时间。格式为yyyy-MM-dd HH:mm:ss.SSS，精确到毫秒。
gmt_modified	date	设备信息最后一次更新时间。格式为yyyy-MM-dd HH:mm:ss.SSS，精确到毫秒。
status	text	设备状态，取值： ONLINE：在线。 OFFLINE：离线。 UNACTIVE：未激活。 DISABLE：已禁用。
group.group_id	text	设备分组ID。
tag.tag_name	text	设备标签名。
tag.tag_value	text	设备标签值。
ota_module.name	text	OTA模块名称。与ota_module.version配合使用，用于指定设备当前OTA版本号对应的OTA模块。 ota_module.version可不传入，不传入时，将不能根据模块名称检索设备。
ota_module.version	text	OTA固件版本。

运算符说明


运算符	支持的字段数值类型
=	number、date、text
!=	number、date、text
>	number、date
<	number、date
LIKE	text

其中：

=和!=：使用时，支持检索字段值取值为null。
LIKE：使用时，支持前缀匹配，不支持后缀匹配或通配符匹配。前缀不得少于4个字符，且不能包含任何特殊字符，例如反斜线（\）、正斜线（/）、and（&）、加号（+）、短划线（-）、感叹号（!）、半角圆括号（()）、半角冒号（:）、波浪线（~）、大括号（{}）、星号（*）、半角问号（?）等。前缀填写完成后，必须固定以% 结尾。

示例：SELECT * FROM device where product_key = "a1*********" and name LIKE "test%" limit 10

调用API时，除了本文介绍的该API的特有请求参数，还需传入公共请求参数。公共请求参数说明，请参见公共参数文档。

返回数据


名称	类型	示例值	描述
Code	String	iot.system.SystemException	调用失败时，返回的错误码。更多信息，请参见错误码。
Data	Array of SimpleDeviceSearchInfo		调用成功时，返回的设备信息。
ActiveTime	String	2020-04-04 16:38:18.607	设备激活时间，GMT格式。
DeviceName	String	light	设备名称。
GmtCreate	String	2020-04-04 16:38:17.000	设备创建时间，GMT格式。
GmtModified	String	2020-04-04 16:38:19.000	设备信息最后一次更新时间，GMT格式。
Groups	Array of SimpleDeviceGroupInfo		设备分组信息。
GroupId	String	a1d21d2fas	分组ID。
IotId	String	Q7uOhVRdZRRlDnTLv****00100	设备ID。物联网平台为该设备颁发的ID，设备的唯一标识符。
Nickname	String	智能灯设备	设备的备注名称。
OTAModules	Array of OTAModuleInfo		设备的模块固件信息列表。
FirmwareVersion	String	a1-dads2-dad2	OTA模块版本号。
ModuleName	String	SomeSampleModule	OTA模块名称。
ProductKey	String	a1BwAGV****	设备所属产品ProductKey。
Status	String	ONLINE	设备状态。返回值： ONLINE：在线。 OFFLINE：离线。 UNACTIVE：未激活。 DISABLE：已禁用。
Tags	Array of TagInfo		设备标签信息。
TagName	String	Color	标签名。
TagValue	String	Red	标签值。
ErrorMessage	String	系统异常	调用失败时，返回的出错信息。
RequestId	String	E55E50B7-40EE-4B6B-8BBE-D3ED55CCF565	阿里云为该请求生成的唯一标识符。
TotalCount	Long	100	当SELECT子句为`SELECT count(*) FROM device`时，返回的count计数。
Success	Boolean	true	是否调用成功。 true：调用成功。 false：调用失败。

示例

请求示例

https://iot.cn-shanghai.aliyuncs.com/?Action=QueryDeviceBySQL
&IotInstanceId=iot-cn-0pp1n8t****
&SQL=SELECT * FROM device where product_key = "a1*********" limit 100, 20
&<公共请求参数>

正常返回示例

XML格式

<QueryDeviceBySQLResponse>
  <RequestId>501CFABA-2C48-468D-B88C-3AA8E3B3A8F3</RequestId>
  <Data>
        <Status>OFFLINE</Status>
        <IotId>ii1*******</IotId>
        <GmtCreate>2020-04-04 16:38:17.000</GmtCreate>
        <ActiveTime>2020-04-04 16:38:18.607</ActiveTime>
        <GmtModified>2020-04-04 16:38:19.000</GmtModified>
        <ProductKey>a1*********</ProductKey>
        <DeviceName>testDevcieae7f3a</DeviceName>
  </Data>
  <Data>
        <Status>UNACTIVE</Status>
        <IotId>5wt*******</IotId>
        <GmtCreate>2020-04-04 16:37:32.000</GmtCreate>
        <Groups>
              <GroupId>Ix4*******</GroupId>
        </Groups>
        <Groups>
              <GroupId>Xrn*******</GroupId>
        </Groups>
        <Groups>
              <GroupId>J9l*******</GroupId>
        </Groups>
        <OTAModules>
              <ModuleName>SomeSampleModule</ModuleName>
              <FirmwareVersion>a1-dads2-dad2</FirmwareVersion>
        </OTAModules>
        <OTAModules>
              <ModuleName>SampleModule</ModuleName>
              <FirmwareVersion>a1-dads2-dad1</FirmwareVersion>
        </OTAModules>
        <GmtModified>2020-04-04 16:37:32.000</GmtModified>
        <ProductKey>a1*********</ProductKey>
        <DeviceName>testDevcie676a22</DeviceName>
  </Data>
  <Success>true</Success>
</QueryDeviceBySQLResponse>

JSON格式

{
    "RequestId": "501CFABA-2C48-468D-B88C-3AA8E3B3A8F3",
    "Data": [
        {
            "Status": "OFFLINE",
            "IotId": "ii1*******",
            "GmtCreate": "2020-04-04 16:38:17.000",
            "ActiveTime": "2020-04-04 16:38:18.607",
            "GmtModified": "2020-04-04 16:38:19.000",
            "ProductKey": "a1*********",
            "DeviceName": "testDevcieae7f3a"
        },
        {
            "Status": "UNACTIVE",
            "IotId": "5wt*******",
            "GmtCreate": "2020-04-04 16:37:32.000",
            "Groups": [
                {
                    "GroupId": "Ix4*******"
                },
                {
                    "GroupId": "Xrn*******"
                },
                {
                    "GroupId": "J9l*******"
                }
            ],
            "OTAModules": [
                {
                    "ModuleName": "SomeSampleModule",
                    "FirmwareVersion": "a1-dads2-dad2"
                },
                {
                    "ModuleName": "SampleModule",
                    "FirmwareVersion": "a1-dads2-dad1"
                }
            ],
            "GmtModified": "2020-04-04 16:37:32.000",
            "ProductKey": "a1*********",
            "DeviceName": "testDevcie676a22"
        }
    ],
    "Success": true
}