DocsICP FilingConsole
Documentation
Home Page Link IoT Edge Support Link IoT Edge Developer Guide (Edge) Edge OpenAPI Version 2.0 BulkActions

BulkActions

Updated at:
Copy as MD
Product
My Favorites

Call this operation to perform batch operations on devices.

Request syntax

POST /2019-09-30/things/bulk HTTP/1.1
Cookie: Cookie

Payload

Request parameters

Parameter name Type Required Description
Cookie String Yes The authentication cookie created by calling the CreateAuthCookie operation.
Payload JSON Yes A JSON object that contains the batch action (BulkAction), the target objects (Things), and related parameters. For details about the format, see the Payload format section below.

The request payload has the following format.

{
  "BulkAction": "string"
  "Things": [
    {
      "ProductKey": "string",
      "DeviceName": "string",
      ... // Parameters for BulkAction
    }
  ]
}
Table 1. Payload parameters
Parameter name Type Required Description
BulkAction String Yes The batch operation for the request. Valid values:
  • SetProperties: sets device properties in a batch.
  • GetProperties: gets device properties in a batch.
  • CallServices: calls device services in a batch.
  • Watch: listens for a specified group of device events.
Things Array Yes A JSON array that contains the target objects and their operation parameters. For format details, see the Things parameter in the request payload format for GetProperties, SetProperties, CallServices, and Watch.

Return Syntax

HTTP/1.1 StatusCode
Content-Type: ContentType

Payload

Response parameters

Parameter name Type Description
StatusCode Number The HTTP status code. A value of 200 indicates success. Other values indicate failure. For more information, see Status codes.
ContentType String The type of the response message (payload). The value depends on the BulkAction.
Payload JSON The result of the batch operation. 
{
  "Code": number,
  "Message": "success|reason for failure"
  "Data": {}
}
Table 2. Payload parameters
Parameter name Type Description
Code Number The return code. A value of 200 indicates success. Other values indicate failure. For more information, see Status codes.
Message String success is returned if the call is successful. The reason for the failure is returned if the call fails.
Data Object The result of the batch operation. For format details, see the Data parameter in the response payload format for GetProperties, SetProperties, CallServices, and Watch.

GetProperties

  • Request payload format 
    {
  "BulkAction": "GetProperties",
  "Things": [
    {
      "ProductKey": "string",
      "DeviceName": "string",
      "Identifiers": [ // Property Identifiers
        "string",
        "string",
        "string",
        ...
      ]
    }
  ]
}
  • Response payload format

    Content-Type: application/json

    {
  "Code": number,
  "Message": "success|reason for failure",
  "Data": {
    "Results": [
      {
        "ProductKey": "string",
        "DeviceName": "string",
        "Returns": {
          "Message": "success|reason for failure",
          "Data": { // The properties returned from the underlying get properties call.
            "Identifier1": value1,
            "Identifier2": value2,
            "Identifier3": value3
              ...
          }
        },
      }
    ],
    "Timestamp": 1568262117344
  }
}
  • Complete example 
    $ curl -i -b token.cookie -d '{"BulkAction":"GetProperties","Things":[{"ProductKey":"a1WabAEC***","DeviceName":"N0hB9tiVWWZFMpALK***","Identifiers":["LightSwitch"]}]}' -k -X POST https://127.0.0.1:9999//2019-09-30/things/bulk

HTTP/1.1 200 OK
Server: openresty/1.13.6.2
Date: Thu, 31 Oct 2019 11:30:40 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive

{"Data":{"Results":[{"Returns":{"Message":"success","Data":{"LightSwitch":1}},"DeviceName":"N0hB9tiVWWZFMpALK***","ProductKey":"a1WabAEC***"}],"Timestamp":1572521440288},"Code":200,"Message":"success"}

SetProperties

  • Request payload format 
    {
  "BulkAction": "SetProperties",
  "Things": [
    {
      "ProductKey": "string",
      "DeviceName": "string",
      "Properties": {
        "Identifier1": value1,
        "Identifier2": value2,
        "Identifier3": value3
    ...
      }
    }
  ]
}
  • Response payload format

    Content-Type: application/json

    {
  "Code": number,
  "Message": "success|reason for failure",
  "Data": {
    "Results": [
      {
        "ProductKey": "string",
        "DeviceName": "string",
        "Returns": {
          "Message": "success|reason for failure",
          "Data": string|boolean|number|array|object // An optional data that returned from the underlying set properties call.
        },
      }
    ],
    "Timestamp": 1568262117344
  }
}
  • Complete example 
    $ curl -i -b token.cookie -d '{"BulkAction":"SetProperties","Things":[{"ProductKey":"a1WabAEC***","DeviceName":"N0hB9tiVWWZFMpALK***","Properties":{"LightSwitch":1}}]}' -k -X POST https://127.0.0.1:9999//2019-09-30/things/bulk

