イベント

概要

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

  • 「イベントAPI」リソースは、すべてのイベントまたは特定の種別および/または特定のソースデバイスのイベントの読み出しが可能となるよう、イベントコレクションにURIおよびURIテンプレートを返します。
  • 「イベントコレクション」リソースはイベントを読み出し、新規イベントの作成を可能にします。
  • 「イベント」リソースは、クエリおよび削除が可能な個々のイベントを表わします。

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

イベントAPI

EventAPI [application/vnd.com.nsn.cumulocity.eventApi+json]

名称 種別 発生回数 説明
self URL 1 このリソースへのリンク
events EventCollection 1 すべてのイベントのコレクション
eventsForType EventCollection URI template 1 R特定種別のイベントすべてから成る読み取り専用コレクション(プレースホルダ:{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 R特定のフラグメント種別を含む特定種別のイベントすべてから成る読み取り専用コレクション(プレースホルダ:{fragmentType}、{type})。
eventsForTimeAndType EventCollection URI template 1 特定の期間からの特定の種別を有するイベントすべてから成る読み取り専用コレクション(プレースホルダ:{type}、{dateFrom}、{dateTo})。
eventsForSourceAnd ??DateAndFragmentType EventCollection URI template 1 特定の期間からの特定のフラグメント種別を含む特定のソースオブジェクトからのイベントすべてから成る読み取り専用コレクション(プレースホルダ:{source}、{dateFrom}、{dateTo}、{fragmentType})。
eventsForSourceAndDateAndFragmentTypeAndType EventCollection URI template 1 特定の期間からの特定のフラグメント種別を含み、特定の種別を有する特定のソースオブジェクトからのイベントすべてから成る読み取り専用コレクション(プレースホルダ:{source}、{dateFrom}、{dateTo}、{fragmentType}、{type})。
eventsForSourceAndFragmentTypeAndType EventCollection URI template 1 特定のフラグメント種別を含み、特定の種別を有する、特定のソースオブジェクトからのイベントすべてから成る読み取り専用コレクション(プレースホルダ:{source}、{fragmentType}、{type})。
eventsForSourceAndTimeAndType EventCollection URI template 1 特定の期間からの、特定の種別を有する、特定のソースオブジェクトからのイベントすべてから成る読み取り専用コレクション(プレースホルダ:{source}、{type}、{dateFrom}、{dateTo})。
eventsForDateAndFragmentTypeAndType EventCollection URI template 1 特定の期間からの特定のフラグメント種別を含む、特定種別からのイベントすべてから成る読み取り専用コレクション(プレースホルダ:{type}、{dateFrom}、{dateTo}、{fragmentType})。

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

応答本体:イベント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}"
}

イベントコレクション

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

応答本体:イベントコレクション 要求されるロール: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 - 新規イベントの作成

リクエスト本体:イベント

応答本体:イベント

要求されるロール:ROLE_EVENT_ADMIN or ソースオブジェクトのオーナー

リクエスト例:新規イベントの作成

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", ... }
}
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 ": "..." }
}

応答例:

HTTP/1.1 201 Created
Content-Length: ...

POSTリクエストの場合、ソースパラメータはIDのみ有することを要求されます。

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

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

PUT - イベントの更新

リクエスト body: Event

応答 body: Event

要求されるロール: ROLE_EVENT_ADMIN または、オブジェクトのオーナー

リクエスト例: イベントの text の変更

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

イベント

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

応答本体:イベント

要求されるロール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 or owner of source object.

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

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)。削除の場合、データは、削除されるイベントの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>>

要求されるロール:ROLE_EVENT_ADMIN

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

対象のイベントには次の fragment を持ちます:

{
  ...
  “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」ヘッダーは、「開始-終了/長さ」フォーマットです:

  • 「開始」 は 0 ではじまりアップロードファイルの開始を表します。
  • 「終了」はファイルの終わりを表します(数値を含みます)。
  • 「長さ」は全体の文書の数を表します。この数値は最後のファイルのチャンクでのみ必須です。他の場合、「*」とします。

サイズ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>>
}

対象のイベントは次の fragment を持ちます:

{
  ...
  “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>>