基本機能

アプリケーションの開発

EPLアプリは、モニタ(*.mon)ファイルです。EPLアプリは、次の2つの方法で開発できます。

コンセプトガイドイベント処理言語(EPL)の使用もご覧ください。

備考
Software AG Designer は Software AG 社の製品であり、サポート対象外となります。予めご了承ください。

ストリーミング分析アプリケーションを使用したアプリケーションの開発

ストリーミング分析アプリケーションは、新規または既存のEPLアプリ(*.mon ファイル)をインタラクティブに編集したり、EPLアプリをインポートおよび有効化(デプロイ)したりするためのインターフェースを提供します。

EPLアプリのページを利用するテナントのユーザーは、CEPマネージャーである必要があります。ユーザーガイド管理 > 権限の管理をご覧ください。

備考
ストリーミング分析アプリケーションを使用してEPLアプリを開発したり、後述「Software AG Designerを使用したアプリケーションの開発」の方法でSoftware AG DesignerからThings Cloudにインポートしたりするには、Things Cloudが提供する「Apama-ctrlマイクロサービス」と「ストリーミング分析」アプリケーションの両方をテナントに登録する必要があります。Apamaスマートルール専用マイクロサービスをお持ちの場合、ストリーミング分析アプリケーションはアプリケーションメニューで使用できません。この機能のご利用にはカスタムストリーミング処理機能のお申し込みが必要となります。

ステップ 1 - ストリーミング分析アプリケーションの呼び出し

アプリケーションメニューを開き、ストリーミング分析のアイコンをクリックします。そして、EPLアプリページに移動します。

EPLアプリページへ移動すると、EPLアプリマネージャが最初に表示され、既存のEPLアプリが一覧表示されます。各アプリケーションはカードとして表示されます。ここでは新しいEPLアプリを追加したり、既存のEPLアプリを管理できます。

EPLアプリ

アプリケーション用に表示される各カードの上部には、アプリケーションを編集、エクスポート、削除できるアクションメニューがあります。

このページでは次のことができます:

ステップ 2 - EPLアプリの作成

上部のメニューバーで新規EPLアプリをクリックします。アプリケーションに固有の名前を付けます。新規アプリケーション用に作成されるカード上に表示する説明を入力することもできます。

EPLエディターが次に表示されます。新規アプリケーションのEPLコードには、Things Cloud での作業に必要な典型的な基本イベント定義とユーティリティが既に含まれています。これらは、アプリケーションの要件に応じて調整できます。詳細については、ドキュメントとサンプルを参照してください。

EPL editor

始めるにあたり、いくつかのサンプルが利用可能です。それらを表示するには、エディターの右側に表示されるサンプルをクリックします。サンプルをクリックすると、その内容のプレビューが表示されます。サンプルコードの一部を選択し、標準のキーの組み合わせ(Ctrl+C と Ctrl+V)を使用して、独自のコードにコピーできます。また、コマンドボタンを使用して、コード全体をクリップボードにコピーし、独自のコードの適切な位置に挿入したり、既存のすべてのコードをサンプルコードに置き換えたりすることもできます。

トップメニューバーのボタンを使用して、現在のセッションの最新の変更を 元に戻る/やり直し することができ、変更を保存できます。

EPLエディターでモードを無効から有効(またはその逆)に変更することもできます。繰り返しますが、EPLコードにエラーがある場合、アプリケーションを有効化することはできません。エラーはコード内で強調表示されます。

EPLアプリを作成(またはインポート)する際には、次の点に注意してください。EPLアプリがアクティブになると、そのアプリケーションを作成したユーザーには許可されていない一部のEPLオペレーションが実行される可能性があります。たとえば、EPLの注入と分析モデルの作成では、「CEP管理」の管理者権限しかない場合があります。ただし、アプリケーションがアクティブになると、注入されたEPLがアラームを作成またはクリアしたり、分析モデルがオペレーションを作成したりする可能性もあります。

備考
EPLエディターは標準のWebコンポーネントを使用することに注意してください。多くの汎用開発者機能を提供しますが、その中には、Quick FixやShow Hoverなど、EPLに関連しないものも含まれます。

上部のメニューバーの×をクリックしてEPLエディターを終了し、EPLアプリ一覧に戻ります。

