イベント

概要

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

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

イベントAPI

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

名称 タイプ 発生回数 説明
self URL 1 このリソースへのリンク
events EventCollection 1 すべてのイベントのコレクション
eventsForType EventCollection URI template 1 特定タイプのすべてのイベントの読み取り専用コレクション(プレースホルダー {type})
eventsForSource EventCollection URI template 1 特定のソースオブジェクトからのすべてのイベントの読み取り専用コレクション(プレースホルダ{source})
eventsForSourceAndType EventCollection URI template 1 特定のタイプおよび特定のソースからのすべてのイベントの読み取り専用コレクション(プレースホルダー{type}と{source})
eventsForTime EventCollection URI template 1 特定期間内すべてのイベントの読み取り専用コレクション(プレースホルダー{dateFrom}、{dateTo})
eventsForFragmentType EventCollection URI template 1 特定のフラグメントタイプを含むすべてのイベントの読み取り専用コレクション(プレースホルダー{fragmentType})
eventsForSourceAndTime EventCollection URI template 1 特定期間内の特定のソースオブジェクトからのすべてのイベントの読み取り専用コレクション(プレースホルダー{source}、{dateFrom}、{dateTo})
eventsForSourceAndFragmentType EventCollection URI template 1 特定のフラグメントタイプを含んだ特定のソースオブジェクトからのすべてのイベントの読み取り専用コレクション(プレースホルダー{source}、{fragmentType})
eventsForDateAndFragmentType EventCollection URI template 1 特定のフラグメントタイプを含んだ特定の期間からのすべてのイベントの読み取り専用コレクション(プレースホルダー{dateFrom}、{dateTo}、{fragmentType})
eventsForFragmentTypeAndType EventCollection URI template 1 特定のフラグメントタイプを含んだ特定のタイプのすべてのイベントの読み取り専用コレクション(プレースホルダー{fragmentType}、{type})
eventsForTimeAndType EventCollection URI template 1 特定期間内の特定のタイプを有するすべてのイベントの読み取り専用コレクション(プレースホルダー{type}、{dateFrom}、{dateTo})
eventsForSourceAnd   DateAndFragmentType EventCollection URI template 1 特定期間内の特定のフラグメントタイプを含む特定のソースオブジェクトからのすべてのイベントの読み取り専用コレクション(プレースホルダー{source}、{dateFrom}、{dateTo}、{fragmentType})
eventsForSourceAnd   DateAndFragmentTypeAndType EventCollection URI template 1 特定期間内の特定のフラグメントタイプを含んだ特定のタイプを有する特定のソースオブジェクトからのすべてのイベントの読み取り専用コレクション(プレースホルダー{source}、{dateFrom}、{dateTo}、{fragmentType}、{type})
eventsForSourceAnd   FragmentTypeAndType EventCollection URI template 1 特定のフラグメントタイプを含んだ特定のタイプを有する、特定のソースオブジェクトからのすべてのイベントの読み取り専用コレクション(プレースホルダー{source}、{fragmentType}、{type})
eventsForSourceAndTimeAndType EventCollection URI template 1 特定期間内の、特定のタイプを有する、特定のソースオブジェクトからのすべてのイベントの読み取り専用コレクション(プレースホルダー{source}、{type}、{dateFrom}、{dateTo})
eventsForDateAnd   FragmentTypeAndType EventCollection URI template 1 特定期間内の特定のフラグメントタイプを含んだ特定タイプからのすべてのイベントの読み取り専用コレクション(プレースホルダー{type}、{dateFrom}、{dateTo}、{fragmentType})

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

応答本体: Event Api

要求されるロール: ROLE_EVENT_READ

リクエスト例: イベントAPIリソースに関する情報を読み出す

GET /event
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx
 Accept: application/vnd.com.nsn.cumulocity.eventApi+json;ver=0.9

