コンテンツにスキップ

5.1.5 カスタムコンポーネント開発環境(SCCDE)

本項では、Synapseカスタムコンポーネント開発環境(以下SCCDE)について説明します。

5.1.5.1 SCCDEの概要#

Synapseカスタムコンポーネント開発環境(SCCDE)は、Synapseのカスタムコンポーネントを開発するための 様々なツール・パッケージを集約した環境です。現在のところ以下の機能を有しています。

  • カスタムコンポーネント管理ディレクトリの初期化(init)

    管理用のディレクトリは、GitやSubversionなどのバージョン管理システムで利用しやすい形態になっています。

  • カスタムコンポーネントのサンプルプログラムの追加(add)

    コレクタ、シリアライザ、エミッタなどの簡易的なサンプルプログラムを追加できます。

  • カスタムコンポーネントのパッケージング(make-package)

    コンポーネントのパッケージングを行うと、複数のカスタムコンポーネントやカスタムUIを まとめて１つのファイル(SCCPKG)に収めることができます。 このSCCPKGファイルを、Synapseの管理画面からアップロードすることで、 複数のカスタムコンポーネントをまとめて管理することができます。

  • カスタムコンポーネントのテスト環境の実行(serve)

    作成したカスタムコンポーネントを簡易的に実行するためのテスト環境を起動できます。

概要

現時点ではPython実装のカスタムコンポーネントのみに対応しています。 C言語実装のコンポーネントの対応は未定です。

5.1.5.2 インストール方法#

SCCDEは以下の方法でインストールできます。

  • Synapseと一緒に配布されるwhlパッケージファイルを使ってインストール
  • PyPI（pipの標準インデックス）からインストール

インストールする環境はWindowsでもLinuxでも構いません。 ただしテスト環境の実行(serve)機能は、同一デバイスにSynapseがインストールされている必要があります。

$ python3 -m venv ~/sccde
$ . ~/sccde/bin/activate
(sccde) $ pip3 install speedbeesynapse-sccde
参考：venv

PS> python -m venv "$HOME\sccde"
PS> . "$HOME\sccde\Scripts\Activate.ps1"
(sccde) PS> pip3 install speedbeesynapse-sccde
参考：venv

本パッケージは標準的なPythonパッケージですので、 上記のpip, venvを使ったインストール方法以外にも様々なパッケージ管理ツール （Poetry, uvなど） を使用可能です。お好みのツールをご利用ください。

※以降で説明する手順は、上記のactivateを行った(sccde)環境内で実施することを想定しています。

5.1.5.3 SCCDEの使い方とパッケージング#

5.1.5.3.1 カスタムコンポーネント管理ディレクトリの初期化#

カスタムコンポーネントを管理するために、空のディレクトリを用意して初期化する必要があります。 以下の手順で初期化してください。

(sccde) $ mkdir sccpack-test
(sccde) $ cd sccpack-test
(sccde) $ sccde init
(sccde) $ ls
parameter_ui  source  scc-info.json

(sccde) PS> mkdir sccpack-test
(sccde) PS> cd sccpack-test
(sccde) PS> sccde init
(sccde) PS> ls
Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
d----          2025/xx/yy    hh:mm                parameter_ui
d----          2025/xx/yy    hh:mm                source
-a---          2025/xx/yy    hh:mm            644 scc-info.json

初期化を行うと現在のディレクトリに対して以下の処理が行われます。

  • scc-info.jsonの生成
  • カスタムコンポーネント(collector)のサンプルプログラムの追加

scc-info.jsonは、このディレクトリ内で管理するカスタムコンポーネントに関する情報を記載するためのファイルです。 JSON形式になっていますので、必要に応じてテキストエディタ等で編集してください。
ファイル内で多言語用のプロパティを用いることで、カスタムコンポーネントダイアログやコンポーネントベースのツールチップで多言語表示を行うことが可能です。

主要なプロパティを下記に記載いたします。

