开发者中心

设备清单

设备清单界面由以下部分组成:

  • inventory API 资源将URI和URI模板返回到托管对象的集合,以便可以查询所有对象,特定类型的所有对象和具有特定功能的所有对象。
  • managed object collection 资源检索托管对象集,并允许创建新的托管对象。
  • managed object * 资源代表可以查询和删除的单个托管对象。
  • managed object reference collection 资源检索对托管对象的引用集。 这些可以是,例如,特定托管对象的子设备。 它还允许向集合添加新引用(例如,添加新的子设备)。
  • managed object reference resource代表对托管对象的一个单独引用,可以检索或删除。

请注意,对于所有PUT / POST请求,应提供ACCEPT标头(Header),否则将返回空应答正文。.

设备清单API

InventoryAPI [application/vnd.com.nsn.cumulocity.inventoryApi+json]
名字 类型 出现次数 描述
self URL 1 此资源的链接。
managedObjects ManagedObjectCollection 1 所有托管对象的集合。
managedObjectsForType ManagedObjectCollection URI-Template 1 所有特定类型的托管对象(占位符{type})的只读集合。
managedObjectsForFragmentType ManagedObjectCollection URI-Template 1 具有特定片段类型或能力(占位符{fragmentType})的所有托管对象的只读集合。
managedObjectsForListOfIds ManagedObjectCollection URI-Template 1 为给定的ids列表(占位符{ids})提取的托管对象的只读集合,例如"?ids = 41,43,68"。
managedObjectsForText ManagedObjectCollection URI-Template 1 包含从给定文本开始的文本值(占位符{text})的托管对象的只读集合。 文本值是以拉丁字母(A-Z或a-z)开头的任何字母数字字符串。
GET Inventory API资源的内容表示

应答正文(body): application/vnd.com.nsn.cumulocity.inventoryApi+json
需要角色权限: ROLE_INVENTORY_READ

请求示例: Get Inventory API资源


                    GET /inventory
                    Host: ...
                    Authorization: Basic ...
                  

应答示例:


    HTTP/1.1 200 OK
    Content-Type: application/vnd.com.nsn.cumulocity.inventoryApi+json;ver=...
    Content-Length: ...
    {
    "self" : "<<InventoryAPI URL>>",
    "managedObjects" : {
    "self" : "<<ManagedObjectCollection URL>>"
      },
      "managedObjectsForType" : "<<ManagedObjectCollection URL>>?type={type}",
      "managedObjectsForFragmentType" : "<<ManagedObjectCollection URL>>?fragmentType={fragmentType}",
      "managedObjectsForListOfIds" : "<<ManagedObjectCollection URL>>?ids={ids}",
      "managedObjectsForText" : "<<ManagedObjectCollection URL>>?text={text}"
    }
              

托管对象集合

ManagedObjectCollection [application/vnd.com.nsn.cumulocity.managedObjectCollection+json]
名字 类型 出现次数 描述
self URI 1 指向这个资源的链接。
managedObjects ManagedObject 0..n 托管对象列表,如下所示。
statistics PagingStatistics 1 关于分页统计的信息。
prev URI 0..1 指向可能的托管对象的前一页的链接。
next URI 0..1 指向可能的托管对象的后一页的链接。
GET ManagedObjectCollection的内容表示

应答正文(body): ManagedObjectCollection

需要角色权限: ROLE_INVENTORY_READ

请求示例: Get特定类型的托管对象


    GET /inventory/managedObjects
    Host: ...
    Authorization: Basic ...
    Accept: application/vnd.com.nsn.cumulocity.managedObjectCollection+json;ver=...
              

应答示例:

HTTP/1.1 200 OK
                Content-Type: application/vnd.com.nsn.cumulocity.managedObjectCollection+json;ver=...
                Content-Length: ...
                {
                "self" : "<<Collection URL>>",
                "managedObjects" : [
                {
                "self" : "<<Object 42 URL>>",
                "id" : "42",
                "type" :"bg_mps_D413",
                "name" : "Meter1",
                ...
              },
              {
              "self" : "<<Object 43 URL>>",
              "id": "43",
              "type" :"bg_mps_D413",
              "name": "Meter2",
              ...
            }
            ],
            "statistics" : {
            "totalPages" : 42,
            "pageSize" : 5,
            "currentPage : 1
          },  "next" : "...",  "prev" : "..."}
        
