开发者中心

设备控制

设备控制接口由三部分组成:

  • 设备控制API 资源将URI和URI模板返回到操作集合, 以便可以按照各种标准查询操作。
  • 操作集合资源检索操作并启用创建新操作。
  • 操作资源表示可以查询和修改的各个操作。

为了创建/检索/更新设备的操作, 设备必须在现有agent的"childDevices"层次结构中。 要在设备清单清单中创建agent, 您应该创建一个带有片段"com_cumulocity_model_Agent"的托管对象。

注意: 所有的PUT/POST请求必须设置accept头, 否则会返回空的应答正文。

设备控制API

设备控制API [application/vnd.com.nsn.cumulocity.devicecontrolApi+json]
名称 类型 次数 描述
self URL 1 资源链接。
operations OperationCollection 1 所有操作集合。
operationsByStatus OperationCollection URI template 1 处于特定状态的所有操作的只读集合 (占位符 {status}, 允许的值请参阅下面的操作介质类型)。
operationsByAgentId OperationCollection URI template 1 针对特定agent的所有操作的只读集合 (占位符 {agentId}, 代理的唯一ID)。
operationsByAgentIdAndStatus OperationCollection URI template 1 针对特定agent和状态的所有操作的只读集合 (占位符 {agentId} 和 {status})。
operationsByDeviceId OperationCollection URI template 1 在特定设备上执行的所有操作的只读集合 (占位符 {deviceId} 设备的唯一ID)。
operationsByDeviceIdAndStatus OperationCollection URI template 1 特定状态下所有操作的只读集合, 应在特定设备上执行 (占位符 {deviceId} 和 {status})。
GET - 查询设备控制API资源

应答正文: 设备控制Api

所需角色: ROLE_DEVICE_CONTROL_READ

请求示例:

GET /devicecontrol
                      Host: ...
                      Authorization: Basic ...
                    

应答示例:

HTTP/1.1 200 OK
                      Content-Type: application/vnd.com.nsn.cumulocity.devicecontrolApi+json;ver=...
                      Content-Length: ...
                      {
                      "self" : "<<DeviceControl API URL>>",
                      "operations" : { "self" :"<<OperationsCollection URL>>" },
                      "operationsByStatus" : "<<OperationsCollection URL>>?status={status}",
                      "operationsByAgentId" : "<<OperationsCollection URL>>?agentId={agentId}",
                      "operationsByAgentIdAndStatus" : "<<OperationsCollection URL>>?agentId={agentId}&status={status}",
                      "operationsByDeviceId" : "<<OperationsCollection URL>>?deviceId={deviceId}"
                      "operationsByDeviceIdAndStatus" : "<<OperationsCollection URL>>?deviceId={deviceId}&status={status}"
                    }
                  

操作集合

操作集合 [application/vnd.com.nsn.cumulocity.operationCollection+json]
名称 类型 次数 描述
self URL 1 资源链接。
operations Operations 0..n 操作列表, 如下所示。
statistics PagingStatistics 1 分页统计信息。
prev URI 0..1 上一页链接。
next URI 0..1 下一页链接。

有关操作集合的注意事项:

  • 仅当使用"agentId"参数查询时,嵌入式操作对象才包含"deviceExternalIDs"。
  • 嵌入式操作对象用"deviceName"填充, 但仅在请求操作集合时。
  • 操作按创建顺序返回(FIFO队列).
POST - 创建操作

请求正文: 操作

应答正文: 操作

所需角色: ROLE_DEVICE_CONTROL_ADMIN 或源对象所有者

请求示例:

POST /devicecontrol/operations/
                    Content-Type: application/vnd.com.nsn.cumulocity.operation+json;ver=...
                    Accept: application/vnd.com.nsn.cumulocity.operation+json;ver=...
                    Authorization: Basic ...
                    {
                    "deviceId" : "1234",
                    "com_cumulocity_model_WebCamDevice": {
                    "name": "take picture",
                    "parameters": {
                    "duration": "5s",
                    "quality": "HD"
                  }
                }
              }
            

应答示例:

HTTP/1.1 201 Created
              Location: <<URL of new operation>>
              Content-Type: application/vnd.com.nsn.cumulocity.operation+json;ver=...
              Content-Length: ...
              {
              "id" : "123",
              "self" : "<<URL of new operation>>",
              "deviceId" : "1234",
              "status" : "PENDING",
              "creationTime" : "2011-09-06T12:03:27.927+02:00",
              "com_cumulocity_model_WebCamDevice" : {
              "name" : "take picture",
              "parameters" : {
              "duration" : "5s",
              "quality" : "HD"
            }
          }
        }
      