HTTP/1.1 200 OK
Server: openresty/1.13.6.2
Date: Thu, 31 Oct 2019 11:46:53 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive

{"Data":{"Results":[{"Returns":{"Message":"success","Data":[]},"DeviceName":"N0hB9tiVWWZFMpALK***","ProductKey":"a1WabAEC***"}],"Timestamp":1572522413633},"Code":200,"Message":"success"}

CallServices

  • Request payload format 
    {
  "BulkAction": "CallServices",
  "Things": [
    {
      "ProductKey": "string",
      "DeviceName": "string",
      "Services": [
        {
          "Name": "string",
          "Args": args // Optional arguments for the service.
        }
      ]
    }
  ]
}
  • Response payload format

    Content-Type: application/json

    {
  "Code": number,
  "Message": "success|reason for failure",
  "Data": {
    "Results": [
      {
        "ProductKey": "string",
        "DeviceName": "string",
        "Services": [
          {
            "Name": "string",
            "Returns": {
              "Message": "success|reason for failure",
              "Data": string|boolean|number|array|object // An optional data that returned from the underlying call services call.
            }
          }
        ],
      }
    ],
    "Timestamp": 1568262117344
  }
}
  • Complete example 
    $ curl -i -b token.cookie -d '{"BulkAction":"CallServices","Things":[{"ProductKey":"a1WabAEC***","DeviceName":"N0hB9tiVWWZFMpALK***","Services":[{"Name":"setColor","Args":{"color":"red"}}]}]}' -k -X POST https://127.0.0.1:9999//2019-09-30/things/bulk

HTTP/1.1 200 OK
Server: openresty/1.13.6.2
Date: Thu, 31 Oct 2019 11:52:13 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive

{"Data":{"Results":[{"Services":[{"Name":"setColor","Returns":{"Message":"success","Data":[]}}],"DeviceName":"N0hB9tiVWWZFMpALK***","ProductKey":"a1WabAEC***"}],"Timestamp":1572522733310},"Code":200,"Message":"success"}

Watch

  • Request payload format 
    {
  "BulkAction": "Watch",
  "Things": [
    {
      "ProductKey": "string",
      "DeviceName": "string",
      "Watches": "all|properties|events" // default is "all"
    }
  ]
}
  • Response payload format

    Content-Type: text/plain

    • Regular message 
      {
  "Code": number,
  "Message": "success|reason for failure",
  "Data": {
    "ProductKey": "string",
    "DeviceName": "string",
    "Event": "string",
    "Args": {}, // Optional arguments along with the event.
    "Timestamp": 1568010749340 
  }
}
    • Heartbeat message 
      {
  "Code": 200,
  "Message": "heartbeat",
  "Data": {
  "Timestamp": 1568010749340 
  }
}
  • Complete example 
    $ curl -b token.cookie -d '{"BulkAction":"Watch","Things":[]}' -k -X POST https://127.0.0.1:9999//2019-09-30/things/bulk

{"Data":{"Timestamp":1572510704112,"Event":"propertiesChanged","ProductKey":"a1t9b6Nn***","Args":{"MeasuredIlluminance":{"time":1572510704110,"value":400}},"DeviceName":"GjCb9LKXgcKXeluGJ***"},"Code":200,"Message":"success"}
{"Data":{"Timestamp":1572510706116,"Event":"propertiesChanged","ProductKey":"a1t9b6Nn***","Args":{"MeasuredIlluminance":{"time":1572510706114,"value":300}},"DeviceName":"GjCb9LKXgcKXeluGJ***"},"Code":200,"Message":"success"}
{"Data":{"Timestamp":1572510706117},"Code":200,"Message":"heartbeat"}
{"Data":{"Timestamp":1572510708119,"Event":"propertiesChanged","ProductKey":"a1t9b6Nn***","Args":{"MeasuredIlluminance":{"time":1572510708118,"value":200}},"DeviceName":"GjCb9LKXgcKXeluGJ***"},"Code":200,"Message":"success"}
Previous：CallThingServicesNext：InvokeFunction