通过查询,GET ManagedObjectCollection的内容表达。

应答正文(body): ManagedObjectCollection
需要角色权限: ROLE_INVENTORY_READ

请求示例: 通过查询,Get托管对象。

GET /inventory/managedObjects?q=<<query language statement>>
          Host: ...
          Authorization: Basic ...
          Accept: application/vnd.com.nsn.cumulocity.managedObjectCollection+json;ver=...
        

应答示例:

HTTP/1.1 200 OK
          Content-Type: application/vnd.com.nsn.cumulocity.managedObjectCollection+json;ver=...
          Content-Length: ...
          {
          "self" : "<<Collection URL>>",
          "managedObjects" : [
          {
          "self" : "<<Object 42 URL>>",
          "id" : "42",
          "type" :"bg_mps_D413",
          "name" : "Meter1",
          ...
        },
        {
        "self" : "<<Object 43 URL>>",
        "id": "43",
        "type" :"bg_mps_D413",
        "name": "Meter2",
        ...
      }
      ],
      "statistics" : {
      "totalPages" : 42,
      "pageSize" : 5,
      "currentPage : 1
    },  "next" : "...",  "prev" : "..."}
  
查询语言

查询语言应用于所有托管对象。

用户可以通过'query'参数进行查询。 参数可以是:
  • 只查询数据库:...?query=name eq 'M01'
  • 关键字 $filter=: ...?query=$filter=name eq 'M01'
  • 关键字 $orderby=: ...?query=$orderby=id asc
  • 关键字 $filter= and $orderby=: ...?query=$filter=name eq 'M01' $orderby=id,

这部分解释,应用将如何处理参数'q'中的查询。

支持的查询操作:
  • eq(Equal): City eq 'Redmond'
  • gt(Greater than): Price gt 20
  • ge(Greater than or equal): Price ge 10
  • lt(Less than): Price lt 20
  • le(Less than or equal): Price le 100
  • and(Logical and): Price le 200 and Price gt 3.5
  • or(Logical or): Price le 3.5 or Price gt 200
支持的查询函数:
  • has: has(name) - match objects with property name
  • bygroupid(12) - match objects from group with id equals 12
支持的查询值:
  • string
    • 例如: name eq 'Dev_002', name eq 'Dev', name eq '_001', name eq '*'
    • string 必须用单引号
    • string 可以包含通配符'*' ,并且这个通配符可以等同于0到N个字符
    • 匹配不分大小写
  • number
  • date
    • 例如: creationTime gt '2015-10-24T09:00:53.351+01:00'
支持的查询属性:
  • simple: name
  • nested: c8y_Availability.status
  • array: c8y_Availability.statuses = [1, 2, 3]
对查询运算符进行分组:
  • ( ) 优先级分组: (p1 eq 1) and (p2 eq 5 or p2 eq 6)
支持的排序操作:
  • desc
    • 例如: $orderby=name desc
  • asc
    • 例如: $orderby=name, $orderby=name asc
示例:

数据示例:

{
  "_id": 1,
  "name": "Dev_001",
  "num": 1,
  "c8y_Availability": {
  "statusId": 1
}
},
{
  "_id": 2,
  "name": "Dev_002",
  "num": 2,
  "c8y_Availability": {
  "statusId": 1
}
},
{
  "_id": 3,
  "name": "Mo_003",
  "num": 3,
  "c8y_Availability": {
  "statusId": 2
}
},
{
  "_id": 4,
  "name": "Mo_004",
  "num": 4,
  "c8y_Availability": {
  "statusId": 2
}
}

然后查询返回:

...q=num eq 1 - {"_id": 1, ...}
  ...q=name eq 'Dev_002' - {"_id": 2, ...}
  ...q=name eq '*00*' - return all 4 rows
  ...q=name eq '*dev_001*' - {"_id": 1, ...}
  ...q=c8y_Availability.statusId eq 2 - {"_id": 3, ...}, {"_id": 4, ...}
  ...q=num gt 2 - {"_id": 3, ...}, {"_id": 4, ...}
  ...q=num le 2 - {"_id": 1, ...}, {"_id": 2, ...}
  ...q=num eq 1 or num eq 2 - {"_id": 1, ...}, {"_id": 2, ...}
  ...q=has(name) - return all 4 rows
