文档首页> 设备接入 IoTDA> API参考> 应用侧API参考> API> 设备管理> 查询设备列表
更新时间：2024-05-29 GMT+08:00
查看PDF

查询设备列表

功能介绍

应用服务器可调用此接口查询物联网平台中的设备信息列表。

调试

您可以在API Explorer中调试该接口，支持自动认证鉴权。API Explorer可以自动生成SDK代码示例，并提供SDK代码示例调试功能。

URI

GET /v5/iot/{project_id}/devices

表1 路径参数

参数

是否必选

参数类型

描述

project_id

是

String

参数说明：项目ID。获取方法请参见 获取项目ID。
表2 Query参数

参数

是否必选

参数类型

描述

product_id

否

String

参数说明：设备关联的产品ID，用于唯一标识一个产品模型，创建产品后获得。方法请参见 创建产品。 取值范围：长度不超过36，只允许字母、数字、下划线（_）、连接符（-）的组合。

gateway_id

否

String

参数说明：网关ID，用于标识设备所属的父设备，即父设备的设备ID。携带该参数时，表示查询该设备下的子设备，默认查询下一级子设备，如果需要查询该设备下所有各级子设备，请同时携带is_cascade_query参数为true；不携带该参数时，表示查询用户下所有设备。 取值范围：长度不超过128，只允许字母、数字、下划线（_）、连接符（-）的组合。

is_cascade_query

否

Boolean

参数说明：是否级联查询，该参数仅在同时携带gateway_id时生效。默认值为false。 取值范围：

  • true：表示查询设备ID等于gateway_id参数的设备下的所有各级子设备。

  • false：表示查询设备ID等于gateway_id参数的设备下的一级子设备。

缺省值：false

node_id

否

String

参数说明：设备标识码，通常使用IMEI、MAC地址或Serial No作为node_id。 取值范围：长度不超过64，只允许字母、数字、下划线（_）、连接符（-）的组合。

device_name

否

String

参数说明：设备名称，资源空间下唯一，用于资源空间下唯一标识一个设备。 取值范围：长度不超过256，只允许中文、字母、数字、以及_?'#().,&%@!-等字符的组合。

limit

否

Integer

参数说明：分页查询时每页显示的记录数。 取值范围：1-50的整数，默认值为10。

最小值：1

最大值：50

缺省值：10

marker

否

String

参数说明：上一次分页查询结果中最后一条记录的ID，在上一次分页查询时由物联网平台返回获得。分页查询时物联网平台是按marker也就是记录ID降序查询的，越新的数据记录ID也会越大。若填写marker，则本次只查询记录ID小于marker的数据记录。若不填写，则从记录ID最大也就是最新的一条数据开始查询。如果需要依次查询所有数据，则每次查询时必须填写上一次查询响应中的marker值。 取值范围：长度为24的十六进制字符串，默认值为ffffffffffffffffffffffff。

缺省值：ffffffffffffffffffffffff

offset

否

Integer

参数说明：表示从marker后偏移offset条记录开始查询。默认为0，取值范围为0-500的整数。当offset为0时，表示从marker后第一条记录开始输出。限制offset最大值是出于API性能考虑，您可以搭配marker使用该参数实现翻页，例如每页50条记录，1-11页内都可以直接使用offset跳转到指定页，但到11页后，由于offset限制为500，您需要使用第11页返回的marker作为下次查询的marker，以实现翻页到12-22页。 取值范围：0-500的整数，默认为0。

最小值：0

最大值：500

缺省值：0

start_time

否

String

参数说明：查询设备注册时间在startTime之后的记录，格式：yyyyMMdd'T'HHmmss'Z'，如20151212T121212Z。

end_time

否

String

参数说明：查询设备注册时间在endTime之前的记录，格式：yyyyMMdd'T'HHmmss'Z'，如20151212T121212Z。

app_id

否

String

参数说明：资源空间ID。此参数为非必选参数，存在多资源空间的用户需要使用该接口时，可以携带该参数查询指定资源空间下的设备列表，不携带该参数则会查询该用户下所有设备列表。 取值范围：长度不超过36，只允许字母、数字、下划线（_）、连接符（-）的组合。

