BulkActions-Link IoT Edge(IoT Edge)-阿里云帮助中心

This API performs batch operations on devices.

Request syntax

POST /2020-04-30/things/bulk HTTP/1.1
Cookie: Cookie

Payload

Important 2020-04-30 is the version number of the edge OpenAPI. This value cannot be changed.

Request parameters

Parameter name	Type	Required	Description
Cookie	String	Yes	The authentication cookie that is 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 description that follows this table.

The request Payload is in 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 to perform. This parameter must be one of the following values: SetProperties: sets device properties in batches. GetProperties: gets device properties in batches. CallServices: calls device services in batches. Watch: gets a specified group of events for devices.
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 Payloads for GetProperties, SetProperties, CallServices, and Watch later in this topic.

Response syntax

HTTP/1.1 StatusCode
Content-Type: ContentType

Payload

Response parameters

Parameter name	Type	Description
StatusCode	Number	The HTTP status code. A status code of 200 indicates a successful call. Other status codes indicate a failed call. For more information about status codes, see Status codes.
ContentType	String	The type of the response message (Payload). The value depends on the BulkAction parameter.
Payload	JSON	The result of the batch operation.

The response Payload is in the following format.

{
  "Data": {}
}

Table 2. Payload parameters
Parameter	Type	Description
Data	Object	The result of the batch operation. For format details, see the Data parameter in the response Payloads for GetProperties, SetProperties, CallServices, and Watch later in this topic.

GetProperties

Request Payload format

{
  "BulkAction": "GetProperties",
  "Things": [
    {
      "ProductKey": "string",
      "DeviceName": "string",
      "Identifiers": [ // Property Identifiers
        "string",
        "string",
        "string",
        ...
      ]
    }
  ]
}

Response Payload format

Content-Type: application/json

{  
  "Data": {
    "Results": [
      {
        "ProductKey": "string",
        "DeviceName": "string",
        "Returns": {
          "Code": "string", // Error code
          "Message": "reason for failure", // Reason for failure
          "Data": { // The properties returned from the underlying get properties call.
            "Identifier1": value1,
            "Identifier2": value2,
            "Identifier3": value3
              ...
          }
        },
      }
    ],
    "Timestamp": 1568262117344
  }
}

Example

$ curl -i -b token.cookie -d '{"BulkAction":"GetProperties","Things":[{"ProductKey":"a1W****CGHU","DeviceName":"N0hB9tiVWWZF****KHgs","Identifiers":["LightSwitch"]}]}' -k -X POST https://127.0.0.1:9999/2020-04-30/things/bulk

HTTP/1.1 200 OK
Server: openresty/1.13.6.2
Date: Wed, 22 Apr 2020 17:41:04 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive

{"Data":{"Results":[{"Returns":{"Data":{"LightSwitch":0}},"DeviceName":"N0hB9tiVWWZF****KHgs","ProductKey":"a1W****CGHU"}],"Timestamp":1587577264304}}

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

{
  "Data": {
    "Results": [
      {
        "ProductKey": "string",
        "DeviceName": "string",
        "Returns": {
          "Code": "string", // Error code
          "Message": "reason for failure", // Reason for failure
          "Data": string|boolean|number|array|object // Optional data returned from the underlying set properties call.
        },
      }
    ],
    "Timestamp": 1568262117344
  }
}

Example

curl -i -b token.cookie -d '{"BulkAction":"SetProperties","Things":[{"ProductKey":"a1W****CGHU","DeviceName":"N0hB9tiVWWZF****KHgs","Properties":{"LightSwitch":1}}]}' -k -X POST https://127.0.0.1:9999/2020-04-30/things/bulk

HTTP/1.1 200 OK
Server: openresty/1.13.6.2
Date: Wed, 22 Apr 2020 17:44:21 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive

{"Data":{"Results":[{"Returns":{"Data":[]},"DeviceName":"N0hB9tiVWWZF****KHgs","ProductKey":"a1W****CGHU"}],"Timestamp":1587577461238}}

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

{ 
  "Data": {
    "Results": [
      {
        "ProductKey": "string",
        "DeviceName": "string",
        "Services": [
          {
            "Name": "string",
            "Returns": {
              "Code": "string", // Error code
              "Message": "reason for failure", // Reason for failure
              "Data": string|boolean|number|array|object // Optional data returned from the underlying call services call.
            }
          }
        ],
      }
    ],
    "Timestamp": 1568262117344
  }
}

Example

curl -i -b token.cookie -d '{"BulkAction":"CallServices","Things":[{"ProductKey":"a1W****CGHU","DeviceName":"N0hB9tiVWWZF****KHgs","Services":[{"Name":"setColor","Args":{"color":"red"}}]}]}' -k -X POST https://127.0.0.1:9999//2020-04-30/things/bulk

HTTP/1.1 200 OK
Server: openresty/1.13.6.2
Date: Wed, 22 Apr 2020 17:47:02 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive

{"Data":{"Results":[{"Services":[{"Name":"setColor","Returns":{"Data":[]}}],"DeviceName":"N0hB9tiVWWZF****KHgs","ProductKey":"a1W****CGHU"}],"Timestamp":1587577622555}}

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

Normal message

{
  "Message": "success",
  "Data": {
    "ProductKey": "string",
    "DeviceName": "string",
    "Event": "string",
    "Args": {}, // Optional arguments along with the event.
    "Timestamp": 1568010749340 
  }
}

Heartbeat message

{
  "Message": "heartbeat",
  "Data": {
    "Timestamp": 1568010749340 
  }
}

Example

$ curl -b token.cookie -d '{"BulkAction":"Watch","Things":[]}' -k -X POST https://127.0.0.1:9999//2020-04-30/things/bulk

{"Message":"success","Data":{"Timestamp":1587577766731,"Event":"propertiesChanged","ProductKey":"a1t9b******","Args":{"MeasuredIlluminance":{"time":1587577766729,"value":200}},"DeviceName":"GjCb9LKXgcKXel******"}}
{"Message":"heartbeat","Data":{"Timestamp":1587577767732}}
{"Message":"success","Data":{"Timestamp":1587577768734,"Event":"propertiesChanged","ProductKey":"a1t9b******","Args":{"MeasuredIlluminance":{"time":1587577768733,"value":100}},"DeviceName":"GjCb9LKXgcKXel******"}}