POST - 创建一个新的托管对象(ManagedObject)

请求(Request)正文(body): ManagedObject

应答(Response)正文(body): ManagedObject (当没有提供accept标头(header)时,返回空的应答正文)

需要角色权限: ROLE_INVENTORY_ADMIN or ROLE_INVENTORY_CREATE

请求示例 : 添加一个新的托管对象(ManagedObject)

POST /inventory/managedObjects
  Host: ...
  Authorization: Basic ...
  Content-Length: ...
  Content-Type: application/vnd.com.nsn.cumulocity.managedObject+json;ver=...
  {
  "name" : "A brand new switch",
  "com_cumulocity_model_BinarySwitch" : { "state": "OFF" }
}

应答示例:

HTTP/1.1 201 Created
  Content-Type: application/vnd.com.nsn.cumulocity.managedObject+json;ver=...
  Content-Length: ...
  Location: <<URL of new object>>
  {
  "self" : "<<URL of new object>>",
  "id"   : "111",
  "lastUpdated": "2012-04-21T18:03:19.932+02:00",
  "name" : "A brand new switch",
  "com_cumulocity_model_BinarySwitch" : { "state": "OFF" }
}

新的托管对象的"id"和"lastUpdated"由服务器生成,并在对POST操作的应答中返回。

托管对象

Managed Object [application/vnd.com.nsn.cumulocity.managedObject+json]
名字 类型 出现次数 描述 PUT/POST
id String 1 对象的唯一标识符,在创建对象时自动分配(参见上文)。 No
self URL 1 指向资源的链接。 No
type String 0..1 最具体类型的托管对象作为完全限定的Java风格的类型名称,点替换为下划线。 Optional
name String 0..1 用于在用户界面中表示对象的人工可读名称。 Optional
* Object 0..n 与特定ManagedObject关联的其他属性。 Optional
lastUpdated TimeStamp 1 对象上次更新的时间。 No
childDevices ManagedObject ReferenceCollection 0..1 子设备引用的集合。 No
childAssets ManagedObject ReferenceCollection 0..1 子设资产引用的集合。 No
deviceParents ManagedObject ReferenceCollection 0..1 引用设备父对象的集合。 No
assetParents ManagedObject ReferenceCollection 0..1 资产父对象的引用集合。 No

"child"和"parents"集合中的托管对象引用仅包含"id","name"和"self"属性。

不是每个GET应答都包含"parents"集合。 它需要传递"withParents = true"查询参数,包括"parents"。

GET 一个托管对象的内容表达

应答正文(body): ManagedObject

需要角色权限: ROLE_INVENTORY_READ

请求示例: Get一个指定托管对象的内容表达

GET /inventory/managedObjects/<<deviceId>>
    Host: ... 
    Authorization: Basic ...
    Accept: application/vnd.com.nsn.cumulocity.managedObject+json;=ver...
  

应答示例:

HTTP/1.1 200 OK
    Content-Type: application/vnd.com.nsn.cumulocity.managedObject+json;ver=...
    Content-Length: ...
    {
    "id" : "42",
    "name" : "SomeName",
    "self" : "<<This ManagedObject URL>>",
    "type" :"com_nsn_cumulocity_example_Clazz",
    "lastUpdated": "2012-05-02T19:48:40.006+02:00",
    "com_othercompany_StrongTypedClass" : { ... },
    "childDevices": {
    "self" : "<<ManagedObjectReferenceCollection URL>>",
    "references" : [
    {
    "self" : "<<ManagedObjectReference URL>>",
    "managedObject": {
    "id": "1",
    "self" : "<<ManagedObject URL>>"
    "name": "Some Child"
  }
},
...
]    
},
...
}
GET一个特定托管对象支持的测量值(measurements)

请求示例: 查询托管对象的支持测量值