注意
別のURLへ移動したり、ブラウザーウィンドウを閉じると、保存されていない変更はすべて失われます。

ステップ 3 - EPLアプリの検証

アプリケーションを有効にすると、実行中の結果を確認できます。これには、メジャーメントの送信、データの受信、アラームの作成、Apama-ctrlマイクロサービスへのロギングが含まれます。Apama-ctrlマイクロサービスのログファイルを確認するには、ユーザーガイド管理 > マイクロサービスの管理と監視をご覧ください。

アプリケーションのデプロイもご覧ください。

Software AG Designerを使用したアプリケーションの開発

注意: Software AG Designer は Software AG 社の製品であり、サポート対象外となります。予めご了承ください。

Software AG Designerは完全な開発環境を提供し、複雑なEPLアプリを作成する場合に最適なツールです。EPLアプリ(モニターファイル)の準備ができたら、Things Cloudにインポートする必要があります。

ステップ 1 - Apamaをインストール

Apamaのライセンスを取得している場合は、Software AG Installerを使用してインストールします。

制限された機能といくつかの制約内で実行されるApamaのフリーミアムバージョンを使用することもできます。これを使用する場合は、https://www.apamacommunity.com/downloads/ からApama Community Editionをダウンロードしてインストールします。

ライセンスバージョンとフリーミアムバージョンの両方に、Software AG Designerが含まれています。

ステップ 2 - プロジェクトの作成

インストールしたら、Software AG DesignerでApamaプロジェクトを作成し、Things Cloud接続性を有効にします。Apamaプロジェクトの作成方法については、Apamaドキュメント内の Creating Apama Projects をご覧ください。

ステップ 3 - プロジェクトにApamaバンドルを追加

次のApamaバンドルを、新しく作成されたApamaプロジェクトに追加します。これらは、Things Cloudがアプリケーションを有効化できるようにするために必要です。プロジェクトにバンドルを追加する方法については、Apamaドキュメントの Adding bundles to projects をご覧ください。

EPLアプリで許可されるのは上記のバンドルのみです。他のバンドルを追加しないように注意してください。追加すると、Things Cloudで有効にしたときにアプリケーションが機能しない場合があります。

ステップ 4 - モニターファイルの作成

新規のApama モニターファイルを作成するにはApamaドキュメントの Creating new monitor files for EPL applications をご覧ください。

新しく作成したモニタファイルをEPLアプリとしてThings Cloudにインポートして有効化する前に、このモニタファイルがSoftware AG Designer内で想定どおりに機能するかどうかを検証します。

詳細についてはApamaドキュメントの The Cumulocity IoT Transport Connectivity Plug-in をご覧ください。

ステップ 5 - モニタファイルの実行と検証

プロジェクトをローカルで実行する場合、プロジェクトの構成設定でThings Cloud認証情報を提供する必要があります。Things Cloudクライアントにある CumulocityIoT.properties ファイルで認証情報を構成設定します。例えば:

CUMULOCITY_USERNAME=user@example.com
CUMULOCITY_SERVER_URL=http://exampleTenant.je1.thingscloud.ntt.com 
CUMULOCITY_PASSWORD=examplePassword
CUMULOCITY_APPKEY=apamaAppKey
備考
CUMULOCITY_APPKEYの値を得るためには、Things Cloudでアプリケーションの管理をする必要があります。

上記の説明は、URLがテナントを識別しているテナントに接続していることを前提としていることを注記してください。そうでない場合(たとえば、IPアドレスで接続している場合)、CumulocityIoT.propertiesファイルで次を設定する必要があります:

CUMULOCITY_TENANT=my_custom_tenant

これで、Software AG DesignerでEPLの検証を進めることができます。

EPLアプリの準備がでたら、EPLアプリを単一の*.monファイルとしてインポートをするために、アプリケーションのデプロイをご覧になり、Things Cloudへのデプロイ方法を確認ください。

アプリケーションのデプロイ

以下をThings Cloudにデプロイできます。

備考
ストリーミング分析アプリケーションでは、「有効化(activate)」という用語はアプリのデプロイに使用されます。

Apama EPL Appsを使用してEPLアプリを単一の *.mon ファイルとしてデプロイする