プロパティ 説明
package-name パッケージの名称です。任意の名前を記載できます。必須プロパティなので、scc-info.jsonファイルに必ず記載してください。
有効な値が入っていない場合、空欄が表示されます。
package-name.{言語コード} package-nameの多言語用プロパティです。このプロパティを追加する際、必須プロパティpackage-nameを削除しないようご注意ください。
{言語コード}にはSynapseでサポートされている言語コード(例：jaまたはen)を入れることで、Synapseの言語設定に合わせて表示が切り替わります。そのため、プロパティの値は{言語コード}に合わせた言語で記載する必要があります。
有効な値が入っていない場合package-nameの値が表示され、package-nameにも有効な値が無い場合は空欄となります。
package-version パッケージのバージョンを示す文字列です。基本的には"."区切りの３つの数値を記載してください。
このバージョン文字列はSemantic Versioning 2.0.0に沿った形式が望ましいです。
package-uuid パッケージを識別するためのIDです。初期状態ではランダムなUUIDが設定されています。必須プロパティなので、scc-info.jsonファイルに必ず記載してください。
基本的には変更せずに使用してください。
package-description パッケージの説明文です。任意の文字列を記載して下さい。
有効な値が入っていない場合、空欄が表示されます。
package-description.{言語コード} package-descriptionの多言語用プロパティです。パッケージの説明文を多言語で表示する場合に追加してください。
{言語コード}にはSynapseでサポートされている言語コード(例：jaまたはen)を入れることで、Synapseの言語設定に合わせて表示が切り替わります。そのため、プロパティの値は{言語コード}に合わせた言語で記載する必要があります。
有効な値が入っていない場合package-descriptionの値が表示され、package-descriptionにも有効な値が無い場合は空欄となります。
author パッケージ作成者の名前を記載できます。
license このパッケージを利用する際のライセンス種別を記入できます。（BSD, MIT, UNLICENSEDなど）。不要な場合は空文字列としてください。
license-file このパッケージのライセンス詳細を記したファイルの相対パスを指定できます。不要な場合は空文字列としてください。
python-components-source このディレクトリ内で管理するPythonのカスタムコンポーネントの配置パスです。基本的に変更する必要はありません。
components 複数のカスタムコンポーネントの定義を記載するためのオブジェクトです。keyにはカスタムコンポーネントのUUIDを指定する必要があります。
components.*.name カスタムコンポーネントの名称です。任意の名前を記載できます。
components.*.description カスタムコンポーネントの説明文です。コンポーネントベースのツールチップに表示されます。
有効な値が入っていない場合、デフォルトテキストが表示されます。
components.*.description.{言語コード} components.\*.descriptionの多言語用プロパティです。コンポーネントベースのツールチップに表示されます。
カスタムコンポーネントの説明文を多言語で表示する場合に追加してください。
{言語コード}にはSynapseでサポートされている言語コード(例：jaまたはen)を入れることで、Synapseの言語設定に合わせてコンポーネントベースのツールチップ表示が切り替わります。そのため、プロパティの値は{言語コード}に合わせた言語で記載する必要があります。
有効な値が入っていない場合components.\*.descriptionの値が表示され、components.\*.descriptionにも有効な値が無い場合は「ユーザが作成、登録したコンポーネントです。」が表示されます。
components.*.component-type カスタムコンポーネントの実装種別です。'python' or 'c'を指定する必要があります。
components.*.modulename Pythonカスタムコンポーネントのモジュール名です。
python-components-sourceで指定したパスを基準とした場合のカスタムコンポーネントをimportするためのモジュール名を記載してください。
components.*.parameter-ui-type カスタムUIの定義ファイルへ種別を指定します。'json' or 'html'を指定可能です。
components.*.parameter-ui カスタムUIへの相対パスを指定してください。
'json'形式の場合はそのファイルへのパスを、'html'形式の場合はhtmlファイルが配置されたディレクトリへのパスを指定してください。
python-requirements Python依存モジュールの定義を記載するための配列です。

記述例
"python-requirements": [
  "sqlalchemy",
  "psycopg[binary]",
  "requests ==2.32.4",
  "aiohttp >=3,<4;sys_platform == 'win32'",
  "httpx ==0.28.1;sys_platform == 'linux' and python_version>='3.10'"
]
詳細な記述形式はDependency specifiersを参照してください。
※ただし、URLの記述には対応していません。