GET /inventory/managedObjects/<<deviceId>>/supportedMeasurements
  Host: ...
  Authorization: Basic ...

应答示例:

HTTP/1.1 200 OK
  {
  "c8y_SupportedMeasurements": ["c8y_AnalogMeasurement", "c8y_MotionMeasurement", "c8y_SignalStrength", "c8y_TemperatureMeasurement"]
}

重要:为了在支持的测量值列表中包含片段名称,片段必须具有特定的结构:

"fragment_name" : { "serie_name" : { "value" : ... "unit" : ... } }

实际示例:

"c8y_SpeedMeasurement": { "Speed": { "value": 1234, "unit": "km/h" } }

Fragment_name和serie_name可以由不同的有效json属性名称替换,但该名称不能包含空格和特殊字符,如[],*。 结构必须完全如上,两层深的json对象。

PUT - 更新一个托管对象

请求正文(body): ManagedObject

应答正文(body): ManagedObject (当没有提供accept标头(header)时,返回空的应答正文。)

需要角色权限: ROLE_INVENTORY_ADMIN or owner

请求示例: 更改托管对象的名字

PUT /inventory/managedObjects/<<deviceId>>
  Host: ...
  Authorization: Basic ...
  Accept: application/vnd.com.nsn.cumulocity.managedObject+json;ver=...
  Content-Type: application/vnd.com.nsn.cumulocity.managedObject+json;ver=...
  Content-Length: ...
  { "name" : "Life, the Universe and the REST" }

应答示例:

HTTP/1.1 200 OK
  Content-Type: application/vnd.com.nsn.cumulocity.managedObject+json;ver=...
  {
  "id" : "42",
  "name" : "Life, the Universe and the REST",
  "self" : "<<This ManagedObject URL>>",
  "type" :"com_nsn_cumulocity_example_Clazz",
  "lastUpdated": "2012-05-02T19:58:40.006+02:00",
  "com_othercompany_StrongTypedClass" : { ... },
  "childDevices": {
  ...
},
...
}

当更新类型"c8y_SmartRule"的托管对象时,将创建具有类型"SmartRule"和动作"智能规则已更新","启用智能规则"或"禁用智能规则"的监控记录。

删除一个托管对象

请求正文(body): N/A.

应答消息正文(Body): N/A.

需要角色权限: ROLE_INVENTORY_ADMIN or owner

请求示例: 删除托管对象

DELETE /inventory/managedObjects/<<deviceId>>
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx

应答示例:

HTTP/1.1  204 NO CONTENT

如果使用可选查询参数"cascade = true",则将递归删除所有子设备和子资源。 默认情况下,只有在删除的对象是组时,删除操作才会传播到子组。

托管对象引用集合

ManagedObjectReferenceCollection [application/vnd.com.nsn.cumulocity.managedObjectReferenceCollection+json]
名字 类型 出现次数 描述
self URI 1 指向资源的链接。
references ManagedObjectReference 0..n 托管对象引用列表,参见下文。
statistics PagingStatistics 1 关于分页统计的信息。
prev URI 0..1 指向可能的托管对象的前一页的链接。
next URI 0..1 指向可能的托管对象的后一页的链接。
GET托管对象引用集合

应答正文(body): ManagedObjectReferenceCollection

请求示例: Get一个特定托管对象引用集合

请注意,如果对象没有引用,将出现"404未找到"错误。

GET /inventory/managedObjects/<<deviceId>>/<<references>>
    Host: ...
    Authorization: Basic
    Accept: application/vnd.com.nsn.cumulocity.managedObjectReferenceCollection+json;ver=...
  

请注意,引用可以是childDevices或childAssets。

应答示例:

HTTP/1.1 200 OK
  Content-Type: application/vnd.com.nsn.cumulocity.managedObjectReferenceCollection+json;ver=...
  Content-Length: ...

  {
  "self" : "<<This ManagedObjectReferenceCollection URL>>",
  "references" : [
  {
  "self" : "<<ManagedObjectReference URL>>",
  "managedObject" : {
  "self" : "<<ManagedObject 1 URL>>",
  "name" : "Meter1",
  "id" : "1",
  ...
}
},
{
  "self" : "<<ManagedObjectReference URL>>",
  "managedObject" : {
  "self" : "<<ManagedObject 2 URL>>",
  "name" : "Meter2",
  "id" : "2",
  ...
}
}
],
"statistics" : {
"pageSize" : 5,
"currentPage : 1
},
"next": "...",
"prev": "..."
}
POST - 向集合添加托管对象引用