備考
ストリーミング分析アプリケーションで単一の*.monファイルをデプロイできるようにするには、Things Cloudで提供されるApama-ctrlマイクロサービスと、ストリーミング分析アプリケーションの両方をテナントが購読する必要があります。Apamaスマートルール専用マイクロサービスを使用している場合、ストリーミング分析アプリケーションはアプリケーションメニューでは使用できません。この機能を使用する場合は、カスタムストリーミング処理機能オプションをお申し込みください。

EPLアプリ(つまり、*.mon file)がThings Cloudで有効化されると、*.monファイルには一意のパッケージ名が割り当てられます。これにより、複数のモジュールが有効化されたときの競合を防ぎます。このため、*.monファイルで packageステートメントを指定しないでください。アプリケーションの異なる部分間でイベントを共有する必要がある場合は、単一の*.monファイルでイベント定義とそれを使用するモニターを作成します。

EPLアプリで利用できる制限されたユーティリティと基本イベントのセットがあります。このドキュメント執筆時点では、これらに Time Format および HTTP Client > JSON with generic request/response event definitions が含まれています。

EPLアプリがランタイムエラーを通知すると、アラームが発生します。ランタイムエラーには、検知されなかった異常、およびEPLアプリによる明確な警告・エラーのロギングが含まれます。一般的にApamaランタイムに関連する動作や状態の問題もアラームとして発生します。

ApamaランタイムおよびアクティブなEPLアプリの詳細な診断については、Apama-ctrlマイクロサービスのログで確認できます。ログファイルの詳細については、ユーザーガイド管理 > マイクロサービスの管理と監視をご覧ください。ただし、Apamaログファイルを最大限に活用するには、Apamaにある程度精通している必要があります。

アプリをテストする

GitHub の Apama EPL アプリツールを使用して、EPL アプリのアップロードをスクリプト化し、CI/CD (継続的インテグレーションおよび継続的デリバリー) ユースケースに合わせて管理できます。このツールは、PySys テストフレームワークへの拡張機能も提供し、EPL アプリのテストを簡単に作成して自動的に実行できるようにします。

Apama EPL Apps Tools は、https://github.com/SoftwareAG/apama-eplapps-tools から入手できます。詳細については、GitHub のドキュメント を参照してください。

PySys の詳細については、Apama ドキュメントからアクセスできる Python の API リファレンス を参照してください。

備考
上記のツールは Software AG 社の提供するツールであり、サポート対象外となります。予めご了承ください。

サポートされるRESTサービス

EPLアプリはREST(Representational State Transfer)サービスをリッスンし、すべてのGET、POST、PUT、DELETEオペレーションをサポートするよう設計されています。さまざまなオペレーションに対するリクエストの例を次に示します。

これらのオペレーションを実行するには、「CEP管理」の読み取りおよび管理者権限が必要です。(ユーザーガイド管理 > 権限の管理もご覧ください。).

備考
このAPIにはApama-ctrlマイクロサービスのバージョン10.6.0以上が必要です。

すべてのオペレーションに対するリクエストヘッダー

各リクエストは、Things Cloudに対して認証される必要があります。

名前 説明
Accept “application/json” (これは必須パラメーターです)

共通レスポンスコード

次の一般的なエラーレスポンスコードは、すべてのリクエストで予想されます。

コード 説明
401 リクエストが認可されていません。
403 リクエストが禁止されています。

特定のリクエストから期待できるその他のレスポンスコードを以下に示します。

共通フィールドの説明

レスポンスでは、オペレーションに応じて次の共通フィールドを使用できます。

フィールド 説明
contents EPLファイルの全内容
description ファイルの説明
eplPackageName EPLファイルのパッケージ名。名前に特殊文字(スペースを含む)が含まれている場合、これらの文字はエスケープされて有効なEPL識別子になり、インジェクションエラーを回避します。
errors ファイル内のすべてのコンパイルエラーのリスト(ある場合)と行番号およびテキスト
id ファイルの一意の識別子
name EPLに付けられた名前
state EPLがコリレーターに注入されて実行されているかどうか。これはactiveまたはinactiveのいずれかになります。
warnings ファイル内のすべてのコンパイル警告のリスト(ある場合)と行番号およびテキスト

GET - 利用可能なすべてのEPLファイルを取得

エンドポイント: /service/cep/eplfiles

リクエストの例

GET /service/cep/eplfiles

