インベントリ

インベントリではバイナリの保存が可能です。下記のAPIは「/inventory」で公開されていません。

概要

インベントリインターフェースは以下の要素で構成されます。

注記:すべてのPUT / POSTリクエストに対して「accept」ヘッダーを使用する必要があります。そうでない場合は、空の応答本体が返されます。

インベントリAPI

インベントリAPI [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 所定のIDリストのために取得したマネージドオブジェクトの読み取り専用コレクション(プレースホルダー{ids})(例:「?ids=41,43,68」)
managedObjectsForText ManagedObjectCollection URI-Template 1 所定のテキストから始まるテキスト値を含むマネージドオブジェクトの読み取り専用コレクション(プレースホルダー{text})。 テキスト値はラテン文字から始まる任意の英数字である(A-Zまたはa-z)

GET - インベントリAPIリソースの取得

応答本体: application/vnd.com.nsn.cumulocity.inventoryApi+json

要求されるロール: ROLE_INVENTORY_READ

リクエスト例 - インベントリAPIリソースを取得する

ヘッダー
Authorization {{auth}}
200 - OK

GET <<url>>/inventory

応答例

ヘッダー
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}"
}

マネージドオブジェクトコレクション

マネージドオブジェクトコレクションAPI [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

要求されるロール: ROLE_INVENTORY_READ

リクエスト例 - 特定のタイプのマネージドオブジェクトを取得する

ヘッダー
Authorization {{auth}}
GET <<url>>/inventory/managedObjects
Accept: application/vnd.com.nsn.cumulocity.managedObjectCollection+json;ver=...

応答例

ヘッダー
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 - クエリによるマネージドオブジェクトコレクションの取得

応答本体: ManagedObjectCollection

要求されるロール: ROLE_INVENTORY_READ

リクエスト例 - クエリによって見つかったマネージドオブジェクトを取得する

ヘッダー
Authorization {{auth}}
200 - OK
   
GET <<url>>/inventory/managedObjects?query=<<query language statement>>
Accept: application/vnd.com.nsn.cumulocity.managedObjectCollection+json;ver=...

応答例

ヘッダー
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'パラメータを介してクエリをPUTすることができます。 以下のパラメータを使用できます。

ここでは、アプリケーションがパラメーター'query'でクエリを処理する方法を説明します。

サポートされるクエリオペレーション:
サポートされるクエリ関数:
サポートされるクエリ値:
サポートされるクエリプロパティ:
クエリ演算子のグルーピング:
サポートされるソートオペレーション:

データ例

    {
        "_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=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

マネージドオブジェクト

マネージドオブジェクト [application/vnd.com.nsn.cumulocity.managedObject+json]

名称 タイプ 発生回数 説明 PUT/POST
id String 1 オブジェクト作成時に自動的に割り当てられる、オブジェクトの固有識別子(上記参照) なし
self URL 1 このリソースへのリンク なし
type String 0..1 このマネージドオブジェクトタイプを端的に表すタイプ名。完全修飾Java-styleタイプ名を使用する場合、ドットはアンダースコアに置き換えてください 任意
name String 0..1 ユーザーインターフェース内でオブジェクトを表現するために使用される、人間が判読可能な名称 任意
* Object 0..n 特定のマネージドオブジェクトに付随する付加的プロパティ 任意
creationDate TimeStamp 1 オブジェクトが作成された時間 POSTのみ
lastUpdated TimeStamp 1 オブジェクトが最後に更新された時間 なし
childDevices ManagedObject ReferenceCollection 0..1 子デバイスに対するリファレンスのコレクション なし
childAdditions ManagedObject ReferenceCollection 0..1 追加された子に対するリファレンスのコレクション なし
childAssets ManagedObject ReferenceCollection 0..1 子アセットに対するリファレンスのコレクション。 なし
deviceParents ManagedObject ReferenceCollection 0..1 親デバイスのオブジェクトに対するリファレンスのコレクション。注記:「/inventory/managedObjects/{{deviceId}}/deviceParents」へのGETは実装されていません なし
assetParents ManagedObject ReferenceCollection 0..1 親アセットのオブジェクトに対するリファレンスのコレクション。注記: 「/inventory/managedObjects/{{deviceId}}/assetParents」 へのGETは実装されていません なし
statusChangeDate ManagedObjectReferenceCollection 0..1 テナントのステータスが変更されるとプロパティが更新されます。この値は表示のみで変更はできません なし

プロパティ名を「child」または「parent」で始めないようにすることをお勧めします。そうすれば、他のタイプの参照を処理できるようになります。

「child」と「parents」のコレクションにおけるマネージドオブジェクトのリファレンスは「id」、「name」および「self」のプロパティのみ包含します。

すべてのGET応答が「parents」コレクションを含むとは限りません。 「parents」を含めるにはwithParents=trueのクエリパラメータを渡す必要があります。withParents=trueの含んだマネージドオブジェクトをクエリすると、指定されたオブジェクトのすべての親と祖父母のフラットリストが返されます。

備考: もしchildDevicesをクエリすると、孫デバイスは含まれず、子デバイスのみが返されます。

GET - マネージドオブジェクトの表現

応答本体: ManagedObject

要求されるロール: ROLE_INVENTORY_READ

リクエスト例 - 特定のマネージドオブジェクトの表現を取得する

ヘッダー  
Authorization {{auth}}
200 - OK

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

応答例

ヘッダー  
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"
        }
      },
      ...
    ]
  },
  ...
}

