QueryDeviceBySQL - IoT Platform - Centro de documentación de Alibaba Cloud

Consulta dispositivos mediante la ejecución de una instrucción similar a SQL. Esta operación devuelve los dispositivos que cumplen las condiciones especificadas en dicha instrucción.

Descripción

La consulta de dispositivos en instancias de Enterprise Edition solo es compatible con las regiones China (Shanghai) y Japan (Tokyo)

, China (Beijing) y China (Shenzhen).
La operación QueryDeviceBySQL devuelve como máximo 10,000 dispositivos por cada llamada. Para obtener más información, consulte la sección "Sintaxis de las cláusulas LIMIT" de este tema.

Límites de QPS

Esta API se puede llamar hasta 10 veces por segundo por cuenta.

Nota

Los usuarios RAM de una cuenta de Alibaba Cloud comparten la cuota de dicha cuenta.

Depuración

OpenAPI Explorer calcula automáticamente el valor de la firma. Para mayor comodidad, se recomienda llamar a esta operación desde OpenAPI Explorer, ya que genera dinámicamente el código de ejemplo para distintos SDK.

Parámetros de solicitud

Parámetro	Tipo	Obligatorio	Ejemplo	Descripción
Action	String	Sí	QueryDeviceBySQL	Operación que se va a ejecutar. Establezca el valor en QueryDeviceBySQL.
SQL	String	Sí	SELECT * FROM device where product_key = "a1*********" limit 100, 20	Instrucción similar a SQL que se ejecutará para consultar los dispositivos. Consulte la siguiente sección para conocer los requisitos específicos y ver ejemplos.
IotInstanceId	String	No	iot-cn-0pp1n8t****	ID de la instancia. Consulte el ID de la instancia en la página Instance Overview de la consola de IoT Platform. Importante Si la instancia tiene un ID, debe especificarlo en este parámetro; de lo contrario, la llamada finaliza con errores. Si no se generó ninguna página Overview ni ningún ID para la instancia, no es necesario configurar este parámetro. Para obtener más información, consulte Descripción general.

Para consultar dispositivos con la operación QueryDeviceBySQL, especifique una instrucción similar a SQL. Dicha instrucción debe incluir una cláusula SELECT y una cláusula WHERE. También admite las cláusulas ORDER BY y LIMIT. La longitud máxima de cada instrucción es de 400 caracteres.

Ejemplos:

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

Cláusula SQL	Descripción
Cláusula SELECT	`SELECT [field]/[count()] FROM device` El parámetro field indica los campos que se desean obtener. En la siguiente tabla se describen dichos campos. Para obtener todos los campos, utilice un asterisco (). Si necesita conocer la cantidad de filas que cumplen las condiciones especificadas, indique count(*).
Cláusula WHERE	`WHERE [condition1] AND [condition2]` Se permiten hasta cinco condiciones. No se admite el anidamiento. En la siguiente tabla se detallan los campos y operadores disponibles. Utilice los operadores lógicos AND u OR para unir las condiciones, con un máximo de cinco operadores lógicos.
Cláusula ORDER BY (opcional)	Sirve para ordenar los campos. Los campos que admiten ordenamiento son gmt_create, gmt_modified y active_time. Esta cláusula es opcional. Si no la incluye, los resultados se ordenan de forma aleatoria.
Cláusula LIMIT (opcional)	Define el número máximo de filas que se devuelven por página y el total de filas que se obtienen. Para más detalles, consulte la sección "Sintaxis de las cláusulas LIMIT" de este tema. Si omite esta cláusula, se aplica limit 20 de manera predeterminada.

Sintaxis de las cláusulas LIMIT

Sintaxis

Descripción

limit k

El valor de k debe ser menor o igual a 50, lo que indica que cada página devuelve como máximo 50 filas. Ejemplo:

SELECT * FROM device WHERE product_key = "a1*****" limit 10

limit n,k

La suma de n y k debe ser menor o igual a 10,000, mientras que k no puede superar 50. Esto significa que el total de filas devueltas no excede 10,000 y cada página muestra como máximo 50 filas. Ejemplo:

SELECT * FROM device WHERE product_key = "a1*****" limit 40,10

Campos