Get - 查询操作集合

响应正文: 操作集合

所需角色: ROLE_DEVICE_CONTROL_READ

请求示例: 查询所有操作。

GET /devicecontrol/operations
        Accept: application/vnd.com.nsn.cumulocity.operationCollection+json;ver=...
        Authorization: Basic ...
      

应答示例:

HTTP/1.1 200 OK
        Content-Type: application/vnd.com.nsn.cumulocity.operationCollection+json;ver=...
        Content-Length: ...
        {
        "self" : "<<This OperationCollection URL>>",
        "operations" : [
        {
        "id" : "123",
        "self" : "<<This Operation URL>>",
        "deviceId" : "1234",
        "deviceName" : "WebCamDevice",
        "status" : "PENDING",
        "creationTime" : "2011-09-06T12:03:27.927Z",
        "com_cumulocity_model_WebCamDevice" : {
        "name" : "take picture",
        "parameters" : {
        "duration" : "5s",
        "quality" : "HD"
      }
    }
  },
  {
  "id" : "124",
  "self" : "<<This Operation URL>>",
  "deviceId" : "1234",
  "deviceName" : "DiscreteStateDevice",
  "status" : "PENDING",
  "creationTime" : "2011-09-06T12:03:27.927Z",
  "com_cumulocity_model_DiscreteStateDevice" : {
  "state" : "off"
}
}
],
"statistics" : {
"pageSize" : 5,
"currentPage : 1
}
}
DELETE - 删除操作集合

DELETE方法允许删除操作集合。 适用的查询参数等同于GET方法。

请求正文: N/A

应答正文: N/A

所需角色: ROLE_DEVICE_CONTROL_ADMIN

请求示例:

 DELETE: /devicecontrol/operations ....
 Host: ...
 Authorization: Basic ...

应答示例:

HTTP/1.1  204 NO CONTENT

操作

操作 [application/vnd.com.nsn.cumulocity.operation+json]
名称 类型 次数 描述 PUT/POST
id String 1 唯一标识操作。
self URI 1 此资源链接。 No
creationTime String 1 在数据库中创建操作的时间。
deviceID String 1 标识应在其上执行此操作的目标设备。 POST: 必选 PUT: 否
deviceExternalIDs ExternalIDCollection 0..n 目标设备的外部ID, 参见身份标识接口。
bulkOperationId String 1 批量操作Id引用, 如果此操作是批量操作计划生成
status String 1 操作状态, 可以是 SUCCESSFUL, FAILED, EXECUTING 或 PENDING中的一种。 POST: 否 PUT: 必选
failureReason String 0..1 失败原因。
* Object 1..n 描述将在设备上执行的操作的其他属性。 POST: 必选 PUT: 否

嵌入在"deviceExternalIDs"集合中的"ExternalID"包含属性"type"和"externalId"。

PUT - 更新操作

请求正文: 操作

应答正文: n/a.

所需角色: ROLE_DEVICE_CONTROL_ADMIN 或源对象所有者

请求示例:

PUT /devicecontrol/operations/<<operationId>>
  Host: ...
  Authorization: Basic ...
  Content-Length: ...
  Content-Type: application/vnd.com.nsn.cumulocity.operation+json;ver=...
  { 
  "status" : "SUCCESSFUL"
}
GET - 查询操作

应答正文: 操作

所需角色: ROLE_DEVICE_CONTROL_READ

请求示例:

GET /devicecontrol/operations/<<operationId>>
  Host: ...
  Authorization: Basic ... 
  Accept: application/vnd.com.nsn.cumulocity.operation+json;ver=...

应答示例:

HTTP/1.1 200 OK
  Content-Type: application/vnd.com.nsn.cumulocity.operation+json;ver=...
  Content-Length: ...
  {
  "id" : "123",
  "self" : "<<This Operation URL>>",
  "deviceId" : "1243",
  "status" : "PENDING",
  "creationTime" : "2011-09-06T12:03:27.927+02:00",
  "com_cumulocity_model_WebCamDevice" : {
  "name" : "take picture",
  "parameters" : {
  "duration" : "5s",
  "quality" : "HD"
}
}
}

通过SMS控制设备

为了通过SMS发送操作, 设备托管对象应包含片段:

    "c8y_CommunicationMode": {
  "mode": "SMS"
}

或者操作应该包含属性:

    "deliveryType": "SMS"

通知

