使用该接口批量操作设备。

请求语法

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

Payload

请求参数

参数名称 类型 是否必选 描述
Cookie String 调用CreateAuthCookie接口创建的认证Cookie。
Payload JSON JSON对象,包含批量操作的动作(BulkAction)、操作对象(Things)及其相关参数。格式详情请参见表格下方Payload格式。

请求Payload格式如下所示。

{
  "BulkAction": "string"
  "Things": [
    {
      "ProductKey": "string",
      "DeviceName": "string",
      ... // Parameters for BulkAction
    }
  ]
}
表 1. Payload参数说明
参数名称 类型 是否必选 描述
BulkAction String 指定请求的批量操作。 必须是如下指定参数之一:
  • SetProperites:表示批量设置设备属性。
  • GetProperites:表示批量获取设备属性。
  • CallServices:表示批量调用设备服务。
  • Watch:表示监听设备的某一组指定事件。
Things Array JSON数组,包含操作对象及其对应的操作参数。格式详情请参见本文下方GetPropertiesSetPropertiesCallServicesWatch中请求Payload格式的Things参数。

返回语法

HTTP/1.1 StatusCode
Content-Type: ContentType

Payload

返回参数

参数名称 类型 描述
StatusCode Number HTTP状态码。返回200表示成功,返回其它状态码表示失败。状态码详情请参见状态码
ContentType String 返回消息(Payload)的类型。取决于批量操作的动作(BulkAction)。
Payload JSON 批量操作的返回结果。
{
  "Code": number,
  "Message": "success|reason for failure"
  "Data": {}
}
表 2. Payload参数说明
参数名称 类型 描述
Code Number 接口返回码。返回200表示成功,返回其它状态码表示失败。状态码详情请参见状态码
Message String 调用成功则返回success;调用失败则返回失败的原因。
Data Object 具体批量操作的返回结果。格式详情请参见本文下方GetPropertiesSetPropertiesCallServicesWatch中返回Payload格式的Data参数。

GetProperties

  • 请求Payload格式
    {
      "BulkAction": "GetProperties",
      "Things": [
        {
          "ProductKey": "string",
          "DeviceName": "string",
          "Identifiers": [ // Property Identifiers
            "string",
            "string",
            "string",
            ...
          ]
        }
      ]
    }
  • 返回Payload格式

    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
      }
    }
  • 完整示例
    $ 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

  • 请求Payload格式
    {
      "BulkAction": "SetProperties",
      "Things": [
        {
          "ProductKey": "string",
          "DeviceName": "string",
          "Properties": {
            "Identifier1": value1,
            "Identifier2": value2,
            "Identifier3": value3
        ...
          }
        }
      ]
    }
  • 返回Payload格式

    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
      }
    }
  • 完整示例
    $ 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

  • 请求Payload格式
    {
      "BulkAction": "CallServices",
      "Things": [
        {
          "ProductKey": "string",
          "DeviceName": "string",
          "Services": [
            {
              "Name": "string",
              "Args": args // Optional arguments for the service.
            }
          ]
        }
      ]
    }
  • 返回Payload格式

    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
      }
    }
  • 完整示例
    $ 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

  • 请求Payload格式
    {
      "BulkAction": "Watch",
      "Things": [
        {
          "ProductKey": "string",
          "DeviceName": "string",
          "Watches": "all|properties|events" // default is "all"
        }
      ]
    }
  • 返回Payload格式

    Content-Type:text/plain

    • 常规消息
      {
        "Code": number,
        "Message": "success|reason for failure",
        "Data": {
          "ProductKey": "string",
          "DeviceName": "string",
          "Event": "string",
          "Args": {}, // Optional arguments along with the event.
          "Timestamp": 1568010749340 
        }
      }
    • 心跳消息
      {
        "Code": 200,
        "Message": "heartbeat",
        "Data": {
        "Timestamp": 1568010749340 
        }
      }
  • 完整示例
    $ 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"}