カスタムコンポーネントPython-アクションフレームワークリファレンス

カスタムコンポーネントをPython言語で開発する際のAPI仕様です。 カスタムコンポーネントの開発手順については下記を参照してください。

Pythonカスタムコンポーネント作成

speedbeesynapse.component.actionfw

アクションフレームワークモジュール

このモジュールはSpeeDBee SynapseのコンポーネントをPythonのアクションフレームワークで実装する場合にimportするモジュールです。

SynapseActionComponentBase Class

class SynapseActionComponentBase()

アクションコンポーネント用基底クラス

すべてのアクションコンポーネントはこのクラスを継承して定義する必要があります。

setup

def setup(self, param: FrozenJsonType) -> None | Generator[None, None, None]

コンポーネントのセットアップ処理関数

コンポーネントの開始時、コンポーネントで定義された各アクションの実行を始める前に呼び出されます。 ここでパラメータを読み取ってアクションに必要な属性の初期化等を行うことができます。

正常にセットアップ処理を終了する場合は、何も返さず本メソッドを終了してください。その後各種アクションの実行が始まります。 何らかの理由により、コンポーネントの実行を継続できない場合は、例外を送出してください。

このメソッドの定義は必須ではありません。

このメソッド内では、１度だけyieldを実行することができます。 yieldを実行する場合、その直前までの処理は通常通り実行されますが、yieldより後の処理はコンポーネント開始時ではなく、コンポーネント終了時に実行されます。

Arguments:

• param - コンポーネントへのパラメータ

  このコンポーネントのパラメータ設定画面で設定したパラメータのJSONオブジェクトです。 このオブジェクトの内容は変更しないでください。dictやlistにおける更新を伴うメソッドは無効化されています。 また、強制的に変更してもその後のアクションの実行には反映されません。

presetup

def presetup(self, param: JsonType) -> None | Generator[None, None, None]

コンポーネントの事前セットアップ処理関数

setupと同様にコンポーネントの開始時に呼び出される関数です。 setupとの違いとして、この関数はコンポーネントのアクションを構築する前に実行されます。また、引数として受け取ったparamも変更可能です。

コンポーネントのアップデートでパラメータの形式に変更がある場合や、UIで設定した値の型を変更したい場合など、 この関数内でparamを変換することで、この後構築されるアクションに反映することができます。

Arguments:

• param - コンポーネントへのパラメータ

  このコンポーネントのパラメータ設定画面で設定したパラメータのJSONオブジェクトです。 このオブジェクトは直接変更できます。

synapse_action_component

def synapse_action_component(uuid: str | UUID,
                             name: str | None=None,
                             tag: str | None=None,
                             inports: int=1,
                             outports: int=1):

アクションコンポーネント用デコレータ

アクションコンポーネントのクラスを定義する際にそのクラスに適用するためのデコレータです。 通常のカスタムコンポーネント同様、コンポーネントの名称やUUIDを指定することができます。

Arguments

• uuid - コンポーネントのUUIDを文字列で指定します。他のコンポーネントと重複しないよう、ランダムなIDを生成してここに設定してください。
• name - コンポーネントの名称を指定します。
• tag - コンポーネントのカテゴリを指定します。通常は無指定としてください。
• inports - 現状は指定できません。常に1 or 無指定としてください。
• outports - 現状は指定できません。常に1 or 無指定としてください。

実験的機能

通常のカスタムコンポーネントでは入力ポートの、出力ポートの有無を指定できますが、本フレームワークを使用する場合は常にどちらも有効とする必要があります。 引数inports、outportsは指定せずにデコレータを適用してください。 この仕様については今後のアップデートで変更となる可能性があります。

synapse_action

def synapse_action(on_parameter: _SynapseJsonPath | None=None,
                   user_data: object = None)

コンポーネントアクション用デコレータ

アクションコンポーネントのメソッドに適用することで、そのメソッドをコンポーネントのアクションとして定義できます。 適用するメソッドはActionFuncと同じ型にしてください。

Arguments

• on_parameter - JSON Path文字列

  このデコレータを適用したアクションを実行するパラメータ内のコンテキストをJSON Pathで指定します。 省略した場合はパラメータ全体を１つのコンテキストとして、アクションの引数に渡されます。 指定したJSON Pathがパラメータ内の複数の要素にマッチする場合、マッチした要素それぞれに対してアクションが並行実行されます。 詳細はアクション実行の並行実行を参照してください。

• user_data - ユーザーデータ初期値

  このデコレータを適用したアクションの引数となるActionContextのuser_dataの初期値を指定します。 synapse_json_pathオブジェクトを指定した場合、パラメータ内のそのパスで指定された値が初期値となります。 呼び出し可能なオブジェクトが指定された場合、その関数の戻り値が初期値となります。 それら以外の場合はそのオブジェクトがそのまま初期値となります。