レスポンス

コード 説明
200 正常に動作しました。以下の値の例もご覧ください。
400 不正なリクエストです。ヘッダの内容に予期しない値が含まれています。

レスポンスコード200の値の例:

{
  "eplfiles":[
    {
      "description":"",
      "eplPackageName": "eplfiles.Ordinal1",
      "errors":[

      ],
      "id":"39615",
      "name":"Ordinal1",
      "state":"active",
      "warnings":[

      ]
    }
  ]
}

GET - 利用可能なすべてのEPLファイルとその内容を取得

エンドポイント: /service/cep/eplfiles

リクエストパラメータ

名前 説明
contents ブール型。EPLファイルとその内容を取得します。これは任意のクエリパラメータです。

リクエストの例

GET /service/cep/eplfiles?contents=true

レスポンス

コード 説明
200 正常に動作しました。以下の値の例もご覧ください。

レスポンスコード200の値の例:

{
  "eplfiles":[
    {
      "contents":"monitor M0 { action onload() { on wait(1.0) { log \"Hello\" at INFO; }}}",
      "description":"",
      "eplPackageName": "eplfiles.Ordinal1",
      "errors":[
      ],
      "id":"39615",
      "name":"Ordinal1",
      "state":"active",
      "warnings":[
      ]
    }
  ]
}

GET - 識別子でEPLファイルを取得

エンドポイント: /service/cep/eplfiles/{id}

リクエストパラメータ

名前 説明
id 取得するEPLファイルの識別子。これは必須パラメータです。

リクエストの例

GET /service/cep/eplfiles/{{id}}

レスポンス

コード 説明
200 正常に動作しました。以下の値の例もご覧ください。
404 識別子のファイルが見つかりません。このセクションの最後にあるレスポンスコードのサンプル値もご覧ください。

レスポンスコード200の値の例:

{
      "contents":"monitor M0 { action onload() { on wait(1.0) { log \"Hello\" at INFO; }}}",
      "description":"",
      "eplPackageName": "eplfiles.Ordinal1",
      "errors":[
      ],
      "id":"39615",
      "name":"Ordinal1",
      "state":"active",
      "warnings":[
      ]
}

POST - 新しいEPLアプリケーションを作成

エンドポイント: /service/cep/eplfiles

リクエストの例

POST /service/cep/eplfiles

リクエストボディーの例を次に示します。

{
  "name": "Ordinal1",
  "contents": "monitor M1 { action onload() { on wait(1.0) { log \"Hello\" at INFO; }}}",
  "state": "active",
  "description": ""
}

以下を注記してください:

レスポンス

コード 説明
201 正常に作成されました。/ 作成されましたが、ファイルにエラーがあります。/ 作成されましたが、ファイルに警告があります。以下の例もご覧ください。
405 入力に誤りがあります。

正常に作成された場合のレスポンスコード201の例:

{
  "description":"",
  "eplPackageName": "eplfiles.Ordinal1",
  "errors":[

  ],
  "id":"39615",
  "name":"Ordinal1",
  "state":"active",
  "warnings":[

  ]
}

警告またはエラー付きで作成された場合のレスポンスコード201の例:

{
  "description":"",
  "eplPackageName": "eplfiles.Ordinal1",
  "errors":[
    {
      "line":5,
      "text":"assigning a float to an integer variable"
    }
  ],
  "id":"39651",
  "name":"Ordinal1",
  "state":"inactive",
  "warnings":[
    {
      "line":10,
      "text":"\"assert\" may become a reserved word in future versions of EPL"
    }
  ]
}

PUT - EPLファイルを識別子で更新

エンドポイント: /service/cep/eplfiles/{id}

リクエストパラメータ

名前 説明
id 更新するEPLファイルの識別子。識別子はパスに含める必要があります。これは必須パラメータです。

リクエストの例

PUT /service/cep/eplfiles/{id}

リクエストボディーの例を次に示します。

{
  "name": "Ordinal1",
  "contents": "monitor M1 { action onload() { on wait(1.0) { log \"Hello\" at INFO; }}}",
  "state": "active",
  "description": ""
}

POSTリクエストに記載されている情報もご覧ください。

レスポンス

コード 説明
200 正常に更新されました。以下の値の例もご覧ください。
404 識別子のあるファイルが見つかりません。このセクションの最後にあるレスポンスコードのサンプル値もご覧ください。