多言語プロパティの設定ルール(scc-info.json)

  • 必須プロパティ
    package-nameはscc-info.jsonファイルに必須のプロパティとなっております。多言語プロパティpackage-name.{言語コード}を追加する際に、間違えてpackage-nameを削除しないようご注意ください。

    定義ファイルの例(scc-info.json)
    {
    "package-name": "example package name",      // 既存プロパティ(必須)
    "package-name.ja": "カスタムパッケージ名",     // 多言語プロパティ(日本語)
    "package-name.en": "Custom package name",    // 多言語プロパティ(英語)
    ..
    .
}

  • ダウンロードファイル名
    パッケージをダウンロードする際のファイル名は、言語設定に関係なく常にpackage-nameから生成されます。

  • 多言語と既存プロパティの優先順位
    プロパティは多言語が優先して参照され、多言語対応されていない場合または有効な値が入っていない場合は既存プロパティが参照されます。

    1 多言語プロパティ
    例：package-name.ja、package-description.enなど
    2 既存プロパティ
    例：package-name、package-descriptionなど

  • 無効な値
    該当する値を入れた場合、そのプロパティは無効となります。無効となった場合の動作はプロパティごとに変わるため、各プロパティの説明をご確認ください。

    1. 空文字
      例："package-description": ""
    2. 空白のみの文字列
      例："package-description.ja": " "
    3. タブや改行のみ
      例："package-description.en": "\t\n"

5.1.5.3.2 カスタムコンポーネントの追加#

管理ディレクトリを初期化した後は、addサブコマンドによりカスタムコンポーネントのサンプルプログラムを追加できます。

(sccde) $ sccde add -t collector

(sccde) PS> sccde add -t collector

-tの後の文字列は、collectorの他にserializer, emitterなどに置き換え可能です。

追加したサンプルプログラムは初期状態ではsource/python配下に配置されます。 このサンプルはそのままでも実行可能なようになっていますが、これをベースに 自由にカスタムコンポーネントを改変して独自のコンポーネントを作ることができます。

カスタムコンポーネントの実装方法については下記を参照してください。

また、追加されたサンプルコンポーネントにはカスタムUIのサンプルも付属しています。 こちらも必要に応じて改変してご利用ください。

デフォルトではjson形式のカスタムUIが付与されます。 追加時のオプションで-u htmlを指定することで、HTML形式のカスタムUIも作成可能です。

5.1.5.3.3 カスタムコンポーネントのテスト実行#

SCCDEコマンドをインストールした環境に、Synapseもインストールされている場合はserveコマンドでカスタムコンポーネントをテスト実行することができます。

(sccde) $ sccde serve --port 8123
Preparing Synapse data directories..
Synapse server ready: http://127.0.0.1:8123
:

(sccde) PS> sccde serve --port 8123
Preparing Synapse data directories..
Synapse server ready: http://127.0.0.1:8123
:

初回実行ではデータディレクトリの初期化および依存モジュールのインストールにしばらく時間がかかります。 ready: http://..のメッセージが表示されたら、ブラウザでそのURLを開いてください。

URLを開くと、SynapseのフローエディタのEdit Modeと同様の画面が表示されます。 左側のコンポーネントベース一覧から、作成したカスタムコンポーネントを選択可能になっています。

テスト用のSynapseは、Ctrl-Cキーで停止できます。

オプション

オプション 説明
--host テスト用Synapseサーバーが利用するIPアドレスを指定できます。稼働しているデバイス外からもアクセスしたい場合は0.0.0.0を指定してください。デフォルトは127.0.0.1となっています。
--port テスト用Synapseサーバーが利用するTCPポート番号指定できます。他のサービスとポート番号が被らないように任意の番号を指定してください。デフォルトは8000となっています。
--verbose テスト用Synapseの実行ログを表示します。

データディレクトリとログ

テスト用Synapseの実行中のデータは、sccdeの作業ディレクトリ内にある.synapse/var-speedbeesynapseディレクトリに配置されます。

(sccde) $ ls .synapse/var-speedbeesynapse/
certs  config  dblog  hivecore_exec_status.json  logs  projects  sdts.db  sdts.file  webui_tmp

(sccde) PS> ls .\.synapse\var-speedbeesynapse\
Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
d----          2025/xx/yy    hh:mm                certs
d----          2025/xx/yy    hh:mm                config
d----          2025/xx/yy    hh:mm                dblog
d----          2025/xx/yy    hh:mm                logs
d----          2025/xx/yy    hh:mm                projects
d----          2025/xx/yy    hh:mm                sdts.db
d----          2025/xx/yy    hh:mm                sdts.file
d----          2025/xx/yy    hh:mm                webui_tmp
-a---          2025/xx/yy    hh:mm            105 hivecore_exec_status.json

データをクリアして初期状態に戻したい場合は、.synapseフォルダごと削除してからテスト用Synapseを起動してください。

また、カスタムコンポーネントのデバッグ等でログを参照したい場合は、.synapse/var-speedbeesynapse/logsにあるspeedbeesynase.logを参照できます。

開発用コンポーネント