有两个选项可用于接收设备控制API的实时通知。 接收通知的基本协议参见"实时通知"。

接收agent的操作

实时通知允许agent几乎立即接收针对其的新操作。 对于控制相关通知,请使用URL

/devicecontrol/notifications
  

订阅通道需要包含要接收其操作的agent的托管对象ID:

/<<agentId>>
  

例如, 要订阅关于为ID为"5"的agent程序创建的新操作的通知, 订阅通道应为以下字符串:

/5
  

所需角色: ROLE_DEVICE_CONTROL_READ

接收设备的操作

该端点不仅返回新创建的操作, 而且返回设备操作的所有更新(包括删除)。URL是

/cep/realtime
  

订阅频道需要包含设备的托管对象ID或作为占位符的"*", 以接收所有设备的通知

/operations/<<deviceId>>
  

应答将附加到操作对象包含"realtimeAction"以标识哪个动作导致给定对象(CREATE, UPDATE 或 DELETE)。 在删除的情况下, 数据将仅包含已删除操作的ID。

应答示例:

HTTP/1.1 200 OK 
    Content-Type: application/json
    [
    {
    "channel": "/operations/12345", 
    "successful": true, 
    "error": "", 
    "data": [{
    "realtimeAction": "CREATE",
    "data": {
    "id": "1",
    "deviceId": "12345",
    "self": "...",
    "creationTime": "2011-09-06T12:03:27.927+02:00",
    "status": "PENDING",
    "time": "2011-09-06T12:03:27.845+02:00",
    "description": "Deactivate motion tracking",
    "c8y_MotionTracking": { ... }
  }
}], 
"clientId": "Un1q31d3nt1f13r" 
}
]

所需角色: ROLE_DEVICE_CONTROL_READ

批量操作集合

批量操作集合 [application/vnd.com.nsn.cumulocity.bulkOperationCollection+json]
名称 类型 次数 描述
self URL 1 此资源链接。
bulkOperations Operations 0..n 批量操作列表, 如下所示。
statistics PagingStatistics 1 分页统计信息。
prev URI 0..1 上一页链接。
next URI 0..1 下一页链接。
POST - 创建批量操作

请求正文: 批量操作

应答正文: 批量操作

所需角色: ROLE_BULK_OPERATION_ADMIN

请求示例:

POST /devicecontrol/bulkoperations
  Content-Type: application/vnd.com.nsn.cumulocity.bulkOperation+json
  Accept: application/vnd.com.nsn.cumulocity.bulkOperation+json
  Authorization: Basic ...
  {
  "operationPrototype":{"test"=>"TEST1"},
  "creationRamp":45,
  "groupId":"10205",
  "startDate":"2015-05-01T22:21:22"
}

应答示例:

HTTP/1.1 201 Created
  Location: <<URL of new operation>>
  Content-Type: application/vnd.com.nsn.cumulocity.bulkOperation+json

  {
  "id":2,
  "self":"https://dev.cumulocity.com/devicecontrol/bulkoperations/2",
  "operationPrototype":{"test"=>"TEST1"},
  "creationRamp":45,
  "groupId":"10205",
  "startDate":"2015-05-01T22:21:22"
  "progress":
  {
  "pending":0, "failed":0, "executing":0, "successful":0, "all":1
},
"status":"ACTIVE"
}
GET - 查询批量操作集合

请求正文: N/A

应答正文: 批量操作集合

所需角色: ROLE_BULK_OPERATION_READ

请求示例: 查询所有批量操作集合。

GET /devicecontrol/bulkoperations
  Accept: application/vnd.com.nsn.cumulocity.bulkOperationCollection+json
  Authorization: Basic ...

应答示例:

HTTP/1.1 200 OK
  Content-Type: application/vnd.com.nsn.cumulocity.bulkOperationCollection+json
  Content-Length: ...
  {
  "self" : "<<This BulkOperationCollection URL>>",
  "bulkOperations" : [
  {
  "id":2,
  "self":"https://dev.cumulocity.com/devicecontrol/bulkoperations/2",
  "operationPrototype":{
  "description": "Restart device",
  "c8y_Restart": {}
},
"creationRamp":45,
"groupId":"10205",
"startDate":"2015-05-01T22:21:22"
"progress":
{
  "pending":0, "failed":0, "executing":0, "successful":0, "all":1
},
"status":"ACTIVE",
},
{
 "id":3,
 "self":"https://dev.cumulocity.com/devicecontrol/bulkoperations/3",
 "operationPrototype":{
 "description": "Send Command",
 "c8y_Command": {
 "text": "Do something"
}
},
"creationRamp":15,
"groupId":"10201",
"startDate":"2015-05-05T22:21:22"
"progress":
{
  "pending":0, "failed":0, "executing":0, "successful":0, "all":5
},
"status":"ACTIVE",
}
],
"statistics" : {
"pageSize" : 5,
"currentPage : 1
}
}