エラーなしで正常に更新された場合のレスポンスコード200の値の例:

{
  "description":"",
  "eplPackageName": "eplfiles.Ordinal1",
  "errors":[

  ],
  "id":"39615",
  "name":"Ordinal1",
  "state":"active",
  "warnings":[

  ]
}

エラーまたは警告で更新された場合のレスポンスコード200の値の例:

{
  "description":"",
  "eplPackageName": "eplfiles.Ordinal1",
  "errors":[
    {
      "line":5,
      "text":"assigning a float to an integer variable"
    }
  ],
  "id":"39651",
  "name":"Ordinal1",
  "state":"inactive",
  "warnings":[
    {
      "line":10,
      "text":"\"assert\" may become a reserved word in future versions of EPL"
    }
  ]
}

DELETE - 識別子でEPLファイルを削除

エンドポイント: /service/cep/eplfiles/{id}

リクエストパラメータ

内容 説明
id 削除するEPLファイルの識別子。識別子はパスに含める必要があります。これは必須パラメータです。

リクエストの例

DELETE /service/cep/eplfiles/{{id}}

レスポンス

コード 説明
200 削除に成功しました。
404 識別子のあるファイルが見つかりません。このセクションの最後にあるレスポンス・コードのサンプル値もご覧ください。

レスポンスコード404の値の例

レスポンスコード404は、特定の識別子を持つファイルが見つからなかったことを示します。

{
  "error":"Not Found",
  "exception":"com.apama.in_c8y.FileNotFoundException",
  "message":"File with id 39613 not found",
  "path":"/eplfiles/39613",
  "status":404,
  "timestamp":"2020-01-17T12:21:42.457+0000"
}

イベントとチャネル

Apama EPLでは、他のThings Cloudエコシステムとのやり取りはイベントを介して行われます。Things Cloudデータにアクセスするための多くのイベント定義が提供されています。

備考
Apama と Things Cloud は異なる「イベント」概念を使用します。Apama イベントは、デバイスのメジャーメント、アラーム、(Things Cloud) イベントの監視と作成など、Things Cloud とのすべてのやり取りに使用されます。Apama イベントの詳細については、Apama ドキュメントの イベントタイプの定義 を参照してください。Things Cloud イベントの詳細については、Things Cloud OpenAPI仕様 の Events を参照してください。

定義済みのイベント型

さまざまなThings Cloud APIとやり取りをするために、いくつかの定義済みイベント型があります。イベントは、新しいメジャーメント、アラームやイベントが作成されると、Apamaアプリケーションに自動的に送信されます。Things Cloudバックエンドとやり取りをするために、イベントを作成して関連するチャネルに送信できます。Things Cloudは自動的に、メールやSMSなどの送信に必要なデータベースクエリを実行するか、APIコールを作成します。

EPL (ApamaDoc)のAPIリファレンスにある データモデル で各ストリームのイベントの構造を確認してください。

チャネルにイベントを送信する

イベントを送信するには、 new <type>でイベントを作成し、その後に各フィールドを割り当てるか、またはすべてのフィールドを指定するコンストラクターを使用します。次に、sendステートメントを使用して、Things Cloudにイベントを送信します。sendステートメントにはチャネルが必要です。これはイベント型のSEND_CHANNEL定数です。

イベントを監視する

チャネルでイベントを監視することにより、EPLをトリガーできます。monitor.subscribe("string name")メソッドでチャネル接続できます。これは、モニターの起動時に実行するか、時々イベントを受信する程度でよければ、必要に応じて呼び出し、その後にmonitor.unsubscribe("string name")を続けます。

onステートメントを使用してイベントを監視し、そして監視しているイベント型に続き、括弧を開いて閉じ、イベントを保持する変数にas <identifier>を指定します。

デフォルトでは、リスナーは一度だけ起動します。すべてのイベントで繰り返し起動させるには、イベント型の前にallキーワードを使用します。

フィルタ

フィルタを追加するには、リスナーのカッコの間に1つ以上のフィールドを指定します。最上位レベルのフィールドのみをフィルタできます。より複雑なフィルタリング、またはイベントのサブプロパティ(たとえば、ディクショナリー内)でのフィルタリングには、ifステートメントを使用します。

