組み込みアクション

概要

Apama EPLを使用すると、「アクション」と呼ばれる機能を利用できます。すべてのモニターには、少なくとも1つのonloadと呼ばれるアクションがあります。このセクションでは、すぐに使用できる組み込みのアクションについて説明します。

組み込みタイプのアクションについては API Reference for EPL (ApamaDoc) をご覧ください。

Things Cloudのデータを取得する

履歴データを操作するには、次のリクエスト/レスポンスのイベントペアのいずれかを使用してリソースを検索できます。

例：アラームを検索するために、FindAlarm.SEND_CHANNELチャネルに適切なクエリパラメーターを指定したFindAlarmリクエストイベントを送信します。レスポンスとして、「0」または（検索リクエストに一致するリソースの数に応じた）更なるFindAlarmResponseイベントとFindAlarmResponseAckイベントがFindAlarmResponse.SUBSCRIBE_CHANNELチャネルに返されます。マネージドオブジェクト、イベント、メジャーメント、オペレーションを検索する場合も同様の機能が提供されています。

検索対象	リクエスト-レスポンスイベント	例
ManagedObject	FindManagedObject FindManagedObjectResponse FindManagedObjectResponseAck	Example
Alarm	FindAlarm FindAlarmResponse FindAlarmResponseAck	Example
Event	FindEvent FindEventResponse FindEventResponseAck	Example
Measurement	FindMeasurement FindMeasurementResponse FindMeasurementResponseAck	Example
Operation	FindOperation FindOperationResponse FindOperationResponseAck	Example
CurrentUser	CurrentUser GetCurrentUser GetCurrentUserResponse	Example
TenantOption	TenantOption FindTenantOptions FindTenantOptionsResponse	Documentation

Things Cloud REST APIの他の部分の呼び出し

Things Cloud REST APIは、個々のイベントタイプでは含まれない追加機能をいくつか提供しています。 REST APIのその他の部分を呼び出すために、Things Cloud APIのどんな部分の呼び出しにも使用できる汎用のリクエスト-レスポンスAPIが提供されています。

次のリクエスト-レスポンスイベントを使用できます:

GenericRequest
GenericResponse
GenericResponseComplete

備考

Apama-ctrl マイクロサービス、つまりその中のすべての EPL アプリコードは、EPL がインベントリ内のすべてのオブジェクトにアクセスし、ユーザーの詳細を読み取ることを許可する多数の権限で実行されます。これには、ユーザー名、電子メールアドレスなど、個人を特定できる情報が含まれます。

詳細については Things Cloud OpenAPI仕様の RESTの実装と Apamaドキュメントの Invoking other parts of the Cumulocity IoT REST API をご覧ください。

HTTPサービスの呼び出し

RESTとJSONを使用してHTTPサービスとやり取りするには、ファクトリメソッドの1つを使用して HttpTransportインスタンスを作成します。

HttpTransport.getOrCreate(string host, integer port) はHttpTransportを返します
HttpTransport.getOrCreateWithConfiguration(string host, integer port, dictionary <string, string> configurations) はHttpTransport（構成設定 dictionary のキーは、プレフィクスCONFIG_ を持つHttpTransportの定数です）を返します

HttpTransportオブジェクトで、作成メソッドの1つを呼び出して、必要に応じてパスとペイロードを渡し、Request オブジェクトを生成します。

Requestオブジェクトでは、必要に応じてCookie、ヘッダ、クエリパラメーターを設定し、execute(action<Response> callback) でリクエストを呼び出すことができます。モニターにコールバックのアクションの名前を指定すると、リクエストが完了（またはタイムアウト）するときに Responseで呼び出されます。

コールバックでは、ResponseオブジェクトにstatusCodeとpayloadが提供されます。ペイロードのフィールドは、それが提供されている AnyExtractorオブジェクトを介してアクセス可能です。フラグメントへのアクセスに関する情報をご覧ください。

詳細についてはAPI Reference for EPL (ApamaDoc)をご覧下さい。

ユーティリティ関数

フラグメントへのアクセス

paramsディクショナリーを介して大部分のイベントのフラグメントにアクセスすることができます。AnyExtractorオブジェクトは、複数のサブフラグメントを含むオブジェクトからデータを抽出してアクセスするのに役立つように構築できます：

アクション getInteger(string path)は integer を返します。
アクション getFloat(string path)は float を返します。
アクション getString(string path)は string を返します。
アクション getBoolean(string path)は Boolean を返します。
アクション getSequence(string path)は sequence<any> を返します。
アクション getDictionary(string path)は dictionary<any, any> を返します。