请求参数

表3 请求Header参数

参数

是否必选

参数类型

描述

X-Auth-Token

否

String

参数说明：用户Token。通过调用IAM服务 获取IAM用户Token接口获取，接口返回的响应消息头中“X-Subject-Token”就是需要获取的用户Token。简要的获取方法样例请参见 Token认证。

Instance-Id

否

String

参数说明：实例ID。物理多租下各实例的唯一标识，建议携带该参数，在使用专业版时必须携带该参数。您可以在IoTDA管理控制台界面，选择左侧导航栏“总览”页签查看当前实例的ID，具体获取方式请参考 查看实例详情。

响应参数

状态码： 200

表4 响应Body参数

参数

参数类型

描述

devices

Array of QueryDeviceSimplify objects

设备信息列表。

page

Page object

查询结果的分页信息。
表5 QueryDeviceSimplify

参数

参数类型

描述

app_id

String

资源空间ID。

app_name

String

资源空间名称。

device_id

String

设备ID，用于唯一标识一个设备。在注册设备时直接指定，或者由物联网平台分配获得。由物联网平台分配时，生成规则为"product_id" + "_" + "node_id"拼接而成。

node_id

String

设备标识码，通常使用IMEI、MAC地址或Serial No作为node_id。

gateway_id

String

网关ID，用于标识设备所属的父设备，即父设备的设备ID。当设备是直连设备时，gateway_id与设备的device_id一致。当设备是非直连设备时，gateway_id为设备所关联的父设备的device_id。

device_name

String

设备名称。

node_type

String

设备节点类型。

  • ENDPOINT：非直连设备。

  • GATEWAY：直连设备或网关。

  • UNKNOWN：未知。

description

String

设备的描述信息。

fw_version

String

设备的固件版本。

sw_version

String

设备的软件版本。

device_sdk_version

String

设备的sdk信息。

product_id

String

设备关联的产品ID，用于唯一标识一个产品模型。

product_name

String

设备关联的产品名称。

status

String

设备的状态。

  • ONLINE：设备在线。

  • OFFLINE：设备离线。

  • ABNORMAL：设备异常。

  • INACTIVE：设备未激活。

  • FROZEN：设备冻结。

tags

Array of TagV5DTO objects

设备的标签列表。
表6 TagV5DTO

参数

参数类型

描述

tag_key

String

参数说明：标签键，在同一资源下标签键唯一。绑定资源时，如果设置的键已存在，则将覆盖之前的标签值。如果设置的键值不存在，则新增标签。 取值范围：长度不超过64，只允许中文、字母、数字、以及_.-等字符的组合。

tag_value

String

参数说明：标签值。 取值范围：长度不超过128，只允许中文、字母、数字、以及_.-等字符的组合。
表7 Page

参数

参数类型

描述

count

Long

满足查询条件的记录总数。

marker

String

本次分页查询结果中最后一条记录的ID，可在下一次分页查询时使用。

请求示例

列表查询所有设备

GET https://{endpoint}/v5/iot/{project_id}/devices

响应示例

状态码： 200

OK

{
  "devices" : [ {
    "app_id" : "jeQDJQZltU8iKgFFoW060F5SGZka",
    "app_name" : "testAPP01",
    "device_id" : "d4922d8a-6c8e-4396-852c-164aefa6638f",
    "node_id" : "ABC123456789",
    "gateway_id" : "d4922d8a-6c8e-4396-852c-164aefa6638f",
    "device_name" : "dianadevice",
    "node_type" : "ENDPOINT",
    "description" : "watermeter device",
    "fw_version" : "1.1.0",
    "sw_version" : "1.1.0",
    "product_id" : "b640f4c203b7910fc3cbd446ed437cbd",
    "product_name" : "Thermometer",
    "status" : "INACTIVE",
    "tags" : [ {
      "tag_key" : "testTagName",
      "tag_value" : "testTagValue"
    } ]
  } ],
  "page" : {
    "count" : 100,
    "marker" : "5c8f3d2d3df1f10d803adbda"
  }
}

状态码

状态码

描述

200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

500

Internal Server Error

错误码

请参见错误码。

父主题： 设备管理