リアルタイムステートメント

概要

下記のAPIは「/platform」でまだ公表されていませんが、URL「/cep」を使用すると入手可能です。

リアルタイムステートメント以下の5つの要素で構成されます。

  • 「cep」APIリソースはURIをモジュールコレクションへ返します。
  • 「モジュールコレクション」リソースはモジュールを読み出し、新規モジュールの作成を可能にします。
  • 「モジュール」リソースは、クエリ、修正、デプロイまたはアンデプロイが可能な個々のモジュールを表わします。

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

モジュールAPI

CepApi[application/vnd.com.nsn.cumulocity.cepApi+json]

名称 種別 発生回数 説明
self URL 1 このリソースへのリンク
modules ModuleCollection 1 すべてのモジュールのコレクション

CepApiリソースをGETする

応答本体:CepApi

要求されるロール:ROLE_CEP_MANAGEMENT_READ

リクエスト例:CepApiリソースコレクションを読み出す

GET /cep
Host: ...
Authorization: Basic ...

応答例:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.cepApi+json;ver=...
Content-Length: ...
{
   "self":"<<CepAPI URL>>",
   "modules":{
      "self":"<<ModuleCollection URL>>"
   }
}

モジュールコレクション

ModuleCollection? [application/vnd.com.nsn.cumulocity.cepModuleCollection+json]

名称 種別 発生回数 説明
self URI 1 このリソースへのリンク
modules Collection 0..n モジュールのリスト(下記参照)
statistics PagingStatistics 1 ページング統計に関する情報
prev URI 0..1 モジュールの潜在的な前のページへのリンク
next URI 0..1 モジュールの潜在的な次のページへのリンク

モジュールコレクションをGETする

応答本体:モジュールコレクション

要求されるロール:ROLE_CEP_MANAGEMENT_READ

リクエスト例:すべてのモジュールのコレクションをGETする

GET /cep/modules
Host: ...
Authorization: Basic ...

応答例:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.cepModuleCollection+json;ver=...
Content-Length: ...
{
  "modules": [
    {
      "id": "67",
      "lastModified": "2018-04-16T00:04:38.041Z",
      "name": "cepLoRaBase",
      "self": "<<module reference URL>>",
      "status": "DEPLOYED"
    },
    {
      "id": "68",
      "lastModified": "2018-04-16T00:09:14.163Z",
      "name": "cepHC",
      "self": "<<module reference URL>>",
      "status": "NOT_DEPLOYED"
    },
    {
      "id": "89",
      "lastModified": "2018-05-02T23:10:46.011Z",
      "name": "testmodule2",
      "self": "<<module reference URL>>",
      "status": "DEPLOYED"
    },
    :
    :
    :
  ],
  "next": "<<URL to next page>>",
  "self": "<<URL to this module collection>>",
  "statistics": {"currentPage":1,"pageSize":5,"totalPages":4}
}

POST - 新規モジュールをステートメント付きで作成する

リクエスト本体:モジュールファイル 応答本体:モジュール ("Accept"ヘッダーが提供される場合) 要求されるロール:ROLE_CEP_MANAGEMENT_ADMIN.

リクエスト例:

POST /cep/modules
Host: ...
Authorization: Basic ...
Content-Length: ...
Content-Type: multipart/form-data

注意: "POST /cep/modules" はマルチパーツのメッセージです。

ファイル例:

module testmodule;
@Name('test1')select * from EventCreated.win:time(1 hour)

@Nameはスキップしても構いません。その場合、Cumulocityプラットフォームがデフォルト名をステートメントに割り当てます。

応答例:

HTTP/1.1 201 Created
Content-Type: application/vnd.com.nsn.cumulocity.cepModule+json;ver=...
{
   "id":"3",
   "lastModified":"2013-06-27T15:37:51.091+02:00",
   "name":"management",
   "self":"http:\/\/localhost:8181\/cep\/modules\/3",
   "status":"DEPLOYED"
}

新規モジュールの「id」と「lastModified」はサーバーにより生成されます。 応答はモジュールデプロイ処理の状態も格納します。

