Example 2: Delivering a Message to a Specific Device

Scenarios

This topic describes how to deliver messages to a specific device using APIs. For details about how to call APIs, see Calling APIs.

Involved APIs

• Query the Device List: Determine the device to which a message is to be delivered.
• Deliver a Message to a Device: Deliver the message to the specified device.
• Query a Message by Message ID: Confirm the message delivery result.

Procedure

1. Determine the device to which a message is to be delivered.
   1. Query the device list
      • API

        URL: GET /v5/iot/{project_id}/devices

        For details, see Query the Device List.

      • Example request

        GET https://{Endpoint}/v5/iot/{project_id}/devices?product_id={product_id}&gateway_id={gateway_id}&is_cascade_query={is_cascade_query}&node_id={node_id}&device_name={device_name}&limit={limit}&marker={marker}&offset={offset}&start_time={start_time}&end_time={end_time}&app_id={app_id}
        Content-Type: application/json
        X-Auth-Token: ********
        Instance-Id: ********

      • Example response

        Status Code: 200 OK

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

   2. Select a device based on project requirements and record the value of device_id.

2. Deliver the message to the device specified in 1.
   1. Deliver a message.
      • API

        URL: POST /v5/iot/{project_id}/devices/{device_id}/messages

        For details, see Deliver a Message to a Device.

      • Example request

        POST https://{Endpoint}/v5/iot/{project_id}/devices/{device_id}/messages
        Content-Type: application/json
        X-Auth-Token: ********
        Instance-Id: ********
        
        {
          "message_id" : "99b32da9-cd17-4cdf-a286-f6e849cbc364",
          "name" : "messageName",
          "message" : "HelloWorld",
          "topic" : "messageDown"
        }

      • Example response

        Status Code: 201 Created

        Content-Type: application/json
        
        {
          "message_id" : "b1224afb-e9f0-4916-8220-b6bab568e888",
          "result" : {
            "status" : "PENDING",
            "created_time" : "20151212T121212Z",
            "finished_time" : "20151212T121213Z"
          }
        }

   2. Record the value of message_id in the response.

3. Confirm the message delivery result.
   1. Query the message with message_id obtained in 2.b.
      • API

        URL: GET /v5/iot/{project_id}/devices/{device_id}/messages/{message_id}

        For details, see Query a Message by Message ID.

      • Example request

        GET https://{Endpoint}/v5/iot/{project_id}/devices/{device_id}/messages/{message_id}
        Content-Type: application/json
        X-Auth-Token: ********
        Instance-Id: ********

      • Example response

        Status Code: 200 OK

        Content-Type: application/json
        
        {
          "message_id" : "b1224afb-e9f0-4916-8220-b6bab568e888",
          "name" : "message_name",
          "message" : "string",
          "topic" : "string",
          "status" : "PENDING",
          "created_time" : "20151212T121212Z",
          "finished_time" : "20151212T121212Z"
        }

   2. Check the message delivery result based on the value of status in the response.