调用该接口通过类SQL语句快速搜索满足指定条件的设备。

使用说明

  • 仅支持搜索华东2(上海)、华北2(北京)、华南1(深圳)地域企业版实例中的设备。
  • 调用该接口,单次最多查询到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
}

错误码

访问错误中心查看更多错误码。