テスト用Synapse実行中は、専用の開発用コンポーネントを利用できます。 開発用コンポーネントの詳細については、「開発用コンポーネント」を参照してください。

5.1.5.3.4 パッケージング#

カスタムコンポーネントを追加した後は、make-packageサブコマンドにより、パッケージを作成できます。

(sccde) $ sccde make-package
(sccde) $ ls
custom_component_package_example.sccpkg  parameter_ui  scc-info.json  source

(sccde) PS> sccde make-package
(sccde) PS> ls
Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
d----          2025/xx/xx    hh:mm                parameter_ui
d----          2025/xx/xx    hh:mm                source
-a---          2025/xx/xx    hh:mm           2481 custom_component_package_example.sccpkg
-a---          2025/xx/xx    hh:mm            644 scc-info.json

.sccpkgという拡張子がついたファイルがSCCPKGです。 このファイルをSynapseに登録することができます。

5.1.5.4 SynapseへのSCCPKGファイルの登録、および、削除#

前項で説明したパッケージングにより作成したパッケージファイル(SCCPKG)を、 Synapseの管理画面から登録することで、パッケージに含まれるカスタムコンポーネントを利用できるようになります。

5.1.5.4.1 登録/更新#

次の手順で、作成したSCCPKGファイルをSpeeDBee Synapseに登録することができます。

  1. ヘッダのモード選択で"Edit Mode"を選択し、Editモードの画面を開きます。

  2. 設定メニューアイコンを押下し、「カスタムコンポーネント」を選択します。

  3. コンポーネントパッケージの「追加」を押下し、カスタムコンポーネントのファイルを登録します。

    既に同一のパッケージが登録済みの場合、ここで上書きを確認するダイアログが表示されます。 上書きする場合は「はい」を選択してください。

    依存モジュールが存在する場合、ここでインストールを確認するダイアログが表示されます。 インストールする場合は「インストールする」を選択してください。

  4. 「閉じる」を押下します。

  5. 確認ダイアログで「はい」を選択し、変更を反映するために、システムを再起動させます。

  6. 左メニューに、登録したカスタムコンポーネントが反映されます。

5.1.5.4.2 依存モジュール#

次の手順で、依存モジュールをインストールすることができます。

  1. 設定メニューアイコンを押下し、「カスタムコンポーネント」を選択します。

  2. コンポーネントパッケージの「依存モジュール」を押下します。

  3. 確認ダイアログで「不足するモジュールのみインストール」または「全モジュールを再インストール」を選択し、「インストールする」を選択します。

5.1.5.4.3 ダウンロード#

次の手順で、登録したコンポーネントパッケージをダウンロードすることができます。

  1. 設定メニューアイコンを押下し、「カスタムコンポーネント」を選択します。

  2. コンポーネントパッケージの「ダウンロードアイコン（取得）」を押下します。

  3. コンポーネントパッケージのファイルがダウンロードされます。

5.1.5.4.4 削除#

次の手順で、登録したSCCPKGファイルをSpeeDBee Synapseから削除することができます。

  1. 設定メニューアイコンを押下し、「カスタムコンポーネント」を選択します。

  2. 対象パッケージの右にある「ゴミ箱アイコン（削除）」を押下します。

  3. 確認ダイアログで「はい」を選択します。

  4. SCCPKGファイルが削除されます。

5.1.5.4.5 保護の付与#

登録したパッケージには保護をかけることができます。
保護されたパッケージは次の操作が行えなくなるため、意図しない更新を防ぐことができます。

次の手順で、パッケージに保護をかけることができます。

  1. 設定メニューアイコンを押下し、「カスタムコンポーネント」を選択します。

  2. 対象パッケージの右にある「鍵アイコン（保護）」を押下します。

  3. 保護解除する際に必要となるパスワードを入力して、「保護」を押下します。

    警告

    • パスワードは復元できない形式で保存され、一度設定すると保護を解除するまで再設定できません。
    • 保護設定したパスワードを忘れた場合、該当のパッケージは操作不能となります。

    パスワードの取り扱いには十分ご注意ください。

  4. コンポーネントパッケージが保護状態になります。

5.1.5.4.6 保護の解除#

次の手順で、パッケージの保護を解除することができます。

  1. 設定メニューアイコンを押下し、「カスタムコンポーネント」を選択します。

  2. 対象パッケージの右にある「鍵アイコン（保護解除）」を押下します。

  3. 保護をかけた際に設定したパスワードを入力して、「保護解除」を押下します。

  4. コンポーネントパッケージの保護が解除されます。