Updated on 2024-06-27 GMT+08:00

Query Device Messages

Function

This API is used by an application to query messages delivered by the platform to a device. By default, the platform stores up to 20 messages for each device. If the number of messages exceeds 20, the earliest messages will be overwritten by subsequent messages.

Debugging

You can debug this API through automatic authentication in API Explorer or use the SDK sample code generated by API Explorer.

URI

GET /v5/iot/{project_id}/devices/{device_id}/messages

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Parameter description: project ID. For details about how to obtain the project ID, see Obtaining a Project ID.

device_id

Yes

String

Parameter description: ID of the device to which the message is delivered. The ID is unique and is allocated by the platform during device registration. Value: The value can contain a maximum of 128 characters. Only letters, digits, underscores (_), and hyphens (-) are allowed.

Request Parameters

Table 2 Request header parameters

Parameter

Mandatory

Type

Description

X-Auth-Token

No

String

Parameter description: user token. You can obtain the token by calling the IAM API Obtaining a User Token Through Password Authentication. In the returned response header, X-Subject-Token is the desired user token. For details about how to obtain the token, see Token Authentication.

Instance-Id

No

String

Parameter description: instance ID. Unique identifier of each instance in the physical multi-tenant scenario. Mandatory for professional editions and recommended in other cases. Log in to the IoTDA console and choose Overview in the navigation pane to view the instance ID. For details, see Viewing Instance Details.

Response Parameters

Status code: 200

Table 3 Response body parameters

Parameter

Type

Description

device_id

String

Unique device ID, which is allocated by the platform during device registration.

messages

Array of DeviceMessage objects

List of device messages.

Table 4 DeviceMessage

Parameter

Type

Description

message_id

String

Device message ID, which is unique and is allocated by the platform during message delivery.

name

String

Message name specified during device message delivery.

message

Object

Message content.

encoding

String

Encoding format for the message content. Possible options are none and base64. The default value is none. base64 supports only transparent transmission.

payload_format

String

Valid payload format. This parameter is valid when encoding is none. Possible options are standard and raw. The default value is standard, indicating that the message content is encapsulated in the standard format. raw indicates that the message content is directly delivered.

topic

String

Message topic.

properties

PropertiesDTO object

Property parameter of the message delivered to the device.

status

String

Message status, including PENDING, DELIVERED, FAILED, and TIMEOUT. PENDING: The message is cached and delivered after the device goes online. DELIVERED: The message is sent successfully. FAILED: The message fails to be sent. TIMEOUT: If a message is not delivered to the device within the default period (one day), the platform sets the message status to TIMEOUT.

error_info

ErrorInfoDTO object

Message delivery error information, including error_code and error_msg. error_code includes IOTDA.014016 and IOTDA.014112. IOTDA.014016 indicates that the device is offline. IOTDA.014112 indicates that the device does not subscribe to any topic.

created_time

String

UTC time when the message was created. The value is in the format of yyyyMMdd'T'HHmmss'Z'.

finished_time

String

UTC time when the message was delivered to the device or timed out. The value is in the format of yyyyMMdd'T'HHmmss'Z'.

Table 5 PropertiesDTO

Parameter

Type

Description

correlation_data

String

Parameter description: data in the request and response modes of MQTT 5.0. This parameter is optional. You can use this parameter to configure data in the request and response modes of MQTT. Value: The value can contain a maximum of 128 characters. Only letters, digits, underscores (_), and hyphens (-) are allowed.

response_topic

String

Parameter description: response topic in the request and response modes of MQTT 5.0. This parameter is optional. You can use this parameter to configure the response topic in the request and response modes of MQTT. Value: The value can contain a maximum of 128 characters. Only letters, digits, and special characters (_-?=$#+/) are allowed.

Maximum: 128

user_properties

Array of UserPropDTO objects

Parameter description: custom property. This parameter is optional. You can use this parameter to configure custom properties. A maximum of 20 customized attributes can be configured.

Table 6 UserPropDTO

Parameter

Type

Description

prop_key

String

Parameter description: key of the custom property. Value: The value can contain a maximum of 128 characters. Only letters, digits, underscores (_), and hyphens (-) are allowed.

prop_value

String

Parameter description: value of the custom property. Value: The value can contain a maximum of 128 characters. Only letters, digits, underscores (_), and question marks (?) are allowed. '#().,& %@!-.

Table 7 ErrorInfoDTO

Parameter

Type

Description

error_code

String

Parameter description: error code, including IOTDA.014016 and IOTDA.014112. IOTDA.014016 indicates that the device is offline. IOTDA.014112 indicates that the device does not subscribe to any topic.

error_msg

String

** Parameter description**: error message. The device is offline or does not subscribe to any topic.

Example Requests

Queries all messages in a list.

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

Example Responses

Status code: 200

OK

{
  "device_id" : "d4922d8a-6c8e-4396-852c-164aefa6638f",
  "messages" : [ {
    "message_id" : "b1224afb-e9f0-4916-8220-b6bab568e888",
    "name" : "message_name",
    "message" : "string",
    "topic" : "string",
    "status" : "PENDING",
    "created_time" : "20151212T121212Z",
    "finished_time" : "20151212T121212Z"
  } ]
}

Status Codes

Status Code

Description

200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

500

Internal Server Error

Error Codes

See Error Codes.