Campo	Tipo	Descripción
product_key	text	ProductKey del producto al que pertenece el dispositivo.
iot_id	text	ID del dispositivo. De manera predeterminada, se devuelve iot_id.
name	text	Nombre del dispositivo.
active_time	date	Hora de activación del dispositivo. Sigue el formato yyyy-MM-dd HH:mm:ss.SSS y tiene precisión de milisegundos.
nickname	text	Alias del dispositivo.
gmt_create	date	Hora de creación del dispositivo. Sigue el formato yyyy-MM-dd HH:mm:ss.SSS y tiene precisión de milisegundos.
gmt_modified	date	Última hora de actualización de la información del dispositivo. Sigue el formato yyyy-MM-dd HH:mm:ss.SSS y tiene precisión de milisegundos.
status	text	Estado del dispositivo. Valores válidos: ONLINE: el dispositivo está en línea. OFFLINE: el dispositivo está sin conexión. UNACTIVE: el dispositivo no está activado. DISABLE: el dispositivo está deshabilitado.
group.group_id	text	ID del grupo de dispositivos.
tag.tag_name	text	Clave de la etiqueta del dispositivo.
tag.tag_value	text	Valor de la etiqueta del dispositivo.
ota_module.name	text	Nombre del módulo de actualización inalámbrica (OTA). Se recomienda usar este campo junto con ota_module.version para identificar el módulo OTA asociado al número de versión OTA actual del dispositivo. Si no configura el campo ota_module.version, no podrá buscar dispositivos por el nombre del módulo OTA.
ota_module.version	text	Versión de firmware del módulo OTA.

Operadores

Operador	Tipo de datos compatible
=	number, date y text
!=	number, date y text
>	number y date
<	number y date
LIKE	text

Descripción:

= y !=: al utilizar estos operadores, los valores de los campos consultados pueden ser nulos.
LIKE: este operador solo admite coincidencias de prefijo. El prefijo debe tener como mínimo cuatro caracteres y no puede contener caracteres especiales como barras invertidas (\), barras diagonales (/), signos et (&), signos más (+), guiones (-), signos de exclamación (!), paréntesis (), dos puntos (:), tildes (~), llaves {}, asteriscos (*) ni signos de interrogación (?). Además, debe terminar con un signo de porcentaje (%).

Ejemplo: SELECT * FROM device where product_key = "a1*********" and name LIKE "test%" limit 10.

Además de los parámetros de solicitud específicos de esta operación, debe configurar los parámetros de solicitud comunes al realizar la llamada. Para obtener más información sobre estos últimos, consulte Parámetros comunes.

Parámetros de respuesta

Parámetro	Tipo	Ejemplo	Descripción
Code	String	iot.system.SystemException	Código de error que se devuelve cuando la llamada finaliza con errores. Para obtener más información, consulte Códigos de error.
Data	Array of SimpleDeviceSearchInfo		Información del dispositivo que se devuelve si la llamada es exitosa.
ActiveTime	String	2020-04-04 16:38:18.607	Hora de activación del dispositivo, expresada en formato GMT.
DeviceName	String	light	Nombre del dispositivo.
GmtCreate	String	2020-04-04 16:38:17.000	Hora de creación del dispositivo, expresada en formato GMT.
GmtModified	String	2020-04-04 16:38:19.000	Última hora de actualización de la información del dispositivo, expresada en formato GMT.
Groups	Array of SimpleDeviceGroupInfo		Información de los grupos a los que pertenece el dispositivo.
GroupId	String	a1d21d2fas	ID del grupo.
IotId	String	Q7uOhVRdZRRlDnTLv****00100	ID del dispositivo. Es un identificador único asignado por IoT Platform.
Nickname	String	Smart light	Alias del dispositivo.
OTAModules	Array of OTAModuleInfo		Información del firmware de cada módulo del dispositivo.
FirmwareVersion	String	a1-dads2-dad2	Número de versión de cada módulo OTA.
ModuleName	String	SomeSampleModule	Nombre del módulo OTA.
ProductKey	String	a1BwAGV****	ProductKey del producto al que pertenece el dispositivo.
Status	String	ONLINE	Estado del dispositivo. Valores válidos: ONLINE: el dispositivo está en línea. OFFLINE: el dispositivo está sin conexión. UNACTIVE: el dispositivo no está activado. DISABLE: el dispositivo está deshabilitado.
Tags	Array of TagInfo		Información de las etiquetas del dispositivo.
TagName	String	Color	Clave de la etiqueta.
TagValue	String	Red	Valor de la etiqueta.
ErrorMessage	String	A system exception occurred.	Mensaje de error que se devuelve cuando la llamada finaliza con errores.
RequestId	String	E55E50B7-40EE-4B6B-8BBE-D3ED55CCF565	ID de la solicitud.
TotalCount	Long	100	Si en la instrucción similar a SQL especifica `SELECT count(*) FROM device`, se devuelve la cantidad de filas que cumplen las condiciones indicadas.
Success	Boolean	true	Indica si la llamada fue exitosa. Valores válidos: true: la llamada fue exitosa. false: la llamada finalizó con errores.

Ejemplos

Solicitudes de ejemplo

https://iot.cn-shanghai.aliyuncs.com/?Action=QueryDeviceBySQL
&IotInstanceId=iot-cn-0pp1n8t****
&SQL=SELECT * FROM device where product_key = "a1*********" limit 100, 20
&<Common request parameters>

Respuestas exitosas de ejemplo

Formato 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>

Formato 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
}

Códigos de error

Para consultar la lista de códigos de error, visite Códigos de error del servicio.