標準のイベント型とチャネル

標準のThings Cloudイベントには、イベントを送受信するためのチャネルを含む定数があります。たとえば:

monitor.subscribe(Measurement.SUBSCRIBE_CHANNEL);
send msmnt to Measurement.SEND_CHANNEL;
イベント 送信用チャネル 受信用チャネル
Operation Operation.SEND_CHANNEL Operation.SUBSCRIBE_CHANNEL
Measurement Measurement.SEND_CHANNEL Measurement.SUBSCRIBE_CHANNEL
Event Event.SEND_CHANNEL Event.SUBSCRIBE_CHANNEL
Alarm Alarm.SEND_CHANNEL Alarm.SUBSCRIBE_CHANNEL
ManagedObject ManagedObject.SEND_CHANNEL ManagedObject.SUBSCRIBE_CHANNEL
MeasurementFragment MeasurementFragment.SEND_CHANNEL MeasurementFragment.SUBSCRIBE_CHANNEL

メジャーメントフラグメント

Measurement および MeasurementFragment イベントは常に公開されます。

EPL では、Measurement イベントではなく MeasurementFragment イベントの内容に一致するリスナーを生成できます。

例:

on all MeasurementFragment(type="c8y_SpeedMeasurement", valueFragment = "c8y_speed", valueSeries = "speedX", value > SPEED_LIMIT) as mf {
}

メジャーメントフラグメントもご覧ください。

通知の作成と更新を区別する

Things Cloud からの AlarmEventManagedObject、または Operation イベントをリッスンする場合、作成操作と更新操作を区別することが必要な場合があります。これらのイベントタイプにはそれぞれ、 isCreate() および isUpdate() という名前のアクションがあり、作成と更新の区別に利用できます。

アラーム作成を監視する例:

on all Alarm() as alarm {
    if alarm.isCreate() {
        log "Alarm created: " + alarm.toString() at INFO;
    }
    // else it's an update
}

アラーム更新を監視する例:

on all Alarm() as alarm {
    if alarm.isUpdate() {
        log "Alarm updated: " + alarm.toString() at INFO;
    }
    // else it's a create
}

Things Cloud からのイベントの場合、isUpdate() または isCreate() のいずれかが常に true を返します。 どちらのアクションも、選択肢と読みやすさを考慮して提供されています。

さまざまなタイプのオブジェクトの例などの詳細については、Apama ドキュメントの Receiving update notifications を参照してください。

isCreate() および isUpdate() の詳細については、API Reference for EPL (ApamaDoc) も参照してください。

この例では、MeasurementFragment APIを使用して新しいメジャーメントの値をリッスンします。受信したメジャーメントの値をフィルタ処理して、指定された最大速度を超える速度の値を検索し、制限に違反した場合はアラームを発生します。

  1. MeasurementFragment.SUBSCRIBE_CHANNELチャネル接続します。
  2. メジャーメントフラグメントをリッスンし、type ( c8y_SpeedMeasurement) でフィルタします。valueFragmentの値がc8y_speedであり、valuesSeriesspeedXのみをフィルタ処理することを確認してください。また、valueSPEED_LIMITより大きい場合は、valueでフィルタします。
  3. すべてのフィールドを指定するコンストラクターを使用してイベントを作成します。
  4. イベントを正しいチャネルに送信します。Alarm.SEND_CHANNEL

結果として完成する *.monファイルは次のようになります:

using com.apama.cumulocity.Alarm;
using com.apama.cumulocity.MeasurementFragment;

monitor TriggerAlarmForSpeedBreach {
    constant float SPEED_LIMIT := 30.0;
    action onload() {
        monitor.subscribe(MeasurementFragment.SUBSCRIBE_CHANNEL);
        // Everytime a measurement fragment with the specific details of the match criteria is triggered then we should raise an alarm
        on all MeasurementFragment(type="c8y_SpeedMeasurement", valueFragment = "c8y_speed", valueSeries = "speedX", value > SPEED_LIMIT) as mf {
            send Alarm("", "c8y_SpeedAlarm", mf.source, currentTime,
                        "Speed limit breached", "ACTIVE", "CRITICAL", 1,
                        new dictionary<string,any>) to Alarm.SEND_CHANNEL;
        }
    }
}