備考: 「with Parents」フラグが指定されていない限り、マネージドオブジェクトの親は常に空です。

POST - 新規マネージドオブジェクトの作成

リクエスト本体: ManagedObject

応答本体: ManagedObject (acceptヘッダーが提供されていない場合、空の応答本体が返されます)

要求されるロール: ROLE_INVENTORY_ADMIN or ROLE_INVENTORY_CREATE

リクエスト例 - 新規マネージドオブジェクトを追加する

ヘッダー  
Authorization {{auth}}
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" }
    }

応答例

ヘッダー  
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" }
  ...
}

新しい管理対象オブジェクトの「id」と「lastUpdated」はサーバーによって生成され、POST操作への応答で返されます。

GET - マネージドオブジェクトのサポート対象メジャーメントの取得

リクエスト例 - マネージドオブジェクトのサポート対象メジャーメントを読み出す

ヘッダー  
Authorization {{auth}}
200 - OK

GET <<url>>/inventory/managedObjects/<<deviceId>>/supportedMeasurements

応答例

ヘッダー  
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"]
}

重要事項: サポート対象メジャーメントリストにフラグメント名を含めるには、フラグメントが特有の構造をしていなければなりません。

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

実例:

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

Fragment_nameserie_nameはさまざまな有効なjsonプロパティ名に置き換えることができますが、名称に空白と[]、*など特殊記号が含まれてはなりません。 構造は上記の通り、正確な2段階のjsonオブジェクトでなければなりません。

GET - マネージドオブジェクトのサポート対象シリーズの取得

リクエスト例 - マネージドオブジェクトのサポート対象シリーズを読み出す

ヘッダー  
Authorization {{auth}}
200 - OK

GET <<url>>/inventory/managedObjects/<<deviceId>>/supportedSeries

応答例

ヘッダー  
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"]}
}

重要事項: サポート対象シリーズリストにフラグメント名を含めるには、フラグメントが特有の構造をしていなければなりません。上記にあるサポート対象メジャーメントに関する説明をご覧ください。

PUT - マネージドオブジェクトの更新

リクエスト本体: ManagedObject

応答本体: ManagedObject (acceptヘッダーが提供されていない場合、空の応答本体が返されます)

要求されるロール: ROLE_INVENTORY_ADMIN or owner

リクエスト例 - マネージドオブジェクトの名称の変更

ヘッダー  
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"
}

応答例

ヘッダー  
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": {
    ...
  },
  ...
}

タイプが c8y_SmartRule のマネージドオブジェクトが更新される場合、タイプが"SmartRule”、アクティビティが"Smart rule updated”、“Smart rule enabled”、“Smart rule disabled"の監査記録が作成されます。

DELETE - マネージドオブジェクトの削除

リクエスト本体: N/A

応答メッセージ本体: N/A

