Overview
The inventory interface consists of the following parts:
- The inventory API resource returns URIs and URI templates to collections of managed objects, so that all objects, all objects of a particular type and all objects with particular capabilities can be queried.
- The managed object collection resource retrieves sets of managed objects and enables creating new managed objects.
- The managed object resource represents individual managed objects that can be queried and deleted.
- The managed object reference collection resource retrieves sets of references to managed objects. These could be, for example, child devices of a particular managed object. It also enables adding new references to a collection (e.g., adding a new child device).
- The managed object reference resource represents one individual reference to a managed object, which can be retrieved or deleted.
Info: For all PUT/POST requests an accept header should be provided, otherwise an empty response body will be returned.
Inventory API
InventoryAPI [application/vnd.com.nsn.cumulocity.inventoryApi+json]
Name | Type | Occurs | Description |
---|---|---|---|
self | string | 1 | A URL linking to this resource. |
managedObjects | ManagedObjectCollection | 1 | Collection of all managed objects. |
managedObjectsForType | ManagedObjectCollection URI-Template | 1 | Read-only collection of all managed objects of a particular type (placeholder {type}). |
managedObjectsForFragmentType | ManagedObjectCollection URI-Template | 1 | Read-only collection of all managed objects with a particular fragment type or capability (placeholder {fragmentType}). |
managedObjectsForListOfIds | ManagedObjectCollection URI-Template | 1 | Read-only collection of managed objects fetched for a given list of IDs (placeholder {ids}),for example “?ids=41,43,68”. |
managedObjectsForText | ManagedObjectCollection URI-Template | 1 | Read-only collection of managed objects containing a text value starting with the given text (placeholder {text}). Text value is any alphanumeric string starting with a latin letter (A-Z or a-z). |
GET - Representation of the Inventory API resource
Response body: application/vnd.com.nsn.cumulocity.inventoryApi+json
Required role: ROLE_INVENTORY_READ
Example request - Get the Inventory API resource
HEADERS | |
---|---|
Authorization | {{auth}} |
Host | {{hostname}} |
200 - OK
GET <<url>>/inventory
Example response
HEADERS | |
---|---|
Content-Type | application/vnd.com.nsn.cumulocity.inventoryapi+json;ver=… |
HTTP/1.1
200 - OK
{
"managedObjectsForFragmentType" : "<<ManagedObjectCollection URL>>?fragmentType={fragmentType}",
"managedObjectsForType" : "<<ManagedObjectCollection URL>>?type={type}",
"self" : "<<InventoryAPI URL>>",
"managedObjects" : {
"self" : "<<ManagedObjectCollection URL>>",
"references": []
},
"managedObjectsForListOfIds" : "<<ManagedObjectCollection URL>>?ids={ids}"
}
Managed object collection
Important: Things to note when querying managed objects without the ROLE_INVENTORY_READ role:
- The response contains managed objects which are in hierarchy, or a direct access to them was configured via Administration > Managing permissions > Assigning inventory roles to users.
- Checking hierarchy for each resource is a performance expensive operation. Hence, the maximum deep level was limited to 5. This means that a user which has a complex hierarchy with more than 5 nested groups/device assets, may not receive all data when querying managed objects without the ROLE_INVENTORY_READ role.
ManagedObjectCollectionAPI [application/vnd.com.nsn.cumulocity.managedObjectCollection+json]
Name | Type | Occurs | Description |
---|---|---|---|
self | string | 1 | A URI linking to this resource. |
managedObjects | ManagedObject | 0..n | List of managed objects, see below. |
statistics | PagingStatistics | 1 | Information about paging statistics. |
prev | string | 0..1 | A URI linking to a potential previous page of managed objects. |
next | string | 0..1 | A URI linking to a potential next page of managed objects. |
GET - Representation of a ManagedObjectCollection
Response body: ManagedObjectCollection
Example request - Get managed objects of a particular type
HEADERS | |
---|---|
Authorization | {{auth}} |
Host | {{hostname}} |
GET <<url>>/inventory/managedObjects
Accept: application/vnd.com.nsn.cumulocity.managedobjectcollection+json;ver=...
Example response
HEADERS | |
---|---|
Content-Type | application/vnd.com.nsn.cumulocity.managedobjectcollection+json;ver=… |
HTTP/1.1
200 OK
{
"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 - Representation of a ManagedObjectCollection by query
Response body: ManagedObjectCollection
Example request - Get managed objects found by query
HEADERS | |
---|---|
Authorization | {{auth}} |
200 - OK
GET <<url>>/inventory/managedObjects?query=<<query language statement>>
Accept: application/vnd.com.nsn.cumulocity.managedobjectcollection+json;ver=...
Example response
HEADERS | |
---|---|
Content-Type | 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 language
Query expressions are matched against all managed objects.
You can use the following query
parameters:
- Only query the database:
...?query=name eq 'M01'
- Keyword
$filter=
:...?query=$filter=name eq 'M01'
- Keyword
$orderby=
:...?query=$orderby=id asc
- Keywords
$filter=
and$orderby=
:...?query=$filter=name eq 'M01' $orderby=id
Query expressions extend the URL. The OData syntax rules for URLs apply. Regex features with custom filter queries are not supported.
The following sections explain how an application will handle a query in the parameter query
.
Supported query operations:
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
not
(logical not):not has(c8y_IsDevice)
Supported query functions:
-
has
:has(c8y_IsDevice)
- match objects with custom propertyc8y_IsDevice
- Only supports custom fragments.
- Standard properties are not supported, i.e. none of:
id
,type
,name
,self
,lastUpdated
,owner
,creationTime
,supportedMeasurements
,childAssets
,childDevices
,childAdditions
,externalIds
-
bygroupid(12)
- match objects from group with ID12
Supported query values:
- String; examples:
name eq 'Dev002'
,name eq 'Dev*'
,name eq '*001'
,name eq '*'
- The string must be surrounded by single quotes.
- The string can contain the wildcard
*
and it matches 0 to N characters. - Matching is case-sensitive.
- Number values
datetime
; example:creationTime.date gt '2015-10-24T09:00:53.351+01:00'
(this must be OData encoded)
Supported query properties:
- Simple:
name
- Nested:
c8y_Availability.status
Grouping query operators:
( )
Precedence grouping:(p1 eq 1) and (p2 eq 5 or p2 eq 6)
Supported sort operations:
desc
; example:$orderby=name desc
asc
; example:$orderby=name, $orderby=name asc
Important: If you query
/inventory/managedObjects?type=c8y_Firmware&query=$filter=(name+eq+'Controller 1')
, the query parametertype
is ignored. Instead,/inventory/managedObjects?query=$filter=(type+eq+c8y_Firmware+and+name+eq+'Controller 1')
has to be queried.
Example data
{
"_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
}
}
Query response
...query=num eq 1 - {"_id": 1, ...}
...query=name eq 'Dev_002' - {"_id": 2, ...}
...query=name eq '*00*' - return all 4 rows
...query=name eq '*Dev_001*' - {"_id": 1, ...}
...query=c8y_Availability.statusId eq 2 - {"_id": 3, ...}, {"_id": 4, ...}
...query=num gt 2 - {"_id": 3, ...}, {"_id": 4, ...}
...query=num le 2 - {"_id": 1, ...}, {"_id": 2, ...}
...query=num eq 1 or num eq 2 - {"_id": 1, ...}, {"_id": 2, ...}
...query=has(c8y_Availability) - return all 4 rows
Managed object
Managed Object [application/vnd.com.nsn.cumulocity.managedObject+json]
Name | Type | Occurs | Description | PUT/POST |
---|---|---|---|---|
id | string | 1 | Unique identifier of the object, automatically allocated when the object is created (see above). | No |
self | string | 1 | A URL linking to this resource. | No |
type | string | 0..1 | The most specific type of the managed object as fully qualified Java-style type name, dots replaced by underscores. | Optional |
name | string | 0..1 | Human-readable name that is used for representing the object in user interfaces. | Optional |
* | Object | 0..n | Additional properties associated with the specific ManagedObject. | Optional |
creationDate | datetime | 1 | The time when the object has been created. | POST only |
lastUpdated | datetime | 1 | The time when the object was last updated. | No |
childDevices | ManagedObject ReferenceCollection | 0..1 | A collection of references to child devices. | No |
childAdditions | ManagedObject ReferenceCollection | 0..1 | A collection of references to child additions. | No |
childAssets | ManagedObject ReferenceCollection | 0..1 | A collection of references to child assets. | No |
deviceParents | ManagedObject ReferenceCollection | 0..1 | A collection of references to device parent objects. Note: GET to /inventory/managedObjects/{{deviceId}}/deviceParents is not implemented. | No |
assetParents | ManagedObject ReferenceCollection | 0..1 | A collection of references to asset parent objects. Note: GET to /inventory/managedObjects/{{deviceId}}/assetParents is not implemented. | No |
statusChangeDate | datetime | 0..1 | The property is updated when the tenant status is modified. The value cannot be modified, it can only be viewed. | No |
It is recommended for property names not to start with “child” or “parent”. This way you will be able to handle other types of references.
A managed object reference in the “child” and “parents” collections contains only id
, name
and self
properties.
Not every GET response contains “parents” collections. You need a global role with READ “Inventory” permission to query the managed object “parents”. Pass withParents=true
query param to have “parents” included. If you query the managed object withParents=true
it will return a flat list of all parents and grandparents of the given object.
Info: If you query
childDevices
, only the children of the given device are returned without any grandchildren.
GET - Representation of a managed object
Response body: ManagedObject
Required role: ROLE_INVENTORY_READ
Example request - Get a representation of a specific managed object
HEADERS | |
---|---|
Authorization | {{auth}} |
Host | {{hostname}} |
200 - OK
GET <<url>>/inventory/managedObjects/<<deviceId>>
Accept: application/vnd.com.nsn.cumulocity.managedobject+json;=ver...
Example response
HEADERS | |
---|---|
Content-Type | application/vnd.com.nsn.cumulocity.managedobject+json;ver=… |
HTTP/1.1
200 - OK
{
"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"
}
},
...
]
},
...
}
Info: Parents of the ManagedObject are always empty unless a flag “withParents” is specified.
POST - Create a new ManagedObject
Request body: ManagedObject
Response body: ManagedObject (when the Accept
header is not provided, an empty response body is returned)
Required role: ROLE_INVENTORY_ADMIN or ROLE_INVENTORY_CREATE
Example request - Add a new ManagedObject
HEADERS | |
---|---|
Authorization | {{auth}} |
Host | {{hostname}} |
Content-Type | application/vnd.com.nsn.cumulocity.managedobject+json;ver=… |
Accept | application/vnd.com.nsn.cumulocity.managedobject+json;ver=… |
POST <<url>>/inventory/managedObjects
{
"name" : "A brand new switch",
"com_cumulocity_model_BinarySwitch" : { "state": "OFF" }
}
Example response
HEADERS | |
---|---|
Content-Type | application/vnd.com.nsn.cumulocity.managedobject+json;ver=… |
HTTP/1.1
201 - Created
{
"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" }
...
}
The id
and lastUpdated
of the new managed object are generated by the server and returned in the response to the POST operation.
GET - Supported measurements of a managed object
Example request - Retrieve supported measurements of a managed object
HEADERS | |
---|---|
Authorization | {{auth}} |
Host | {{hostname}} |
200 - OK
GET <<url>>/inventory/managedObjects/<<deviceId>>/supportedMeasurements
Example response
HEADERS | |
---|---|
Content-Type | application/vnd.com.nsn.cumulocity.managedobject+json;ver=… |
HTTP/1.1
200 - OK
{
"c8y_SupportedMeasurements": ["c8y_AnalogMeasurement", "c8y_MotionMeasurement", "c8y_SignalStrength", "c8y_TemperatureMeasurement"]
}
Important: In order to have fragment names included in the supported measurements list, the fragment has to have a specific structure:
"fragment_name" : {
"serie_name" : {
"value" : ...
"unit" : ...
}
}
Real example:
"c8y_SpeedMeasurement": {
"Speed": {
"value": 1234,
"unit": "km/h"
}
}
Fragment_name
and serie_name
can be replaced by a different valid json property name, but that name may not contain whitespaces and special characters like [], *. The structure has to be exactly as above, a two-level deep json object.
GET - Supported series of a managed object
Example request - Retrieve supported series of a managed object
HEADERS | |
---|---|
Authorization | {{auth}} |
Host | {{hostname}} |
200 - OK
GET <<url>>/inventory/managedObjects/<<deviceId>>/supportedSeries
Example response
HEADERS | |
---|---|
Content-Type | application/vnd.com.nsn.cumulocity.managedobject+json;ver=… |
HTTP/1.1
200 - OK
{
{"c8y_SupportedSeries":["c8y_TemperatureMeasurement.T","c8y_SpeedMeasurement.speed","c8y_SignalStrength.rssi"]}
}
Important: In order to have fragment names included in the supported series list, the fragment has to have a specific structure. See the explanation above regarding supported measurements.
PUT - Update a managed object
Request body: ManagedObject
Response body: ManagedObject (when the Accept
header is not provided, an empty response body is returned)
Required role: ROLE_INVENTORY_ADMIN or owner
Example request - Change the name of a managed object
HEADERS | |
---|---|
Authorization | {{auth}} |
Accept | application/vnd.com.nsn.cumulocity.managedobject+json;ver=… |
Content-Type | application/vnd.com.nsn.cumulocity.managedobject+json;ver=… |
200 - OK
PUT <<url>>/inventory/managedObjects/<<deviceId>>
{
"name" : "Life, the Universe and the REST"
}
Example response
HEADERS | |
---|---|
Content-Type | application/vnd.com.nsn.cumulocity.managedobject+json;ver=… |
HTTP/1.1
200 - OK
{
"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": {
...
},
...
}
When a managed object of type c8y_SmartRule
is updated, an audit record is created with type “SmartRule” and activity “Smart rule updated”, “Smart rule enabled” or “Smart rule disabled”.
DELETE - Managed object
Request body: N/A
Response message body: N/A
Required role: ROLE_INVENTORY_ADMIN or owner
Example request - Delete a managed object
HEADERS | |
---|---|
Authorization | {{auth}} |
Host | {{hostname}} |
DELETE <<url>>/inventory/managedObjects/<<deviceId>>
Example response
HTTP/1.1
204 - NO CONTENT
If the managed object is a device or a group and the optional query parameter cascade=true
is used, all child devices and child assets will be deleted recursively. By default, the delete operation is propagated to the subgroups only if the deleted object is a group.
If you want to delete the full hierarchy regardless of the managed object type, use the query parameter forceCascade=true
. When both cascade
and forceCascade
are provided the second one takes precedence.
Info: Inventory DELETE requests are not synchronous. The response could be returned before the delete request has been completed.
Managed object reference collection
ManagedObjectReferenceCollection [application/vnd.com.nsn.cumulocity.managedObjectReferenceCollection+json]
Name | Type | Occurs | Description |
---|---|---|---|
self | string | 1 | A URI linking to this resource. |
references | ManagedObjectReference | 0..n | List of managed object references, see below. |
statistics | PagingStatistics | 1 | Information about paging statistics. |
prev | string | 0..1 | A URI linking to a potential previous page of managed objects. |
next | string | 0..1 | A URI linking to a potential next page of managed objects. |
GET - Managed object reference collection
Response body: ManagedObjectReferenceCollection
Example request - Get reference collection of a certain managed object
HEADERS | |
---|---|
Authorization | {{auth}} |
Host | {{hostname}} |
Info: “404 Not Found” error will appear if the object has no references.
GET /inventory/managedObjects/{deviceId}/childDevices
Host: https://<TENANT_DOMAIN>
Info: Besides childDevices in the URL, you can also use childAssets or childAdditions.
Example response
HEADERS | |
---|---|
Content-Type | application/vnd.com.nsn.cumulocity.managedobjectreferencecollection+json;ver=… |
HTTP/1.1
200 - OK
{
"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 - Add a managed object reference to the collection
Request body: ManagedObjectReference
Response body: ManagedObjectReference
Required role: ROLE_INVENTORY_ADMIN or parent and child owner
Info: Use the header
X-Cumulocity-Processing-Mode
set toQUIESCENT
to disable real-time notifications. This is required when performance is important or dealing with a large group of objects.
Example request - Add a ManagedObjectReference
HEADERS | |
---|---|
Authorization | {{auth}} |
Host | {{hostname}} |
Content-Type | application/vnd.com.nsn.cumulocity.managedobject+json;ver=… |
POST /inventory/managedObjects/{deviceId}/childDevices
Host: https://<TENANT_DOMAIN>
{
"managedObject" : { "self" :"<<ManagedObject URL>>" }
}
Info: Besides childDevices in the URL, you can also use childAssets or childAdditions.
Example response
HEADERS | |
---|---|
Content-Type | application/vnd.com.nsn.cumulocity.managedobjectreference+json;ver=… |
HTTP/1.1
201 - Created
{
"self" : "<<This ManagedObjectReference URL>>,
"managedObject" : {
"id" : "2",
"self" : <<ManagedObject 2 URL>>,
"name" : "Meter2",
...
}
}
As an alternative, it is also allowed to pass the following reference object in the request body when adding to the collection:
{
"managedObject" : { "id" :"<<ManagedObject id>>" }
}
POST - Add multiple object references to the collection
Request body: ManagedObjectReferenceCollection
Response body: ManagedObjectReferenceCollection (when the Accept header is not provided, an empty response body is returned)
Required role: ROLE_INVENTORY_ADMIN or parent and children owner
Example request - Add a ManagedObjectReferenceCollection
HEADERS | |
---|---|
Authorization | {{auth}} |
Host | {{hostname}} |
Content-Type | application/vnd.com.nsn.cumulocity.managedobjectreferencecollection+json;ver=… |
Accept | application/vnd.com.nsn.cumulocity.managedobjectreferencecollection+json;ver=… |
POST /inventory/managedObjects/100/childDevices
{
"references":[
{
"managedObject":{
"id":"128"
}
},
{
"managedObject":{
"id":"129"
}
}
]
}
Info: Besides childDevices in the URL, you can also use childAssets or childAdditions.
Example response
HEADERS | |
---|---|
Content-Type | application/vnd.com.nsn.cumulocity.managedobjectreferencecollection+json;ver=… |
HTTP/1.1
201 - Created
{
"self" : "https://<TENANT_DOMAIN>/inventory/managedObjects/100/childDevices",
"references": [
{
"self" : "https://<TENANT_DOMAIN>/inventory/managedObjects/100/childDevices/128",
"managedObject" : {
"additionParents": {
"self": "https://<TENANT_DOMAIN>/inventory/managedObjects/128/additionParents",
"references": []
},
"owner": "admin",
"childDevices": {
"self": "https://<TENANT_DOMAIN>/inventory/managedObjects/128/childDevices",
"references": []
},
"childAssets": {
"self": "https://<TENANT_DOMAIN>/inventory/managedObjects/128/childAssets",
"references": []
},
"creationTime": "2020-12-31T09:38:34.448Z",
"lastUpdated": "2020-12-31T09:38:34.448Z",
"childAdditions": {
"self": "https://<TENANT_DOMAIN>/inventory/managedObjects/128/childAdditions",
"references": []
},
"name": "testMeasurementDevice",
"assetParents": {
"self": "https://<TENANT_DOMAIN>/inventory/managedObjects/128/assetParents",
"references": []
},
"deviceParents": {
"self": "https://<TENANT_DOMAIN>/inventory/managedObjects/128/deviceParents",
"references": []
},
"self": "https://<TENANT_DOMAIN>/inventory/managedObjects/128",
"id": "128",
"c8y_IsDevice": {},
"c8y_SupportedMeasurements": [
"c8y_TemperatureMeasurement"
]
}
},
{
"self" : "https://<TENANT_DOMAIN>/inventory/managedObjects/100/childDevices/129",
"managedObject" : {
"additionParents": {
"self": "https://<TENANT_DOMAIN>/inventory/managedObjects/129/additionParents",
"references": []
},
"owner": "admin",
"childDevices": {
"self": "https://<TENANT_DOMAIN>/inventory/managedObjects/129/childDevices",
"references": []
},
"childAssets": {
"self": "https://<TENANT_DOMAIN>/inventory/managedObjects/129/childAssets",
"references": []
},
"creationTime": "2020-12-31T09:39:58.705Z",
"lastUpdated": "2020-12-31T09:39:58.705Z",
"childAdditions": {
"self": "https://<TENANT_DOMAIN>/inventory/managedObjects/129/childAdditions",
"references": []
},
"name": "MeasurementDeviceName",
"assetParents": {
"self": "https://<TENANT_DOMAIN>/inventory/managedObjects/129/assetParents",
"references": []
},
"deviceParents": {
"self": "https://<TENANT_DOMAIN>/inventory/managedObjects/129/deviceParents",
"references": []
},
"self": "https://<TENANT_DOMAIN>/inventory/managedObjects/129",
"id": "129",
"c8y_IsDevice": {},
"c8y_SupportedMeasurements": [
"c8y_TemperatureMeasurement"
]
}
}
]
}
DELETE - Managed object reference collection
Request body: ManagedObjectReferenceCollection
Response message body: N/A
Required role: ROLE_INVENTORY_ADMIN or parent owner or child owner
Info: This operation just removes the reference, it does not delete the object itself.
Example request - Delete a managed object reference collection
HEADERS | |
---|---|
Authorization | {{auth}} |
Host | {{hostname}} |
Content-Type | application/vnd.com.nsn.cumulocity.managedobjectreferencecollection+json;ver=… |
DELETE /inventory/managedObjects/100/childDevices
{
"references":[
{
"managedObject":{
"id":"128"
}
},
{
"managedObject":{
"id":"129"
}
}
]
}
Info: Besides childDevices in the URL, you can also use childAssets or childAdditions.
Example response
HTTP/1.1
204 - NO CONTENT
Managed object reference
ManagedObjectReference [application/vnd.com.nsn.cumulocity.managedObjectReference+json]
Name | Type | Occurs | Description |
---|---|---|---|
self | string | 1 | A URI linking to this resource. |
managedObject | ManagedObject | 1 | The ManagedObject being referenced. |
GET - Managed object reference
Response body: ManagedObjectReference
Required role: ROLE_INVENTORY_READ
Example request
HEADERS | |
---|---|
Authorization | {{auth}} |
Host | {{hostname}} |
200 - OK
GET <<url>>/inventory/managedObjects/<<deviceId>>/<<references>>/<<referenceId>>
Example response
HEADERS | |
---|---|
Content-Type | application/vnd.com.nsn.cumulocity.managedobjectreference+json;ver=… |
HTTP/1.1
200 - OK
{
"self" : "<<This ManagedObjectReference URL>>",
"managedObject" : {
"self" : "<<ManagedObject 4 URL>>",
"name" : "Foo",
"id" : "4",
...
}
}
DELETE - Managed object reference
Request body: N/A
Response message body: N/A
Required role: ROLE_INVENTORY_ADMIN or parent owner or child owner
Info: This operations just removes the reference, it does not delete the object itself.
Example request - Delete a managed object reference
HEADERS | |
---|---|
Authorization | {{auth}} |
Host | {{hostname}} |
DELETE /inventory/managedObjects/<<deviceId>>/<<references>>/<<referenceId>>
Example response
HTTP/1.1
204 - NO CONTENT
Notifications
Inventory notifications permit the monitoring of changes in the inventory (CREATE, UPDATE and DELETE).
The basic protocol for receiving notifications is described in Real-time notifications.
The URL is:
/cep/realtime
The subscription channel must contain the managed object ID of the object in the inventory to be monitored or a “*” as placeholder to receive notifications for the entire inventory.
/managedobjects/<<managedObjectId>>
In addition to the managed object, the response will contain a realtimeAction
to identify which action resulted in the given object (CREATE, UPDATE or DELETE). In case of a deletion the data will only contain the ID of the deleted managed object.
Required role: ROLE_INVENTORY_READ
Example response
HEADERS | |
---|---|
Content-Type | application/json |
HTTP/1.1
200 - OK
[
{
"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"
}
]