synapse_action.output

def synapse_action.output(name: str | _SynapseJsonPath,
           data_type: DataType | _SynapseJsonPath,
           array_size: int | _SynapseJsonPath=0)

コンポーネントアクション用出力カラム指定デコレータ

このデコレータが適用されたアクションの戻り値を格納するための、出力ポートのカラムを定義するためのデコレータです。 これを指定しない場合、アクションが戻り値を返しても無視されます。

いずれの引数も、str, intなどの直値の他、synapse_json_pathで指定したオブジェクトを指定することができます。 この場合は、このアクションのコンテキストとなったパラメータを基準にJSON Pathでマッチした要素がそのパラメータの値として適用されます。

Arguments

• name - カラムの名称
• data_type - カラムの型
• array_size - 配列型の場合の要素数

synapse_action.trigger_by_time

def synapse_action.trigger_by_time(time: float | _SynapseJsonPath,
                    enabled: bool | _SynapseJsonPath | None = None)

コンポーネントアクション用定期実行間隔指定デコレータ

アクションを一定周期で実行することを宣言するデコレータです。

いずれの引数も、int, boolなどの直値の他、synapse_json_pathで指定したオブジェクトを指定することができます。 synapse_json_pathオブジェクトを指定した場合、このアクションのコンテキストとなったパラメータを基準にJSON Pathでマッチした要素がそのパラメータの値として適用されます。

Arguments

• time - アクションの実行間隔を秒単位で指定します。
• enabled - 一定間隔での実行を有効にするか無効にするかを指定します。デフォルトはtrue、有効です。

synapse_action.trigger_by_data

def synapse_action.trigger_by_data(
            component_name: str | _SynapseJsonPath | None = None,
            component_name_pattern: str | _SynapseJsonPath | None = None,
            data_name: str | _SynapseJsonPath | None = None,
            data_name_pattern: str | _SynapseJsonPath | None = None,
            data_types: DataType | list[DataType] | _SynapseJsonPath | None = None,
            enabled: bool | _SynapseJsonPath | None = None,
            )

コンポーネントアクション用入力ポートデータトリガ指定デコレータ

入力ポートからのデータを受け取った際に１つ１つのデータに対してアクションが実行されることを宣言するデコレータです。 引数を省略した場合は、どのようなデータを受信した場合も常に実行されます。 引数でcomponent_nameやdata_nameを指定することで、指定された名称に一致するデータを受信した場合のみ、アクションが実行されます。

いずれの引数も、int, boolなどの直値の他、synapse_json_pathで指定したオブジェクトを指定することができます。 この場合は、このアクションのコンテキストとなったパラメータを基準にJSON Pathでマッチした要素がそのパラメータの値として適用されます。

このトリガによってアクションが実行された場合、アクションの第三引数TriggerContextにはHiveRecordDataが渡されます。

Arguments

• component_name - トリガとなるデータを生成したコンポーネント名を指定します
• component_name_pattern - トリガとなるデータを生成したコンポーネント名にマッチする正規表現を指定します
• data_name - トリガとなるデータ名を指定します
• data_name_pattern - トリガとなるデータ名にマッチする正規表現を指定
• data_types - トリガとなるデータの型を指定
• enabled - 入力ポートからのデータによるトリガを有効にするか無効にするかを指定します。デフォルトはtrue、有効です。

実験的機能

引数component_name_pattern, data_name_pattern, data_typesは実験的機能です。 今後のアップデートにより仕様変更となる可能性が有ります。

synapse_action.trigger_by_record

def synapse_action.trigger_by_record()

コンポーネントアクション用入力ポートレコードトリガ指定デコレータ

このデコレータが適用されたアクションが、入力ポートからのデータ受け取り時に実行されることを宣言するデコレータです。 アクションの実行は同一のタイムスタンプをもつデータをまとめたレコード単位で行われます。 synapse_action.trigger_by_dataとは違い、データ名などによるフィルタリングはできないため、入力されたすべてのデータに対して実行されます。

このトリガによってアクションが実行された場合、アクションの第三引数TriggerContextにはHiveRecordが渡されます。

synapse_action.enable

def synapse_action.enable(capability: bool | _SynapseJsonPath)

コンポーネントアクション用有効無効指定デコレータ

このデコレータが適用されたアクションの有効・無効を切り替えるためのデコレータです。 通常は定義されたアクションは常に有効となりますが、このデコレータでcapabilityがFalseに解決された場合、そのアクションは無効化され、実行されなくなります。 ユーザーの設定により特定のアクションを停止した場合場合はこのデコレータを使用して、capabilityにsynapse_json_pathを指定してください。