要求されるロール: ROLE_INVENTORY_ADMIN or owner

リクエスト例 - マネージドオブジェクトを削除する

ヘッダー  
Authorization {{auth}}

DELETE <<url>>/inventory/managedObjects/<<deviceId>>

応答例

HTTP/1.1 
204 - NO CONTENT

マネージドオブジェクトがデバイスまたはグループであり、任意のクエリパラメータ「cascade=true」が使用されていると、すべての子デバイスおよび子アセットが再帰的に削除されます。 デフォルトでは、削除されたオブジェクトがグループである場合に限り、削除オペレーションがサブグループにも伝播されます。

備考: インベントリのDELETE要求は同期的ではありません。 DELETE要求が完了する前に応答が返される可能性があります。

マネージドオブジェクリファレンスコレクション

マネージドオブジェクリファレンスコレクション [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 - マネージドオブジェクリファレンスコレクションの取得

応答本体: ManagedObjectReferenceCollection

リクエスト例 - 特定のマネージドオブジェクトのリファレンスコレクションを取得する

ヘッダー
Authorization {{auth}}

備考: オブジェクトがリファレンスを持たない場合、「404 Not Found」エラーが表示されます。

GET <<url>>/inventory/managedObjects/<<deviceId>>/<<references>>

備考: リファレンスはchildDevices または childAssetsになります。

応答例

ヘッダー
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 - マネージドオブジェクリファレンスをコレクションに追加

リクエスト本体: ManagedObjectReference

応答本体: ManagedObjectReference

要求されるロール: ROLE_INVENTORY_ADMIN または 親と子のオーナー

リクエスト例 - マネージドオブジェクリファレンスを追加する

ヘッダー
Authorization {{auth}}
Content-Type application/vnd.com.nsn.cumulocity.managedObject+json;ver=…

POST <<url>>/inventory/managedObjects/<<deviceId>>/<<references>>

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

応答例

ヘッダー
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",
    ...
  }
}

代替策として、コレクションに追加する際に以下のリファレンスオブジェクトをリクエスト本体に渡すことも可能です。

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

マネージドオブジェクトリファレンス

マネージドオブジェクトリファレンス [application/vnd.com.nsn.cumulocity.managedObjectReference+json]

名称 タイプ 発生回数 説明
self URI 1 このリソースへのリンク
managedObject ManagedObject 1 参照されるマネージドオブジェクト

GET - マネージドオブジェクトリファレンスの取得

応答本体: ManagedObjectReference

要求されるロール: ROLE_INVENTORY_READ

リクエスト例

ヘッダー
Authorization {{auth}}
200 - OK

GET <<url>>/inventory/managedObjects/<<deviceId>>/<<references>>/<<referenceId>>

応答例

ヘッダー
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 - マネージドオブジェクトリファレンスの削除

リクエスト本体: N/A

応答メッセージ本体: N/A

要求されるロール: ROLE_INVENTORY_ADMIN または 親または子のオーナー

備考: このオペレーションはリファレンスのみを削除します。オブジェクト自体は削除しません。

リクエスト例 - マネージドオブジェクトリファレンスを削除する

ヘッダー
Authorization {{auth}}
DELETE /inventory/managedObjects/<<deviceId>>/<<references>>/<<referenceId>>

応答例

HTTP/1.1
204 - NO CONTENT

通知

インベントリ通知はインベントリ内での変更のモニタリングを許可します(作成、更新および削除)。

通知を受信するための基本プロトコルは「リアルタイム通知」セクションに記載されています。

URLは以下の通りです:

    /cep/realtime

インベントリに関するすべての通知を受信するには、チャネル接続に、モニタリングされるべきインベントリ内のマネージドオブジェクトID、またはプレースホルダーとして「 * 」を含む必要があります。

    /managedobjects/<<managedObjectId>>

さらに、マネージドオブジェクトの応答には「realtimeAction」が含まれ、指定されたオブジェクトになったアクション(CREATE、UPDATE、またはDELETE)を識別します。削除(DELETE)の場合、データは、削除されたマネージドオブジェクトのIDのみ包含することになります。

要求されるロール: ROLE_INVENTORY_READ

応答例

ヘッダー
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"
  }
]