Gravio HubKit マニュアル

Gravio アクションフロー開発ガイド

目次

1. アクション構成ビューの概要

アクション構成ビューでは、トリガーによって実行されるプログラムを記述することができます。このプログラムを「アクション」と呼びます。

典型的な利用シナリオでは、センサーデータが複数のアクションをトリガして、それらのアクションに複数のパラメータを渡します。

アクションを作成または編集するには、以下の手順に従います： 1. サーバーの概要画面に進みます 2. サーバーカードの下端にある中間のアイコンをクリックします 3. 表示されたUIから、左上のメニューの「+」マークをクリックしてアクションを追加します

2. アクションの作成手順

新しいアクションを作成するには：

  1. エッジサーバー内のアクション構成ビューの右上にある「+」記号をクリックします
  2. 新しいアクションを保存するアクションファイルの名前を入力します（例：NewAction.acs）
  3. OKボタンを押すと、新しいアクションファイルが登録されリストに表示されます
  4. そのアクションファイルをダブルクリックするとアクションエディタが開きます

アクションエディタでは、実行されるシーケンス内で左から右に並べる「ステップ」でアクションを構成します。

新しいステップを追加するには： 1. 右上の「+」アイコンをクリックします 2. 「アクションコンポーネントライブラリ」から新しいアクションコンポーネントを選択します 3. コンポーネントを選択すると、ステップを構成してその変数にアクセスしたり、処理したりする設定画面が表示されます

3. アクション内で利用できる変数と変数型

アクションプログラム内では、以下の種類の変数を利用できます：

アクションプロパティ (Action Property)

アクション変数 (Action Variable)

コンポーネントプロパティ (Component Property)

コンポーネント変数 (Component Variable)

トリガー変数 (Trigger Variable)

トリガープロパティ (Trigger Property)

変数の型と型変換

利用可能な変数型は以下の通りです：

変数型 説明
Int 整数
Double 浮動小数点
String 文字列
Bool true/false
DateTime 日時
バイト列 バイト列
配列 配列
Object オブジェクト

各型からは別の型への変換が可能です。変換ルールは以下のように定義されています：

演算子

アクションプログラム内では、以下の演算子が使用できます：

算術演算子： - + 加算 - - 減算 - * 乗算 - / 除算 - ** べき乗 - & ビット論理積（AND） - | ビット論理和（OR） - ^ ビット排他的論理和（XOR） - % 剰余

比較演算子： - > より大きい - >= 以上 - < より小さい - <= 以下 - == 等価 - != 不等価 - =~ 正規表現マッチ - !~ 正規表現非マッチ

論理演算子： - || 論理OR - && 論理AND

4. Objectデータの参照方法

アクション内でObject型変数の値を参照する場合、ドット記法または角括弧記法を使用します。

例えば、以下のようなJSONデータがある場合：

{
  "id": "XXXXXX",
  "source": {
    "channel": 4,
    "bacId": "YYYYYY"
  },
  "common": {
    "description": "Face Recognition",
    "time": "2019-06-17T07:53:22.986Z"
  },
  "fr": {
    "candidates": [
      {
        "customId": "00001",
        "displayName": "Person B",
        "similiarityScore": "0.7272"
      }
    ]
  }
}

fr.candidates[0].displayNameを参照するには、以下のいずれかの方法を使用できます：

tv.Data.fr.candidates[0].displayName

または、キー名にスペースやハイフンなどが含まれている場合は：

tv.Data["fr"]["candidates"][0]["displayName"]
tv.Data.fr.candidates[0]["display Name"]  // スペースを含むキー名の場合

これらのアクセス方法は、アクションの条件式などでも使用できます：

cv.Payload.fr.candidates[0].displayName == "Person B"

さらに、トリガー条件でもこれらの式を利用できます。例えば、IVARの条件で男性のみアクションを起動する場合：

tv.Data.iod.gender == "MALE"

5. アクションコンポーネントの動作

アクションコンポーネントでは入力ペイロード(cv.Payload)と出力ペイロード(cv.Payload)というコンポーネント変数が用意されています。

入力ペイロード

出力ペイロード

6. Pre Mappings / Post Mappingsの使い方

Action Editor画面でコンポーネントを選択すると、右側にPre Mappings / Post Mappingsの編集エリアが表示されます。

式の記述方法

  1. 「+」ボタンを押すと入力フィールドが表示されます
  2. 左側に変数名、右側に変数に代入する式を記述します
  3. 例: cp.Color = "Blue"

式には以下を記述できます： - 四則演算（+, -, *, /） - 関数 - 変数（tp.〜, tv.〜, ap.〜, av.〜, cp.〜, cv.〜 など）

右辺の式の評価結果の型は左辺の型に自動変換されます。

比較演算子を使って真偽値を返すこともできます： - 例: cv.Payload > 10 - 例: cv.Payload == "abc"

利用可能な関数

Pre Mappings / Post Mappingsの式で利用できる関数群：

文字列関係： Len, Contains, RuneCount, HasPrefix, HasSuffix, Index, Join, LastIndex, Repeat, Replace, Split, ToLower, ToUpper, Trim, TrimLeft, TrimRight, TrimPrefix, TrimSuffix

