QueryDeviceBySQL - IoT Platform

使用說明

僅支援搜尋華東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
}

錯誤碼

訪問錯誤中心查看更多錯誤碼。