Arguments

• capability - アクションの有効無効を指定します。Falseの場合アクションは無効となり、実行されません

synapse_json_path

def synapse_json_path(path: str,
                      default: FrozenJsonType = _NO_DEFAULT) -> _SynapseJsonPath

JSON Pathオブジェクト生成関数

引数pathにJSON Path仕様の文字列を指定することで、コンポーネントのパラメータをJSON Pathで検索するためのオブジェクトを生成する関数です。 この関数で生成したオブジェクトは、各種synapse_action.*デコレータの引数として渡すことができます。 JSON Pathの仕様はJSONPath を参照してください。

本関数は、内部ではサードパーティモジュール jsonpath-ng を使用しています。 具体的な実装仕様はこちらを参照してください。

Arguments:

• path - JSON Path文字列を指定します。
• default - パラメータ内にマッチする要素がない場合に使われる値を指定します。マッチする要素もdefaultも指定しない場合、エラーとなりコンポーネントは実行されません。

ActionContext Class

@dataclass
class ActionContext

アクションコンテキストクラス

アクションとして定義されたメソッドの第二引数として渡されるオブジェクトです。 synapse_actionデコレータにて引数on_parameterを指定し、そのJSON Pathがパラメータ内の複数の要素にマッチする場合、どの要素にマッチしたかを識別するために使用されます。 １つのアクションにおいて、この引数の内容は呼び出し毎に変化することはありません。

Attributes:

• param: FrozenJsonType

  アクションが適用されたコンポーネントのパラメータです。 synapse_actionデコレータにて引数on_parameterを指定しない場合はコンポーネントのパラメータ全体がこの属性の値となります。 引数on_parameterにsynapse_json_pathを指定した場合、コンポーネントのパラメータにおけるそのJSON Pathのマッチした要素がこの属性の値となります。

• column: OutColumn | None

  synapse_action.outputデコレータにて出力カラムを指定していた場合は、生成された出力カラムオブジェクトOutColumn がこの属性の値となります。

• user_data: object

  アクション毎に使用可能な任意のデータを配置できる属性です。デフォルトではNoneが格納されていますが、アクション実行時にこれも更新できます。 また、synapse_actionデコレータの引数user_dataで初期値を指定することもできます。

TriggerContext Class

@dataclass
class TriggerContext

トリガーコンテキストクラス

アクションとして定義されたメソッドの第三引数として渡されるオブジェクトです。 どの要因によってアクションが実行されたか、その要因となったデータを識別するために使用されます。 １つのアクションにおいても、この引数の内容は呼び出し毎に内容が変化します。

Attributes:

• trigger_type: TriggerType

  アクションの実行要因となったトリガの種別を表します

• time: float | None

  トリガ種別がTIMEの場合、コンポーネントのアクションを開始してから現在までの経過時間を保持します

• window_data: HiveWindowData | None

  この要素は現在未使用です

• record: HiveRecord | None

  トリガ種別がRECORDの場合、トリガとなったHiveRecordを保持します

• data: HiveRecordData | None

  トリガ種別がDATAの場合、トリガとなったHiveRecordDataを保持します

TriggerType Enum

class TriggerType(IntEnum)

トリガー種別列挙型

アクションを実行するトリガーとなった事象の種別を表します。

Attributes:

• NONE(0) - 現在は使用されていません
• TIME(1) - synapse_action.trigger_by_timeにより指定された周期実行によるトリガであることを示します
• DATA(2) - synapse_action.trigger_by_dataにより指定された入力ポートのデータ受信によるトリガであることを示します
• RECORD(3) - synapse_action.trigger_by_recordにより指定された入力ポートのレコード受信によるトリガであることを示します
• WINDOW(4) - 現在は使用されていません
• CALL(5) - 現在は使用されていません

FrozenJsonType Alias

FrozenJsonType = FrozenDict[str, 'FrozenJsonType'] | FrozenList['FrozenJsonType'] | str | int | float | bool | None

不変なJSONデータの型を表す型エイリアスです。 この型のデータは変更できないことを表しています。

型情報を持つだけなので、型アノテーションを使わない場合は使用する必要はありません。

JsonType Alias

JsonType = dict[str, 'JsonType'] | list['JsonType'] | str | int | float | bool | None

変更可能なJSONデータの型を表す型エイリアスです。

型情報を持つだけなので、型アノテーションを使わない場合は使用する必要はありません。

ActionFunc Alias

ActionFunc = Callable[[object, 'ActionContext', 'TriggerContext'], Any | None]

アクションとして定義できるメソッドの型を表す型エイリアスです。 アクション定義するメソッドはこれと同一の型情報を保つ必要があります。

型情報を持つだけなので、型アノテーションを使わない場合は使用する必要はありません。