応答例:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.eventApi+json;ver=...
Content-Length: ...
{
  "self" : "<<Event API URL>>",
  "events" : {
    "self" :"<<EventCollection URL>>"
  },
  "eventsForType" : "<<EventCollection URL>>?type={type}",
  "eventsForSource" : "<<EventCollection URL>>?source={source}",
  "eventsForTime" : "<<EventCollection URL>>?dateFrom={dateFrom}&dateTo={dateTo}",
  "eventsForFragmentType" : "<<EventCollection URL>>?fragmentType={fragmentType}",
  "eventsForSourceAndType" : "<<EventCollection URL>>?type={type}&source={source}",
  "eventsForSourceAndTime" : "<<EventCollection URL>>?source={source}&dateFrom={dateFrom}&dateTo={dateTo}",
  "eventsForSourceAndFragmentType" : "<<EventCollection URL>>?source={source}&fragmentType={fragmentType}",
  "eventsForDateAndFragmentType" : "<<EventCollection URL>>?dateFrom={dateFrom}&dateTo={dateTo}&fragmentType={fragmentType}",
  "eventsForFragmentTypeAndType" : "<<EventCollection URL>>?fragmentType={fragmentType}&type={type}",
  "eventsForTimeAndType" : "<<EventCollection URL>>?dateFrom={dateFrom}&dateTo={dateTo}&type={type}",
  "eventsForSourceAndDateAndFragmentType" : "<<EventCollection URL>>?source={source}&dateFrom={dateFrom}&dateTo={dateTo}&fragmentType={fragmentType}",
  "eventsForSourceAndDateAndFragmentTypeAndType" : "<<EventCollection URL>>?source={source}&dateFrom={dateFrom}&dateTo={dateTo}&fragmentType={fragmentType}&type={type}",
  "eventsForSourceAndFragmentTypeAndType" : "<<EventCollection URL>>?source={source}&fragmentType={fragmentType}&type={type}",
  "eventsForSourceAndTimeAndType" : "<<EventCollection URL>>?source={source}&dateFrom={dateFrom}&dateTo={dateTo}&type={type}",
  "eventsForDateAndFragmentTypeAndType" : "<<EventCollection URL>>?dateFrom={dateFrom}&dateTo={dateTo}&fragmentType={fragmentType}&type={type}"
}

イベントコレクション

イベントコレクション[application/vnd.com.nsn.cumulocity.eventCollection+json]

名称 タイプ 発生回数 説明
self URI 1 このリソースへのリンク
events Event 0..n イベントのリスト(下記参照)
statistics PagingStatistics 1 ページング統計に関する情報
prev URI 0..1 イベントの前のページへのリンク(あれば)
next URI 0..1 イベントの次のページへのリンク(あれば)

GET - イベントコレクションの取得

応答本体: Event Collection

要求されるロール: ROLE_EVENT_READ

リクエスト例: イベントコレクションに関する情報を読み出す

GET /event/events
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx
 Accept: application/vnd.com.nsn.cumulocity.eventCollection+json;ver=0.9

応答例:

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

{
 "self":"...",
 "events":[
   {
     "id" : "10",
     "self" : "...",
     "creationTime" : "2011-09-06T12:03:27.927+02:00",
     "type" : "com_cumulocity_model_DoorSensorEvent",
     "time" : "2011-09-06T12:03:27.845+02:00",
     "text" : "Door sensor was triggered.",
     "com_othercompany_Extension" : { ... },
     "source":{ "id":"12345", "self": "..." }
   }, {
     "id":"11",
     ...
   }
 ],
 "statistics" : {
    "totalPages" : 2,
    "pageSize" : 5,
    "currentPage : 1
 }
}

POST - 新規イベントの作成

リクエスト本体: Event

応答本体: Event

要求されるロール: ROLE_EVENT_ADMIN またはソースオブジェクトの所有権

リクエスト例: 新規イベントを作成する

POST /event/events
Host: ...
Authorization: Basic ...
Content-Length: ...
Content-Type: application/vnd.com.nsn.cumulocity.event+json;ver=...

{
  "time" : "2011-09-06T12:03:27.845+02:00",
  "type" : "com_cumulocity_model_DoorSensorEvent",
  "text" : "Door sensor was triggered.",
  "source": { "id" : "12345", ... }
}

応答例:

HTTP/1.1 201 Created
Content-Type: application/vnd.com.nsn.cumulocity.event+json;ver=...
Content-Length: ...
Location: <<URL of new event>>

{
  "id" : "10",
  "self" : "<<URL of new event>>",
  "time" : "2011-09-06T12:03:27.845+02:00",
  "creationTime" : "2011-09-06T12:03:27.927+02:00",
  "type" : "com_cumulocity_model_DoorSensorEvent",
  "text" : "Door sensor was triggered.",
  "source" : { "id":"12345", "self ": "..." }
}

POSTリクエストの場合、ソースパラメータにはIDのみが必要です。

新規イベントの「id」と「creationTime」はサーバーによって生成され、応答においてPOSTオペレーションへ返されます。

クエリの dateFrom や dateTo などのようにイベントAPI で範囲クエリを実行する場合は、最新のイベントが最初に返されます。リクエストURLにクエリパラメータrevert=trueを追加して順序を変更することも可能です。多くのユースケースでは、デバイスから送信される最も古いメジャーメントを取得する必要がある場合があります。これは、revertパラメータを「dateFrom」および「dateTo」パラメータと一緒に渡して、結果を日付順にソートすることで実現できます。たとえば、1年前の dateFrom と未来の dateTo を渡します。

PUT - イベントの更新

リクエスト本体: Event

応答本体: Event

要求されるロール: ROLE_EVENT_ADMIN またはソースオブジェクトの所有権