请求正文(body): ManagedObjectReference

应答正文(body): ManagedObjectReference

需要角色权限: ROLE_INVENTORY_ADMIN or ROLE_INVENTORY_CREATE

请求示例: Add a ManagedObjectReference

POST /inventory/managedObjects/<<deviceId>>
  Host: ...
  Authorization: Basic ...
  Content-Length: ...
  Content-Type: application/vnd.com.nsn.cumulocity.managedObjectReference+json;ver=...

  {
  "managedObject" : { "self" :"<<ManagedObject URL>>" }
}

应答示例:

HTTP/1.1 201 Created
  Content-Type: application/vnd.com.nsn.cumulocity.managedObjectReference+json;ver=...
  Content-Length: ...
  Location: <<This ManagedObjectReference URL>>
  {
  "self" : "<<This ManagedObjectReference URL>>,
  "managedObject" : {
  "id" : "2",
  "self" : <<ManagedObject 2 URL>>,
  "name" : "Meter2",
  ...
}
}

作为替代,当添加到集合时,还允许在请求正文(body)中传递以下引用对象:

{
  "managedObject" : { "id" :"<<ManagedObject id>>" }
}

托管对象引用

ManagedObjectReference [application/vnd.com.nsn.cumulocity.managedObjectReference+json]
名字 类型 出现次数 描述
self URI 1 指向资源的链接。
managedObject ManagedObject 1 被引用的ManagedObject。
GET托管对象引用

应答正文(body): ManagedObjectReference

需要角色权限: ROLE_INVENTORY_READ

请求示例:

GET /inventory/managedObjects/<<deviceId>>/references/<<referenceId>>
    Host: ...
    Authorization: Basic ...
    Accept: application/vnd.com.nsn.cumulocity.managedObjectReference+json;ver=...
  

应答示例:

HTTP/1.1 200 OK
    Content-Type: application/vnd.com.nsn.cumulocity.managedObjectReference+json;ver=...
    Content-Length: ...
    {
    "self" : "<<This ManagedObjectReference URL>>",
    "managedObject" : {
    "self" : "<<ManagedObject 4 URL>>",
    "name" : "Foo",
    "id" : "4",
    ...
  }
}
DELETE 托管对象引用

请求正文(Body): N/A.

应答消息正文(Body): N/A.

需要角色权限: ROLE_INVENTORY_ADMIN or owner

注意:此操作只是删除引用,它不会删除对象本身。

请求示例: Delete托管对象引用

DELETE /inventory/managedObjects/<<deviceId>>/references/<<referenceId>>
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx

应答示例:

HTTP/1.1  204 NO CONTENT

通知

用于接收通知的基本协议在"实时通知"一节中描述。 URL是 设备清单通知允许监控设备清单中的更改(创建,更新和删除)。 用于接收通知的基本协议在 "实时通知"一节中描述。 URL是

/cep/realtime
    

订阅频道需要包含应监控的设备清单中对象的托管对象ID或作为占位符的"*",以接收整个设备清单的通知

/managedobjects/<<managedObjectId>>
    

该应答将对托管对象包含"realtimeAction",以标识哪个动作导致给定对象(CREATE,UPDATE或DELETE)。 在删除的情况下,数据将只包含被删除的托管对象的id。

应答示例:

HTTP/1.1 200 OK
      Content-Type: application/json
      [
      {
      "channel": "/managedobjects/12345",
      "successful": true,
      "error": "",
      "data": [{
      "realtimeAction": "UPDATE",
      "data": {
      "id": "12345",
      "self": "...",
      "creationTime": "2011-09-06T12:03:27.927+02:00",
      "name": "a device",
      "c8y_IsDevice": {},
      "c8y_Location": { ... }
    }
  }],
  "clientId": "Un1q31d3nt1f13r"
}
]

需要角色权限: ROLE_INVENTORY_READ