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

Push a Device Message Status Change Notification

Function

After the application calls the API for creating a rule triggering condition (resource is set to device.message.status and event to update), the API for creating a rule action, and the API for modifying a rule triggering condition, and activates a rule, the platform pushes the result to the server specified by the rule when the device message status changes.

URI

POST /HTTP URL determined when the application creates a device message status change notification rule. The AMQP channel does not require the URL.

Request Parameters

Table 1 Request body parameters

Parameter

Mandatory

Type

Description

resource

Yes

String

Parameter description: subscribed resource name. Set this parameter to device.message.status.

event

Yes

String

Parameter description: subscribed event. Set this parameter to update.

event_time

Yes

String

Parameter description: UTC time when the resource event was generated. The value is in the format of yyyyMMdd'T'HHmmss'Z', for example, 20151212T121212Z. If necessary, convert the time to display in the local time zone format.

event_time_ms

No

String

Parameter description: UTC time when a resource event was generated. The value in the format of yyyy-MM-dd'T'HH:mm:ss.SSS'Z', for example, 2015-12-12T12:12:12.000Z. If necessary, convert the time to display in the local time zone format.

request_id

No

String

Parameter description: message ID, which is specified by the device or generated by the platform, and is used to trace the service process.

notify_data

Yes

DeviceMessageStatusUpdateNotifyDataV5 object

Parameter description: message to push.

Table 2 DeviceMessageStatusUpdateNotifyDataV5

Parameter

Mandatory

Type

Description

header

Yes

NotifyDataHeader object

Parameter description: message header.

body

Yes

DeviceMessageStatusUpdate object

Parameter description: message body.

Table 3 NotifyDataHeader

Parameter

Mandatory

Type

Description

app_id

No

String

Parameter description: application ID.

Maximum: 256

device_id

No

String

Parameter description: unique device ID, which is allocated by IoTDA during device registration.

Maximum: 256

node_id

No

String

Parameter description: device node ID. This parameter is set to the IMEI, MAC address, or serial number.

Maximum: 256

product_id

No

String

Parameter description: unique product ID, which is allocated by the platform during product registration.

Maximum: 256

gateway_id

No

String

Parameter description: gateway ID, which uniquely identifies a gateway. The gateway ID is the same as the device ID if the device is a directly connected device. If the device is an indirectly connected device, the gateway ID is the device ID of the directly connected device (that is, the gateway) with which it associates.

Maximum: 256

tags

No

Array of TagV5DTO objects

Parameter description: list of tags to be bound to a specific resource. Each tag key must be unique in the tag list. Up to 10 tags can be bound to a resource.

Table 4 TagV5DTO

Parameter

Mandatory

Type

Description

tag_key

Yes

String

Parameter description: tag key, which is unique for a resource. If the specified key already exists, the value of the existing tag is overwritten. If the specified key does not exist, a new tag is added.

tag_value

No

String

Parameter description: tag value.

Table 5 DeviceMessageStatusUpdate

Parameter

Mandatory

Type

Description

topic

No

String

Parameter description: MQTT topic used for message reporting.

message_id

Yes

String

Parameter description: sequence number of a message, which uniquely identifies a message.

name

No

String

Parameter description: message name.

status

No

String

Parameter description: device message status. Options: PENDING, DELIVERED, TIMEOUT, and FAILED.

error_info

No

ErrorInfoDTO object

Parameter description: message delivery failure information.

timestamp

No

String

Parameter description: UTC when the message was updated. The value is in the format of yyyyMMdd'T'HHmmss'Z', for example, 20151212T121212Z.

Table 6 ErrorInfoDTO

Parameter

Mandatory

Type

Description

error_code

No

String

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

error_msg

No

String

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

Response Parameters

None

Example Requests

Example of a device message status change notification.

Device message status change notification.

{
  "resource" : "device.message.status",
  "event" : "update",
  "event_time" : "20151212T121212Z",
  "event_time_ms" : "2015-12-12T12:12:12.000Z",
  "request_id" : "3fe58d5e-8697-4849-a165-7db128f7e776",
  "notify_data" : {
    "header" : {
      "device_id" : "d4922d8a-6c8e-4396-852c-164aefa6638f",
      "product_id" : "ABC123456789",
      "app_id" : "d4922d8a-6c8e-4396-852c-164aefa6638f",
      "gateway_id" : "d4922d8a-6c8e-4396-852c-164aefa6638f",
      "node_id" : "ABC123456789",
      "tags" : [ {
        "tag_value" : "testTagValue",
        "tag_key" : "testTagName"
      } ]
    }
  },
  "body" : {
    "error_info" : {
      "error_msg" : "Send to device failed, device not subscribe topic.",
      "error_code" : "IOTDA.014112"
    },
    "name" : "name",
    "topic" : "topic",
    "message_id" : "1235",
    "status" : "DELIVERED",
    "timestamp" : "20151212T121212Z"
  }
}

Example Responses

None

Status Codes

Status Code

Description

200

OK

Error Codes

See Error Codes.