默认情况下, 查询批量操作端点不返回CANCELED操作。 可以通过添加额外的查询参数将其包含在应答中: withDeleted=true。

批量操作

批量操作API允许调度要在指定时间执行的一组设备上的操作。 需要指定每次操作创建之间的延迟。 创建批量操作时, 它处于ACTIVE状态。 创建所有操作后, 批量操作状态为COMPLETED。

创建批量操作时, 可以以两种模式运行:

  • 当传递groupId时, 它以标准方式工作, 即从群组中获取设备并对其上的操作进行调度
  • 当传递failedBulkOperationId时, 它将通过该id进行已经处理的批量操作, 并调度以前操作失败的设备上的操作

禁止同时传递groupId和failedBulkOperationId。

批量操作API需要与标准设备控制API不同的角色。 这些新角色是: BULK_OPERATION_READ和BULK_OPERATION_ADMIN。

批量操作 [application/vnd.com.nsn.cumulocity.bulkOperation+json]
名称 类型 次数 描述 PUT/POST
id String 1 唯一标识操作。
self URI 1 资源链接。
groupId String 1 标识应在其上执行此操作的目标组。 POST: 否 PUT: 否
failedBulkOperationId String 1 标识应该重新计划失败操作的失败批量操作。 POST: 否 PUT: 否
startDate String 1 应该创建操作的时间。 POST: 必选 PUT: 否
creationRamp Number 1 每次操作创建之间的延迟。 POST: 必选 PUT: 否
operationPrototype OperationRepresentation 1 要为组中的每个设备执行的操作。 POST: 必选 PUT: 否
status String 1 批量操作的状态。 可能的值: ACTIVE, COMPLETED, DELETED
progress BulkOperationProgressRepresentation 1 包含已处理操作数的信息。
PUT - 更新批量操作

对已启动的批量操作进行更新会将其取消, 并创建/计划新的批量操作。

请求正文: 批量操作

应答正文: n/a.

所需角色: ROLE_BULK_OPERATION_ADMIN

请求示例:

PUT /devicecontrol/bulkoperations/<<bulkoperationId>>
    Host: ...
    Authorization: Basic ...
    Content-Type: application/vnd.com.nsn.cumulocity.bulkoperation+json
    { 
    "creationRamp" : 15
  }

应答示例:

HTTP/1.1 200 OK
  Content-Type: application/vnd.com.nsn.cumulocity.bulkoperation+json

  {
  "id" : "123",
  "self" : "<<This BulkOperation URL>>",
  "groupId" : "124301",
  "status" : "ACTIVE",
  "startDate" : "2011-09-06T12:03:27",
  "operationPrototype":{
  "description": "Restart device",
  "c8y_Restart": {}
},
"creationRamp":15,
"progress":
{
 "pending":0, "failed":0, "executing":0, "successful":0, "all":2
}
}
GET - 查询批量操作

应答正文: 批量操作

所需角色: ROLE_BULK_OPERATION_READ

请求示例:

GET /devicecontrol/bulkoperations/<<bulkoperationId>>
  Host: ...
  Authorization: Basic ...
  Accept: application/vnd.com.nsn.cumulocity.bulkoperation+json;ver=...

应答示例:

HTTP/1.1 200 OK
  Content-Type: application/vnd.com.nsn.cumulocity.bulkoperation+json

  {
  "id" : "123",
  "self" : "<<This BulkOperation URL>>",
  "groupId" : "124301",
  "status" : "ACTIVE",
  "startDate" : "2011-09-06T12:03:27",
  "operationPrototype":{
  "description": "Restart device",
  "c8y_Restart": {}
},
"creationRamp":15,
"progress":
{
 "pending":0, "failed":0, "executing":0, "successful":0, "all":2
}
}
DELETE - 删除批量操作

请求正文: N/A.

应答正文: N/A.

所需角色: ROLE_BULK_OPERATION_ADMIN

请求视力: Delete a Bulk Operation

DELETE /devicecontrol/bulkoperations/<<id>>
  Authorization: Basic ...

应答示例:

HTTP/1.1  204 NO CONTENT