查询设备消息
功能介绍
应用服务器可调用此接口查询平台下发给设备的消息，平台为每个设备默认最多保存20条消息，超过20条后， 后续的消息会替换下发最早的消息。
调试
您可以在API Explorer中调试该接口，支持自动认证鉴权。API Explorer可以自动生成SDK代码示例，并提供SDK代码示例调试功能。
URI
GET /v5/iot/{project_id}/devices/{device_id}/messages
|
参数 |
是否必选 |
参数类型 |
描述 |
|---|---|---|---|
|
project_id |
是 |
String |
参数说明：项目ID。获取方法请参见 获取项目ID。 |
|
device_id |
是 |
String |
参数说明：下发消息的设备ID，用于唯一标识一个设备，在注册设备时由物联网平台分配获得。 取值范围：长度不超过128，只允许字母、数字、下划线（_）、连接符（-）的组合。 |
请求参数
|
参数 |
是否必选 |
参数类型 |
描述 |
|---|---|---|---|
|
X-Auth-Token |
否 |
String |
参数说明：用户Token。通过调用IAM服务 获取IAM用户Token接口获取，接口返回的响应消息头中“X-Subject-Token”就是需要获取的用户Token。简要的获取方法样例请参见 Token认证。 |
|
Instance-Id |
否 |
String |
参数说明：实例ID。物理多租下各实例的唯一标识，建议携带该参数，在使用专业版时必须携带该参数。您可以在IoTDA管理控制台界面，选择左侧导航栏“总览”页签查看当前实例的ID，具体获取方式请参考 查看实例详情。 |
响应参数
状态码： 200
|
参数 |
参数类型 |
描述 |
|---|---|---|
|
device_id |
String |
设备ID，用于唯一标识一个设备，在注册设备时由物联网平台分配获得。 |
|
messages |
Array of DeviceMessage objects |
设备消息列表。 |
|
参数 |
参数类型 |
描述 |
|---|---|---|
|
message_id |
String |
设备消息ID，用于唯一标识一条消息，在下发设备消息时由物联网平台分配获得。 |
|
name |
String |
消息名称,在下发消息时由用户指定。 |
|
message |
Object |
消息内容。 |
|
encoding |
String |
消息内容编码格式，取值范围none|base64,默认值none, base64格式仅支持透传。 |
|
payload_format |
String |
有效负载格式，在消息内容编码格式为none时有效，取值范围standard|raw，默认值standard（平台封装的标准格式），取值为raw时直接将消息内容作为有效负载下发。 |
|
topic |
String |
消息topic |
|
properties |
PropertiesDTO object |
消息下行到设备的属性参数。 |
|
status |
String |
消息状态，包含PENDING，DELIVERED，FAILED和TIMEOUT，PENDING指设备不在线，消息被缓存起来，等设备上线之后下发； DELIVERED指消息发送成功；FAILED消息发送失败；TIMEOUT指消息在平台默认时间内（1天）还没有下发送给设备，则平台会将消息设置为超时，状态为TIMEOUT。 |
|
error_info |
ErrorInfoDTO object |
消息下发失败信息。 |
|
created_time |
String |
消息的创建时间，"yyyyMMdd'T'HHmmss'Z'"格式的UTC字符串。 |
|
finished_time |
String |
消息结束时间, "yyyyMMdd'T'HHmmss'Z'"格式的UTC字符串，包含消息转换到DELIVERED和TIMEOUT两个状态的时间。 |
|
参数 |
参数类型 |
描述 |
|---|---|---|
|
correlation_data |
String |
参数说明：MQTT 5.0版本请求和响应模式中的相关数据，可选。用户可以通过该参数配置MQTT协议请求和响应模式中的相关数据。 取值范围：长度不超过128，只允许字母、数字、下划线（_）、连接符（-）的组合。 |
|
response_topic |
String |
参数说明：MQTT 5.0版本请求和响应模式中的响应主题，可选。用户可以通过该参数配置MQTT协议请求和响应模式中的响应主题。 取值范围：长度不超过128, 只允许字母、数字、以及_-?=$#+/等字符的组合。 |
|
user_properties |
Array of UserPropDTO objects |
参数说明：用户自定义属性，可选。用户可以通过该参数配置用户自定义属性。可以配置的最大自定义属性数量为20。 |
请求示例
列表查询所有消息。
GET https://{endpoint}/v5/iot/{project_id}/devices/{device_id}/messages
响应示例
状态码： 200
OK
{
"device_id" : "d4922d8a-6c8e-4396-852c-164aefa6638f",
"messages" : [ {
"message_id" : "b1224afb-e9f0-4916-8220-b6bab568e888",
"name" : "message_name",
"message" : "string",
"encoding" : "none",
"payload_format" : "raw",
"topic" : "string",
"properties" : {
"correlation_data" : "string",
"response_topic" : "string",
"user_properties" : [ {
"prop_key" : "string",
"prop_value" : "string"
} ]
},
"status" : "PENDING",
"error_info" : {
"error_code" : "string",
"error_msg" : "string"
},
"created_time" : "20151212T121212Z",
"finished_time" : "20151212T121212Z"
} ]
}
状态码
|
状态码 |
描述 |
|---|---|
|
200 |
OK |
|
400 |
Bad Request |
|
401 |
Unauthorized |
|
403 |
Forbidden |
|
404 |
Not Found |
|
500 |
Internal Server Error |
错误码
请参见错误码。