JSONパスを使用して、オブジェクト構造内を移動できます。例えば：

string s := AnyExtractor(measurement.params["fragment"]).getString("sub.fragment.object");

"fragment"の例: “c8y_TemperatureMeasurement”.
"sub.fragment.object"の例: “c8y_TemperatureMeasurement.T.Unit”.

「any」値のキャスト

別の方法として、キャストを使用してanyを特定の型に変換します。

string s := <string> measurement.params["strfragment"];

オブジェクトの型が異なる場合、キャスト操作はスローされることに注意してください。

currentTime と TimeFormatter

読み取り専用変数currentTimeを使用して、現在のサーバー時間を取得できます。Apamaは、Unix Epoch（1970年1月1日UTC）からの秒数を使用して時間を処理しています。TimeFormatオブジェクトを使用して、人が読める形式に簡単に変換できます。 TimeFormat オブジェクトは日付や時刻のフォーマット設定や解析に利用できます。

例:

using com.apama.correlator.timeformat.TimeFormat;

monitor Example { 
    action onload { 
        log TimeFormat.format(currentTime, "yyyy.MM.dd 'at' HH:mm:ss") at INFO; 
    }
}

TimeFormat の詳細は Apama ドキュメントの Using the TimeFormat Event Library や API Reference for EPL (ApamaDoc) をご覧ください。

inMaintenanceMode

Util.inMaintenanceMode()関数は、デバイスが現在メンテナンスモードになっているかどうかをすばやく確認する方法です。マネージドオブジェクトをパラメーターとして受け取り、デバイスがメンテナンスモードの場合にtrueとなるブール値を返します。

例:

using com.apama.cumulocity.Measurement;
using com.apama.cumulocity.Event;
using com.apama.cumulocity.FindManagedObject;
using com.apama.cumulocity.FindManagedObjectResponse;
using com.apama.cumulocity.FindManagedObjectResponseAck;

using com.apama.cumulocity.Util;

monitor ExampleMonitor {
  action onload() {
    // Subscribe to Measurement.SUBSCRIBE_CHANNEL to receive all measurements
    monitor.subscribe(Measurement.SUBSCRIBE_CHANNEL);
    monitor.subscribe(FindManagedObjectResponse.SUBSCRIBE_CHANNEL);
    on all Measurement() as m {
      integer reqId := integer.getUnique();
      send FindManagedObject(reqId, m.source, new dictionary<string,string>) to FindManagedObject.SEND_CHANNEL;
      on FindManagedObjectResponse(reqId = reqId, id = m.source) as d and not FindManagedObjectResponseAck(reqId = reqId) {
        if not Util.inMaintenanceMode(d.managedObject) {
          send Event("", "c8y_Event", m.source, currentTime, "Received measurement from active device", new dictionary<string,any>) to Event.SEND_CHANNEL;
        }
      }
    }
  }
}

replacePlaceholders

文字列を作成するには、次のように連結を使用します:

string s:= "An event with the text " + evt.text + " has been created.";

テキストが長くなり、データから動的に設定される値が増える場合、Util.replacePlaceholders()関数を使用します。テキスト文字列で、イベントからのフィールド名でプレースホルダーをマークし、#{}で囲みます。replacePlaceholdersの2番目のパラメーターには、任意のイベントタイプを指定できます。

Utils::replacePlaceholders は、イベントまたはイベントのパラメーターで指定されたフィールド名を検索して、テキスト置換を生成します。 #{X.Y} 型のフィールド名を使用して、イベント内のネストされた構造にアクセスできます。

myMailText := Util.replacePlaceholders("The device #{source} created an event with the text #{text} at #{time}", alarm);

置換文字列が #{source.name}（source.name はマネージドオブジェクト/デバイスの名前）もしくは #{source.c8y_hardware.notes} （ c8y_hardware はマネージドオブジェクトのフラグメント）のような形式である場合、置換するには特別な処理が必要になります。最初の置換後、プレースホルダーのフィールド名を更新し、source の managedObject を使用して Util::replacePlaceholders を再度実行する必要があります。

myMailText := Util.replacePlaceholders("The device #{source} with the serial number #{source.c8y_Hardware.serialNumber} created an event with the text #{text} at #{time}. The device is located at #{source.c8y_Address.street} in #{source.c8y_Address.city}.", alarm);
myMailText := myMailText.replaceAll("#{source.", "#{"); 
myMailText := Util.replacePlaceholders(myMailText, managedObject);