モジュール名はアプリケーションと同一です。

モジュール

Module?[application/vnd.com.nsn.cumulocity.cepModule+json]

名称 種別 発生回数 説明 PUT/POST
id String 1 モジュールを一意に識別します。 いいえ
self URI 1 このリソースへのリンク いいえ
lastModified String 1 モジュールが作成または修正された時間 いいえ
name String 1 モジュール名 POST:必須、PUT:任意
status String 1 モジュールの状態:DEPLOYED、NOT_DEPLOYED(デフォルト) POST:必須、PUT:任意

モジュールをGETする

応答本体:モジュール

要求されるロール:ROLE_CEP_MANAGEMENT_READ

応答例:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.cepModule+json;ver=...
Content-Length: ...
{
   "id":"1",
   "lastModified":"2013-04-08T14:35:29.879+02:00",
   "name":"the_module",
   "self":"<<URL of cepModule>>",
   "status":"NOT_DEPLOYED"
}

ステートメント付きモジュールファイルをGETする

応答本体:プレーンテキスト

要求されるロール:ROLE_CEP_MANAGEMENT_READ

応答例:

HTTP/1.1 200 OK
Content-Type: text/plain
Content-Length: ...

@Name('test1')select * from EventCreated.win:time(1 hour)@Name('test2')select id, count(*) from MyOffOnStream.win:time(1 hour) group by id;

警告:任意のステートメントがThings Cloudプラットフォームからデフォルト名を割り当てられている場合、「@Name」は表示されません。

モジュールを更新する

リクエスト本体:モジュール

応答本体:モジュール(「Accept」ヘッダーが提供される場合のみ)

要求されるロール:ROLE_CEP_MANAGEMENT_ADMIN

リクエスト例:

PUT /cep/modules/<<moduleId>>
Host: ...
Authorization: Basic ...
Content-Type: application/vnd.com.nsn.cumulocity.cepModule+json;ver=...
{
  "name" : "the_module",
  "status" : "DEPLOYED"
}

応答例:

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

モジュールファイルを更新する - ステートメント付きモジュールを修正する

リクエスト本体:モジュールファイル 応答本体:モジュール(「Accept」ヘッダーが提供される場合のみ) 要求されるロール:ROLE_CEP_MANAGEMENT_ADMIN.

応答例:

PUT /cep/modules/<<moduleId>>
Host: ...
Authorization: Basic ...
Content-Length: ...
Content-Type: text/plain

ファイル例:

module testmodule;
@Name('test1')select * from EventCreated.win:time(1 hour)@Name('test2')select id, count(*) from MyOffOnStream.win:time(1 hour) group by id;

応答例:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.cepModule+json;ver=...
{
   "id":"3",
   "lastModified":"2013-06-27T15:37:51.091+02:00",
   "name":"management",
   "self":"http:\/\/localhost:8181\/cep\/modules\/3",
   "status":"DEPLOYED"
}

モジュール修正過程で古いモジュールは削除され、また未デプロイの新規モジュールがデプロイされますので、モジュールIDが変わります。

モジュールをDELETEする

リクエスト本体:N/A

要求されるロール:ROLE_CEP_MANAGEMENT_ADMIN

リクエスト例:モジュールをDELETEする

DELETE /cep/modules/<<moduleId>>
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx

応答例:

HTTP/1.1  204 NO CONTENT

通知

リアルタイム通知は、ステートメントからの出力をほぼ即座に受信することを可能にします。 これはURL「/cep/notifications」にて利用可能です。用法は別文書に記載されています。

要求されるロール:ROLE_NOTIFICATION_READ

接続チャネル名の形式

接続チャネルにはリアルタイムステートメントが定義されるモジュールの名称と、リアルタイムステートメント自体の名称が含まれます。 構造は以下の通りです。

/<<moduleName>>/<<statementName>>

例えば、「alarm」モジュール内のステートメント「overHeatAlarms」からの通知に対してチャネル接続する場合、接続チャネルは以下の文字列となります。

/alarms/overHeatAlarms