型変換関係： ToBool, ToInt, ToFloat, ToString, ToDate, ToBinary, ToJSON

エンコード関係： URLPathEscape, URLPathUnescape, URLQueryEscape, URLQueryUnescape, MD5, SHA1, SHA256, BASE64, DecodeBASE64, BASE64URL, DecodeBASE64URL

日付関係： Now, Year, Month, Day, Hour, Minute, Second, Weekday, ToLocal, ToUTC, ToTimezone, DateFormat, DateParse

環境変数： Env

正規表現： RegExpMatch, RegExpFind, RegExpFindSubmatch, RegExpFindAll, RegExpReplace, UUID

7. アクションの実行フローとデバッグ

デバッグログ出力

コンポーネントの左上のボタンを押すことで、デバッグログを出力できます。デバッグログには、tp/tv/ap/av/cp/cvのプロパティと変数の値が表示されます。

アクションプログラムの処理順序

アクションプログラムは以下の順序で処理されます：

  1. Payloadを含むコンポーネント変数をキューから取得する
  2. 前のコンポーネントから渡されたPostMappingsの値がある場合は代入処理が行われる
  3. PreMappingsの式評価、値代入が行われる
  4. プロパティに応じでコンポーネントが処理を実行する
  5. コンポーネントの処理結果に応じて、新たなPayloadを含むコンポーネント変数を作成する
  6. PostMappingsの式評価が行われ、結果の値は新たなPayloadを含むコンポーネント変数に保管される
  7. 次のコンポーネントのキューに新たなPayloadを含むコンポーネント変数を渡す
  8. 処理を繰り返す（1に戻る）

デバッグログ機能をONにすると、3のPreMappingsの式評価・代入が行われた後の変数の内容が出力されます。これにより、各ステップでの変数の状態を確認できます。

なお、通常はコンポーネントが独立して並行に動作しますが、デバッグログを出力しながらアクションを実行する場合は、アクションエンジン内で同期処理が行われます。

8. ファイルパスの記述方法

コンポーネントプロパティに指定するファイルは様々な形式でファイルパスを指定することができます。以下では、それぞれのケースでの記述方法を説明します。

ファイルパスを指定しないファイルの参照/保存先

ファイルパスを指定しないファイルの参照/保存先は、OSによって異なります：

さまざまなファイルパスの指定方法

1. dataフォルダ内のファイル

Windows以外の場合

ファイルパス 説明
sample.txt actmgr/dataフォルダー内の sample.txt を指定しています
./sample.txt actmgr/dataフォルダー内の sample.txt を指定しています

Windowsの場合

ファイルパス 説明
sample.txt actmgr/dataフォルダー内の sample.txt を指定しています
.\sample.txt actmgr/dataフォルダー内の sample.txt を指定しています

2. dataフォルダからの相対パスのファイル

Windows以外の場合

ファイルパス 説明
../../../../gravio/sample.txt actmgr/dataフォルダーから4階層上の gravio/sample.txt を指定しています

Windowsの場合

ファイルパス 説明
..\..\..\..\gravio/sample.txt actmgr/dataフォルダーから4階層上の gravio\sample.txt を指定しています

3. 絶対パスのファイル

Windows以外の場合

ファイルパス 説明
/home/gravio/sample.txt ルート下の home/gravio/sample.txt を指定しています

Windowsの場合

ファイルパス 説明
c:\temp\sample.txt c:ドライブ下の temp\sample.txt を指定しています

※ここでの例では sample.txt ファイルを読み込むことを想定しています。

9. 添付ファイルの指定方法

アクションコンポーネントの中には、メール送信やHTTP送信など添付ファイルを扱うものがあります。ここでは、添付ファイルの指定方法について説明します。

添付ファイル

添付ファイルは複数のファイルを指定することができます。ファイルパスの指定方法はOS環境によって異なりますので、以下の説明に従ってください。

Windows環境での添付ファイルの指定

Windowsでは、ファイルパスにはactmgr\dataが自動的に保管されます。パスの指定も可能です。

注意：フォルダー名、ファイル名にスペースが含まれている場合には"（ダブルクォート）で囲む必要があります。

基本的な指定例：

絶対パスの指定例：

複数ファイル・ワイルドカードの指定：

ファイルは複数のファイル、ワイルドカードを指定することも可能です。複数のファイルのセパレーターは;（セミコロン）を使用し、ワイルドカードは*（アスタリスク）を使用します。

Mac、Linux、RaspberryPI、Gravio Hub環境での添付ファイルの指定

Unixベースのシステムでは、ファイルパスにはactmgr/dataが自動的に保管されます。パスの指定も可能です。

注意：フォルダー名、ファイル名にスペースが含まれている場合には"（ダブルクォート）で囲む必要があります。

基本的な指定例：

絶対パスの指定例：

複数ファイル・ワイルドカードの指定：

ファイルは複数のファイル、ワイルドカードを指定することも可能です。複数のファイルのセパレーターは;（セミコロン）を使用し、ワイルドカードは*（アスタリスク）を使用します。

このように、OS環境に応じた正しいパス区切り文字とファイル指定方法を使用することで、添付ファイルを適切に指定できます。特にスペースを含むパスの場合は、必ずダブルクォートで囲むことを忘れないようにしましょう。