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

{
  "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"
  } ]
}