リクエスト例: イベントのテキストを変更

PUT /event/events/<<eventId>>
Host: ...
Authorization: Basic ...
Accept: application/vnd.com.nsn.cumulocity.event+json;ver=...
Content-Type: application/vnd.com.nsn.cumulocity.event+json;ver=...
Content-Length: ...
{
  "text": "Life full of events"
}

応答例:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.event+json;ver=...
{
  "creationTime": "2016-11-08T16:07:40.917+01:00",
  "time": "2014-03-03T12:03:27.845Z",
  "id": "10400",
  "self": ".../event/events/10400",
  "source": {
    "id": "10216",
    "self": ".../inventory/managedObjects/10216"
  },
  "text": "Life full of events",
  "type": "TestAlarm"
}

DELETE - イベントコレクションの削除

DELETEメソッドはイベントコレクションの削除を可能にします。適用可能なクエリパラメータはGETメソッドの場合と同じです。

リクエスト本体: N/A

応答本体: N/A

要求されるロール: ROLE_EVENT_ADMIN

リクエスト例:

 DELETE: /event/events....
 Host: ...
 Authorization: Basic ...

応答例:

HTTP/1.1  204 NO CONTENT

イベント

イベント [application/vnd.com.nsn.cumulocity.event+json]

名称 タイプ 発生回数 説明 PUT/POST
id String 1 イベントを固有に識別します なし
self URI 1 このリソースへのリンク なし
creationTime String 1 イベントがデータベース内で作成された時間 なし
type String 1 このイベントのタイプを識別します POST: 必須 PUT: なし
time String 1 イベントの時間 POST: 必須 PUT: なし
text String 1 イベントを説明するテキスト POST: 必須 PUT: 任意
source ManagedObject 1 イベントの発生源となったマネージドオブジェクト。オブジェクトは「id」、「self」、「name」、「type」のプロパティを含みます POST: 必須 PUT: なし
* Object 0..n イベントの付加的プロパティ POST: 任意 PUT: 任意

GET - イベントの表現の取得

応答本体: Event

要求されるロール: ROLE_EVENT_READ

リクエスト例: イベントに関する情報を読み出す

GET /event/events/<<eventID>>
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx
 Accept: application/vnd.com.nsn.cumulocity.event+json;ver=0.9

応答例:

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

{
  "id" : "10",
  "self" : "...",
  "time" : "2011-09-06T12:03:27.845+02:00",
  "creationTime" : "2011-09-06T12:03:27.927+02:00",
  "type" : "com_cumulocity_model_DoorSensorEvent",
  "text" : "Door sensor was triggered.",
  "source" : { "id":"12345", "self ": "..." }
}

DELETE - イベントの削除

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

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

要求されるロール: ROLE_EVENT_ADMIN またはソースオブジェクトの所有権

リクエスト例: イベントを削除する

DELETE /event/events/<<eventID>>
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx

応答例:

HTTP/1.1  204 NO CONTENT

通知

イベント通知APIを使用すると、特定のデバイスに関するすべてのイベントの更新を受信することができます。 通知を受信するための基本プロトコルは「リアルタイム通知」セクションに記載されています。URLは以下の通りです。

/cep/realtime

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

/events/<<deviceId>>

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

応答例:

HTTP/1.1 200 OK
Content-Type: application/json
[
  {
    "channel": "/events/12345",
    "successful": true,
    "error": "",
    "data": [{
      "realtimeAction": "CREATE",
      "data": {
        "id": "1",
        "self": "...",
        "source": {
          "12345"
        },
        "creationTime": "2011-09-06T12:03:27.927+02:00",
        "text": "event has been triggered"
      }
    }],
    "clientId": "Un1q31d3nt1f13r"
  }
]

要求されるロール: ROLE_EVENT_READ

バイナリの扱い

イベントREST APIでは、イベントに対するバイナリの格納/取得/削除を行うことが可能です。

すべてのイベントには1つのバイナリを添付することができます。

GET - バイナリのダウンロード

要求されるロール: ROLE_EVENT_READ

リクエスト例:

GET <<url>>/event/events/<<eventId>>/binaries
Authorization: Basic <<auth>>

バイナリが存在する場合の応答例:

HTTP/1.1 200 OK
Content-Type: <<content-type>>
Content-Disposition: attachment; filename=”file.txt”
<<content-body>>

バイナリが存在しない場合、一部のみアップロードされている場合、イベントが存在しない場合の応答は以下のようになります。

HTTP/1.1 404 OK
<<error-message>>

POST - バイナリのアップロード

POSTメソッドを使えば、バイナリファイルをイベントの添付ファイルのようにアップロードできます。ファイルは 50MB まで添付可能です。

要求されるロール: ROLE_EVENT_ADMIN

リクエスト例:

POST <<url>>/event/events/<<eventId>>/binaries
Content-Type: <<content-type>>
Content-Length: <<content-lenght>>
Authorization: Basic <<auth>>
<<content-body>>

正常時の応答:

HTTP/1.1 201 Created
Location: <<url>>/event/events/<<eventId>>/binaries
Content-Type: application/vnd.com.nsn.cumulocity.event+json
{
  "self”: “<<url>>/event/binaries/<<eventId>>”,
  “type”: “<<content-type>>”,
  “source”: <<eventId>>,
  “length”: <<content-lenght>>
}

イベントが存在しない場合の応答:

HTTP/1.1 404 NOT FOUND
<<error-message>>

バイナリがすでに存在する場合の応答:

HTTP/1.1 409 CONFLICT
<<error-message>>

対象のイベントは次のフラグメントを含みます:

{
  ...
  “c8y_IsBinary”:  {
    “type”: “<<content-type>>”
  }
  ...
}

POST multipart/form-data - バイナリのアップロード

マルチパートリクエストを利用したアップロードも利用できます。

要求されるロール: ROLE_EVENT_ADMIN

リクエスト例:

POST <<url>>/event/events/<<eventId>>/binaries
Content-Type: multipart/form-data; boundary=--myBoundary
Authorization: Basic <<auth>>

--myBoundary
Content-Type: application/octet-stream
Content-Disposition: form-data; name="file.txt"

<<content-body>>
--myBoundary--

正常時の応答:

HTTP/1.1 201 Created
Location: <<url>>/event/events/<<eventId>>/binaries
Content-Type: application/vnd.com.nsn.cumulocity.event+json
{
  "self”: “<<url>>/event/events/<<eventId>>/binaries”,
  “type”: “application/octet-stream”,
  “name”: “file.txt”,
  “source”: <<eventId>>,
  "length": <<lenght>>
}

POST content-range - バイナリのアップロード

「Content-Range」ヘッダーを利用することで、複数の塊(チャンク)としてファイルをアップロードできます。

「Content-Range」ヘッダーは、「start-stop/length(開始-終了/長さ)」のフォーマットです:

サイズ10の文書をもつ場合、次のようなチャンクを指定できます: 「0-3/*」, 「4-5/*」, 「6-9/10」

1つのチャンクは5MBを超えることはできません。

要求されるロール: ROLE_EVENT_ADMIN

最初のチャンクのリクエスト例:

POST <<url>>/event/events/<<eventId>>/binaries
Authorization: Basic <<auth>>
Content-Type: <<content-type>>
Content-Length: 100
Content-Range: 0-399/*
<<content-body>>

最初のチャンクの応答例:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.event+json
{
  "self”: “<<url>>/event/events/<<eventId>>/binaries”,
  “type”: “<<content-type>>”,
  “range”: “0-399/*”,
  “source”: <<eventId>>
}

対象のイベントは次のフラグメントを持ちます:

{
  ...
  “c8y_IsIncompleteBinary”: {
    “range”: “0-399/*”
  }
  ...
}

最後のリクエストの例:

POST <<url>>/event/events/<<eventId>>/binaries
Authorization: Basic <<auth>>
Content-Type: <<content-type>>
Content-Length: 100
Content-Range: 400-499/500
<<content-body>>

最後のチャンクの応答例:

HTTP/1.1 201 Created
Location: <<url>>/event/events/<<eventId>>/binaries
Content-Type: application/vnd.com.nsn.cumulocity.event+json
{
  "self”: “<<url>>/event/binaries/<<eventId>>”,
  “type”: “<<content-type>>”,
  “source”: <<eventId>>,
  “length”: <<content-lenght>>
}

PUT - 存在するバイナリの置き換え

要求されるロール: ROLE_EVENT_ADMIN

リクエスト例:

PUT <<url>>/event/events/<<eventId>>/binaries
Content-Type: <<content-type>>
Content-Length: <<content-lenght>>
Authorization: Basic <<auth>>
<<content-body>>

正常時の応答:

HTTP/1.1 201 Created
Location: <<url>>/event/events/<<eventId>>/binaries
Content-Type: application/vnd.com.nsn.cumulocity.event+json
{
  "self”: “<<url>>/event/binaries/<<eventId>>”,
  “type”: “<<content-type>>”,
  “source”: <<eventId>>,
  “length”: <<content-lenght>>
}

DELETE - バイナリの削除

要求されるロール: ROLE_EVENT_ADMIN

リクエスト例:

DELETE <<url>>/event/events/<<eventId>>/binaries
Authorization: Basic <<auth>>

応答例:

HTTP/1.1 204 NO CONTENT

バイナリまたはイベントが存在しない場合の応答例:

HTTP/1.1 404 NOT FOUND
<<error-message>>