インベントリ

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

概要

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

  • 「インベントリAPI」リソースは、すべてのオブジェクト、特定種別のすべてのオブジェクトおよび特定の能力を有するすべてのオブジェクトのクエリが可能となるよう、マネージドオブジェクトコレクションにURIおよびURIテンプレートを返します。
  • 「マネージドオブジェクトコレクション」リソースはマネージドオブジェクトのセットを読み出し、新規マネージドオブジェクトの作成を可能にします。
  • 「マネージドオブジェクト」リソースは、クエリおよび削除が可能な個々のマネージドオブジェクトを表わします。
  • 「マネージドオブジェクトリファレンスコレクション」リソースは、マネージドオブジェクトに対するリファレンスのセットを読み出します。 これらは例えば特定のマネージドオブジェクトの子デバイスである可能性もあります。 また、コレクションに対する新たなリファレンスの追加(例:新規子デバイスの追加)も可能にします。
  • 「マネージドオブジェクトリファレンス」リソースは、読み出しまたは削除が可能な、マネージドオブジェクトに対する1つの個別のリファレンスを表わします。

注記:すべてのPUT/POSTリクエストについて、acceptヘッダーを使用すべきであり、さもなければ空の応答本体が返されます。

インベントリAPI

インベントリAPI [application/vnd.com.nsn.cumulocity.inventoryApi+json]

名称 種別 発生回数 説明
self URL 1 このリソースへのリンク
managedObjects ManagedObjectCollection 1 すべてのマネージドオブジェクトコレクション
managedObjectsForType ManagedObjectCollection URIテンプレート 1 R特定種別のマネージドオブジェクトすべてから成る読み取り専用コレクション(プレースホルダ:{type})。
managedObjectsForFragmentType ManagedObjectCollection URIテンプレート 1 特定のフラグメント種別または能力を有するマネージドオブジェクトすべてから成る読み取り専用コレクション(プレースホルダ:{fragmentType})。
managedObjectsForListOfIds ManagedObjectCollection URIテンプレート 1 所定のIDリストについてフェッチされたマネージドオブジェクトから成る読み取り専用コレクション(プレースホルダ:{ids})(例:「?ids=41,43,68」)。
managedObjectsForText ManagedObjectCollection URIテンプレート 1 所定のテキストから始まるテキスト値を含むマネージドオブジェクトから成る読み取り専用コレクション(プレースホルダ:{text})。 テキスト値はラテン文字から始まる任意の英数字である(A-Zまたはa-z)。

インベントリAPIリソースをGETする

応答本体:application/vnd.com.nsn.cumulocity.inventoryApi+json 要求されるロール:ROLE_INVENTORY_READ

インベントリAPIリソースをGETする

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 マネージドオブジェクトの潜在的な次のページへのリンク

ManagedObjectCollectionをGETする

応答本体: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" : "..."}

クエリによってManagedObjectCollectionをGETする

応答本体:ManagedObjectCollection 要求されるロール:ROLE_INVENTORY_READ

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

GET /inventory/managedObjects?query=<<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'パラメータを介してクエリをPUTすることができます。 以下のパラメータを使用できます。
  • only query to 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'においてアプリケーションがクエリを処理する方法を説明します。

サポートされるクエリオペレーション
  • 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) - オブジェクトをプロパティ名と照合します
  • bygroupid(12) - IDが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]
クエリ演算子のグルーピング
ソートオペレーション
  • 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
    }
}

クエリは以下を返します。

...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(name) - return all 4 rows

POST - 新規ManagedObjectを作成する

リクエスト本体:ManagedObject

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

要求されるロール:ROLE_INVENTORY_ADMINまたは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オペレーションへ返されます。

マネージドオブジェクト

マネージドオブジェクト [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 特定のManagedObjectに付随する付加的プロパティ。 オプション
lastUpdated TimeStamp 1 オブジェクトが最後に更新された時間。 なし
childDevices ManagedObject ReferenceCollection 0..1 子デバイスに対するリファレンスのコレクション なし
childAssets ManagedObject ReferenceCollection 0..1 子アセットに対するリファレンスのコレクション。 なし
deviceParents ManagedObject ReferenceCollection 0..1 デバイスの親オブジェクトに対するリファレンスのコレクション。 なし
assetParents ManagedObject ReferenceCollection 0..1 アセットの親オブジェクトに対するリファレンスのコレクション。 なし

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

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

すべてのGET応答が「親」コレクションを含むとは限りません。 「親」を含むには「withParents=true」のクエリパラメータを渡す必要があります。

マネージドオブジェクトをGETする

応答本体: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する

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

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

マネージドオブジェクトのサポート対象シリーズをGETする

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

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

応答例:

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

リクエスト例:マネージドオブジェクトの名称を変更する

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'、活動'Smart rule updated'、'Smart rule enabled'または'Smart rule disabled'の監視記録が作成されます。

マネージドオブジェクトをDELETEする

Rリクエスト本体:N/A

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

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

リクエスト例:マネージドオブジェクトをDELETEする

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する

応答本体: ManagedObjectReferenceCollection

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

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

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

リクエスト本体: ManagedObjectReference

応答本体: ManagedObjectReference

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

リクエスト例:ManagedObjectReferenceを追加する

POST /inventory/managedObjects/<<deviceId>>/<<references>>
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",
    ...
  }
}

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

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

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

ManagedObjectReference [application/vnd.com.nsn.cumulocity.managedObjectReference+json]

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

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

応答本体: 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",
    ...
  }
}

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

リクエスト本体:N/A

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

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

注記:このオペレーションはリファレンスを削除するだけです。オブジェクト自体は削除しません。

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

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

応答例:

HTTP/1.1  204 NO CONTENT

通知

インベントリ通知はインベントリ内での変更のモニタリングを許可します(作成、更新および削除)。 通知を受信するための基本プロトコルは「リアルタイム通知」セクションに記載されています。 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