@things-factory/integration-base 9.0.5 → 9.0.12

package/helps/integration/connector/pyrun-connector.ja.md

@@ -0,0 +1,55 @@
+# pyrun-connector
+
+Python Runner（pyrun）REST APIと連携するためのコネクタです。
+pyrunサーバーのREST API（例：`/api/run/{module}`）を呼び出して、Pythonモジュールの実行結果を取得できます。
+
+## パラメータ
+
+- **endpoint**: pyrunサーバーのURL（例：`http://runner.hatiolab.com:8000`）
+- **username**: （任意）pyrunサーバーにログインするユーザー名（認証が必要な場合）
+- **password**: （任意）pyrunサーバーにログインするパスワード（認証が必要な場合）
+- **token**: （任意）Bearer認証トークン。直接入力するか、username/passwordでログイン時に自動発行されます。
+
+> pyrunサーバーが認証を要求しない場合は、endpointのみ入力してください。  
+> 認証が必要な場合は、username/passwordを入力すると、コネクタが`/auth/login` APIを通じてトークンを自動取得して使用します。  
+> すでにトークンを持っている場合は、tokenのみ入力してください。
+
+## 動作仕様
+
+- usernameとpasswordが両方入力されている場合、`/auth/login`エンドポイントにログインリクエストを送り、レスポンスから`access_token`を抽出して使用します。
+- tokenが入力されている場合は、AuthorizationヘッダーのBearerトークンとしてそのまま使用します。
+- 認証情報がない場合は、認証なしでpyrun APIを呼び出します。
+- 認証に失敗した場合はエラーメッセージが返されます。
+
+## 使用例
+
+```json
+{
+  "type": "pyrun-connector",
+  "endpoint": "http://runner.hatiolab.com:8000",
+  "params": {
+    "username": "your username",
+    "password": "your password"
+  }
+}
+```
+
+または
+
+```json
+{
+  "type": "pyrun-connector",
+  "endpoint": "http://runner.hatiolab.com:8000",
+  "params": {
+    "token": "your-access-token"
+  }
+}
+```
+
+## 注意事項
+
+- Basic認証（Authorization: Basic ...）はサポートされていません。
+- username/passwordを入力すると、自動的にトークンが発行されて使用されます。
+- tokenのみ入力した場合は、そのままBearer認証として使用されます。
+- pyrunサーバーの認証ポリシーに従って、必要なパラメータを入力してください。
+- 認証に失敗した場合、`"pyrun-connector 認証失敗: [ステータスコード] [エラーメッセージ]"`のようなエラーが発生することがあります。

package/helps/integration/connector/pyrun-connector.ko.md

@@ -0,0 +1,55 @@
+# pyrun-connector
+
+Python Runner(pyrun) REST API와 연동하기 위한 커넥터입니다.  
+pyrun 서버의 REST API(예: `/api/run/{module}`)를 호출하여 파이썬 모듈 실행 결과를 받아올 수 있습니다.
+
+## 파라미터
+
+- **endpoint**: pyrun 서버의 URL (예: `http://runner.hatiolab.com:8000`)
+- **username**: (선택) pyrun 서버에 로그인할 사용자명. (인증이 필요한 경우)
+- **password**: (선택) pyrun 서버에 로그인할 비밀번호. (인증이 필요한 경우)
+- **token**: (선택) Bearer 인증 토큰. 직접 입력하거나, username/password로 로그인 시 자동 발급받아 사용합니다.
+
+> pyrun 서버가 인증을 요구하지 않는 경우, endpoint만 입력하면 됩니다.  
+> 인증이 필요한 경우, username/password를 입력하면 `/auth/login` API를 통해 토큰을 자동으로 발급받아 사용합니다.  
+> 이미 발급받은 토큰이 있다면 token만 입력해도 됩니다.
+
+## 동작 방식
+
+- username/password가 모두 입력되면 `/auth/login` 엔드포인트로 로그인 요청을 보내고, 응답에서 `access_token`을 추출하여 사용합니다.
+- token이 입력된 경우, 바로 Authorization 헤더(`Bearer {token}`)로 pyrun API를 호출합니다.
+- 인증 정보가 모두 없으면 인증 없이 pyrun API를 호출합니다.
+- 인증 실패 시 에러 메시지가 반환됩니다.
+
+## 사용 예시
+
+```json
+{
+  "type": "pyrun-connector",
+  "endpoint": "http://runner.hatiolab.com:8000",
+  "params": {
+    "username": "your username",
+    "password": "your password"
+  }
+}
+```
+
+또는
+
+```json
+{
+  "type": "pyrun-connector",
+  "endpoint": "http://runner.hatiolab.com:8000",
+  "params": {
+    "token": "your-access-token"
+  }
+}
+```
+
+## 참고
+
+- Basic 인증(Authorization: Basic ...)은 지원하지 않습니다.
+- username/password를 입력하면 자동으로 토큰을 발급받아 사용합니다.
+- token만 입력하면 바로 Bearer 인증으로 사용합니다.
+- pyrun 서버의 인증 정책에 따라 파라미터를 선택적으로 입력하세요.
+- 인증 실패 시 `"pyrun-connector 인증 실패: [상태코드] [에러메시지]"` 형태의 에러가 발생할 수 있습니다.

package/helps/integration/connector/pyrun-connector.md

@@ -0,0 +1,55 @@
+# pyrun-connector
+
+This connector is for integrating with the Python Runner (pyrun) REST API.
+You can use it to call the pyrun server's REST API (e.g., `/api/run/{module}`) and receive the result of running a Python module.
+
+## Parameters
+
+- **endpoint**: The URL of the pyrun server (e.g., `http://runner.hatiolab.com:8000`)
+- **username**: (Optional) Username for logging in to the pyrun server (if authentication is required)
+- **password**: (Optional) Password for logging in to the pyrun server (if authentication is required)
+- **token**: (Optional) Bearer authentication token. You can enter it directly, or it will be automatically issued and used if you log in with username/password.
+
+> If the pyrun server does not require authentication, just enter the endpoint.  
+> If authentication is required, enter username/password and the connector will automatically obtain a token via the `/auth/login` API.  
+> If you already have a token, you can enter only the token.
+
+## How it works
+
+- If both username and password are provided, the connector sends a login request to the `/auth/login` endpoint and extracts the `access_token` from the response.
+- If a token is provided, it is used directly as a Bearer token in the Authorization header for pyrun API calls.
+- If no authentication information is provided, the pyrun API is called without authentication.
+- If authentication fails, an error message is returned.
+
+## Example
+
+```json
+{
+  "type": "pyrun-connector",
+  "endpoint": "http://runner.hatiolab.com:8000",
+  "params": {
+    "username": "your username",
+    "password": "your password"
+  }
+}
+```
+
+Or
+
+```json
+{
+  "type": "pyrun-connector",
+  "endpoint": "http://runner.hatiolab.com:8000",
+  "params": {
+    "token": "your-access-token"
+  }
+}
+```
+
+## Notes
+
+- Basic authentication (Authorization: Basic ...) is not supported.
+- If you enter username/password, a token is automatically issued and used.
+- If you enter only a token, it is used directly as Bearer authentication.
+- Enter parameters as needed according to the pyrun server's authentication policy.
+- If authentication fails, you may see an error like: `"pyrun-connector authentication failed: [status code] [error message]"`.

package/helps/integration/connector/pyrun-connector.ms.md

@@ -0,0 +1,55 @@
+# pyrun-connector
+
+Penyambung ini digunakan untuk integrasi dengan Python Runner (pyrun) REST API.
+Anda boleh memanggil REST API pelayan pyrun (cth: `/api/run/{module}`) dan menerima hasil pelaksanaan modul Python.
+
+## Parameter
+
+- **endpoint**: URL pelayan pyrun (cth: `http://runner.hatiolab.com:8000`)
+- **username**: (Pilihan) Nama pengguna untuk log masuk ke pelayan pyrun (jika perlu pengesahan)
+- **password**: (Pilihan) Kata laluan untuk log masuk ke pelayan pyrun (jika perlu pengesahan)
+- **token**: (Pilihan) Token pengesahan Bearer. Anda boleh masukkan secara langsung, atau ia akan dijana dan digunakan secara automatik jika anda log masuk dengan username/password.
+
+> Jika pelayan pyrun tidak memerlukan pengesahan, hanya masukkan endpoint.  
+> Jika perlu pengesahan, masukkan username/password dan penyambung akan mendapatkan token secara automatik melalui API `/auth/login`.  
+> Jika anda sudah mempunyai token, hanya masukkan token sahaja.
+
+## Cara Kerja
+
+- Jika kedua-dua username dan password diberikan, penyambung akan menghantar permintaan log masuk ke endpoint `/auth/login` dan mengekstrak `access_token` dari respons.
+- Jika token diberikan, ia akan digunakan secara langsung sebagai Bearer token dalam header Authorization untuk panggilan API pyrun.
+- Jika tiada maklumat pengesahan diberikan, API pyrun akan dipanggil tanpa pengesahan.
+- Jika pengesahan gagal, mesej ralat akan dipaparkan.
+
+## Contoh Penggunaan
+
+```json
+{
+  "type": "pyrun-connector",
+  "endpoint": "http://runner.hatiolab.com:8000",
+  "params": {
+    "username": "your username",
+    "password": "your password"
+  }
+}
+```
+
+Atau
+
+```json
+{
+  "type": "pyrun-connector",
+  "endpoint": "http://runner.hatiolab.com:8000",
+  "params": {
+    "token": "your-access-token"
+  }
+}
+```
+
+## Nota
+
+- Pengesahan Basic (Authorization: Basic ...) tidak disokong.
+- Jika anda masukkan username/password, token akan dijana dan digunakan secara automatik.
+- Jika anda hanya masukkan token, ia akan digunakan terus sebagai pengesahan Bearer.
+- Masukkan parameter mengikut keperluan dasar pengesahan pelayan pyrun.
+- Jika pengesahan gagal, anda mungkin akan menerima ralat seperti: `"pyrun-connector pengesahan gagal: [kod status] [mesej ralat]"`.

package/helps/integration/connector/pyrun-connector.zh.md

@@ -0,0 +1,55 @@
+# pyrun-connector
+
+用于与 Python Runner (pyrun) REST API 集成的连接器。
+可以调用 pyrun 服务器的 REST API（如 `/api/run/{module}`），并获取 Python 模块的执行结果。
+
+## 参数
+
+- **endpoint**: pyrun 服务器的 URL（例如：`http://runner.hatiolab.com:8000`）
+- **username**: （可选）登录 pyrun 服务器的用户名（如需认证时）
+- **password**: （可选）登录 pyrun 服务器的密码（如需认证时）
+- **token**: （可选）Bearer 认证令牌。可直接输入，或通过输入用户名/密码自动获取并使用。
+
+> 如果 pyrun 服务器不需要认证，只需输入 endpoint。  
+> 如果需要认证，输入 username/password，连接器会通过 `/auth/login` API 自动获取令牌。  
+> 如果已有令牌，只需输入 token 即可。
+
+## 工作方式
+
+- 同时输入 username 和 password 时，连接器会向 `/auth/login` 端点发送登录请求，并从响应中提取 `access_token`。
+- 输入 token 时，直接作为 Bearer 令牌用于 Authorization 头部调用 pyrun API。
+- 未输入认证信息时，将不带认证信息调用 pyrun API。
+- 认证失败时会返回错误信息。
+
+## 使用示例
+
+```json
+{
+  "type": "pyrun-connector",
+  "endpoint": "http://runner.hatiolab.com:8000",
+  "params": {
+    "username": "your username",
+    "password": "your password"
+  }
+}
+```
+
+或
+
+```json
+{
+  "type": "pyrun-connector",
+  "endpoint": "http://runner.hatiolab.com:8000",
+  "params": {
+    "token": "your-access-token"
+  }
+}
+```
+
+## 备注
+
+- 不支持 Basic 认证（Authorization: Basic ...）。
+- 输入 username/password 时会自动获取并使用令牌。
+- 仅输入 token 时直接作为 Bearer 认证使用。
+- 请根据 pyrun 服务器的认证策略选择性输入参数。
+- 认证失败时，可能会出现如下错误：`"pyrun-connector 认证失败: [状态码] [错误信息]"`。

package/helps/integration/task/publish.ja.md

@@ -1,16 +1,54 @@
 # publish
 
-これはsubscription APIを介して要求されたすべてのSubscriberにデータをブロードキャストするタスクです。
+subscription APIを介して要求されたすべてのSubscriberにデータをブロードキャストするタスクです。
 
-クライアントアプリケーションでデータサブスクリプションを要求する方法は以下の通りです。
+クライアントアプリケーションでデータサブスクリプションを要求する方法は以下の通りです：
 
-- ボードUIを介してSubscriberを通じて要求できます。
-- wss://[server host:port]/subscription APIを介してsubscribeを要求できます。
+- Board UIでsubscriberを通じて要求できます。
+- wss://[server host:port]/subscription APIを介してsubscribe要求できます。
 
-## パラメータ
+## パラメーター
 
-- [アクセサ](../concept/data-accessor.md)
-  - シナリオ内のステップ名で、ブロードキャストしたいデータを指定します。
-- タグ
+- tag
   - データをブロードキャストする際には、タグを付けて送る必要があります。
   - Subscriberもデータをsubscribeする際には、受け取りたいタグを設定して、該当のタグが付いたブロードキャストだけを受信できます。
+  - **動的サポート**: 以下のパターンを使用した動的置換をサポートします:
+    - `#{user.id}_status` - #{...} パターン使用
+    - `${user.role}_prefs` - ${...} パターン使用
+    - `{{domain.name}}_data` - {{...}} パターン使用
+    - `static_name` - 静的名前 (置換なし)
+
+## 使用例
+
+### 静的使用
+
+```json
+{
+  "task": "publish",
+  "params": {
+    "tag": "machine"
+  }
+}
+```
+
+### 動的使用
+
+```json
+{
+  "task": "publish",
+  "params": {
+    "tag": "#{machine.code}"
+  }
+}
+```
+
+### 混合使用
+
+```json
+{
+  "task": "publish",
+  "params": {
+    "tag": "#{machine.code}_${sensor.code}"
+  }
+}
+```

package/helps/integration/task/publish.ko.md

@@ -9,8 +9,46 @@ subscription API를 통해서 요청된 모든 Subscriber에게 데이타를 브
 
 ## parameters
 
-- [accessor](../concept/data-accessor.md)
-  - 시나리오 내의 하나의 스텝이름으로, 브로드캐스트하고자 하는 데이타를 지정한다.
 - tag
   - 데이타를 브로드캐스트할 때 태그를 부여해서 보내야한다.
   - subscriber들도 data를 subscribe할 때, 받고자 하는 테그를 설정하여, 해당 태그가 부여된 브로드캐스트만 받을 수 있다.
+    - **동적 지원**: 다음 패턴을 사용한 동적 치환을 지원합니다:
+    - `#{user.id}_status` - #{...} 패턴 사용
+    - `${user.role}_prefs` - ${...} 패턴 사용
+    - `{{domain.name}}_data` - {{...}} 패턴 사용
+    - `static_name` - 정적 이름 (치환 없음)
+
+## 사용 예시
+
+### 정적 사용
+
+```json
+{
+  "task": "publish",
+  "params": {
+    "tag": "machine"
+  }
+}
+```
+
+### 동적 사용
+
+```json
+{
+  "task": "publish",
+  "params": {
+    "tag": "#{machine.code}"
+  }
+}
+```
+
+### 혼합 사용
+
+```json
+{
+  "task": "publish",
+  "params": {
+    "tag": "#{machine.code}_${sensor.code}"
+  }
+}
+```

package/helps/integration/task/publish.md

@@ -7,10 +7,48 @@ Ways to request data subscription in client applications include:
 - It can be requested through the Board UI via subscribers.
 - Subscription requests can be made through the wss://[server host:port]/subscription API.
 
-## Parameters
+## parameters
 
-- [Accessor](../concept/data-accessor.md)
-  - As a step name within the scenario, specifies the data to be broadcast.
-- Tag
+- tag
   - When broadcasting data, it is necessary to attach a tag.
   - When subscribers subscribe to data, they can receive only broadcasts with the specified tag.
+  - **Dynamic Support**: Supports dynamic substitution using the following patterns:
+    - `#{user.id}_status` - Using #{...} pattern
+    - `${user.role}_prefs` - Using ${...} pattern
+    - `{{domain.name}}_data` - Using {{...}} pattern
+    - `static_name` - Static name (no substitution)
+
+## Usage Examples
+
+### Static Usage
+
+```json
+{
+  "task": "publish",
+  "params": {
+    "tag": "machine"
+  }
+}
+```
+
+### Dynamic Usage
+
+```json
+{
+  "task": "publish",
+  "params": {
+    "tag": "#{machine.code}"
+  }
+}
+```
+
+### Mixed Usage
+
+```json
+{
+  "task": "publish",
+  "params": {
+    "tag": "#{machine.code}_${sensor.code}"
+  }
+}
+```

package/helps/integration/task/publish.ms.md

@@ -7,10 +7,48 @@ Cara untuk meminta langganan data dalam aplikasi klien termasuk:
 - Ini dapat diminta melalui Board UI melalui subscriber.
 - Permintaan langganan dapat dilakukan melalui wss://[server host:port]/subscription API.
 
-## Parameter
+## parameter
 
-- [Aksesori](../concept/data-accessor.md)
-  - Sebagai nama langkah dalam skenario, menentukan data yang akan disiarkan.
-- Tag
+- tag
   - Ketika menyiarkan data, perlu melampirkan tag.
   - Ketika subscriber berlangganan data, mereka hanya dapat menerima siaran dengan tag yang ditentukan.
+  - **Sokongan Dinamik**: Menyokong penggantian dinamik menggunakan corak:
+    - `#{user.id}_status` - Menggunakan corak #{...}
+    - `${user.role}_prefs` - Menggunakan corak ${...}
+    - `{{domain.name}}_data` - Menggunakan corak {{...}}
+    - `static_name` - Nama statik (tiada penggantian)
+
+## Contoh Penggunaan
+
+### Penggunaan Statik
+
+```json
+{
+  "task": "publish",
+  "params": {
+    "tag": "machine"
+  }
+}
+```
+
+### Penggunaan Dinamik
+
+```json
+{
+  "task": "publish",
+  "params": {
+    "tag": "#{machine.code}"
+  }
+}
+```
+
+### Penggunaan Campuran
+
+```json
+{
+  "task": "publish",
+  "params": {
+    "tag": "#{machine.code}_${sensor.code}"
+  }
+}
+```

package/helps/integration/task/publish.zh.md

@@ -4,13 +4,54 @@
 
 客户端应用程序请求数据订阅的方式包括：
 
-- 可以通过Board UI通过订阅者请求。
+- 可以通过Board UI通过subscriber请求。
 - 可以通过wss://[server host:port]/subscription API进行订阅请求。
 
 ## 参数
 
+- tag
+  - 广播数据时，需要附加标签。
+  - 当订阅者订阅数据时，他们只能接收带有指定标签的广播。
+  - **动态支持**: 支持使用以下模式的动态替换:
+    - `#{user.id}_status` - 使用 #{...} 模式
+    - `${user.role}_prefs` - 使用 ${...} 模式
+    - `{{domain.name}}_data` - 使用 {{...}} 模式
+    - `static_name` - 静态名称 (无替换)
+
+## 使用示例
+
+### 静态使用
+
+```json
+{
+  "task": "publish",
+  "params": {
+    "tag": "machine"
+  }
+}
+```
+
+### 动态使用
+
+```json
+{
+  "task": "publish",
+  "params": {
+    "tag": "#{machine.code}"
+  }
+}
+```
+
+### 混合使用
+
+```json
+{
+  "task": "publish",
+  "params": {
+    "tag": "#{machine.code}_${sensor.code}"
+  }
+}
+```
+
 - [存取器](../concept/data-accessor.md)
   - 作为场景中的步骤名称，指定要广播的数据。
-- 标签
-  - 在广播数据时，需要附加标签。
-  - 当订阅者订阅数据时，他们只能接收具有指定标签的广播。

package/helps/integration/task/pyrun-execute.ja.md

@@ -0,0 +1,36 @@
+# pyrun-execute
+
+pyrun-connector を通じて Python Runner（pyrun）サーバーの REST API（`/api/run/{module}`）を呼び出し、  
+指定した Python モジュールを実行し、その結果を返すタスクです。
+
+## パラメータ
+
+- **module**: 実行する Python モジュール名（必須）
+- **input-params**: （任意）Python モジュールに渡す入力パラメータ（キー・バリューのオブジェクト）
+
+## 使用例
+
+```json
+{
+  "task": "pyrun-execute",
+  "connection": "my-pyrun",
+  "params": {
+    "module": "hello_world",
+    "input": {
+      "name": "山田太郎",
+      "count": 3
+    }
+  }
+}
+```
+
+## 実行結果
+
+- 正常に実行されると、Python モジュールの実行結果（result）が返されます。
+- 実行中の標準出力（stdout）はログに記録され、標準エラー（stderr）が発生した場合はエラーとして処理されます。
+- exit_code が 0 でない場合、タスクは失敗とみなされエラーが発生します。
+
+## 注意事項
+
+- pyrun-connector の認証設定（token または username/password）が必要な場合があります。
+- 入力パラメータは `input` オブジェクトとして Python モジュールに渡されます。

package/helps/integration/task/pyrun-execute.ko.md

@@ -0,0 +1,36 @@
+# pyrun-execute
+
+pyrun-connector를 통해 Python Runner(pyrun) 서버의 REST API(`/api/run/{module}`)를 호출하여  
+지정한 파이썬 모듈을 실행하고, 실행 결과를 반환하는 태스크입니다.
+
+## parameters
+
+- **module**: 실행할 파이썬 모듈명 (필수)
+- **input-params**: (선택) 파이썬 모듈에 전달할 입력 파라미터(키-값 쌍, 오브젝트)
+
+## 사용 예시
+
+```json
+{
+  "task": "pyrun-execute",
+  "connection": "my-pyrun",
+  "params": {
+    "module": "hello_world",
+    "input": {
+      "name": "홍길동",
+      "count": 3
+    }
+  }
+}
+```
+
+## 실행 결과
+
+- 정상적으로 실행되면, 파이썬 모듈의 실행 결과(result)가 반환됩니다.
+- 실행 중 표준 출력(stdout)은 로그로 기록되며, 표준 에러(stderr) 발생 시 에러로 처리됩니다.
+- exit_code가 0이 아니면 태스크가 실패로 간주되어 에러가 발생합니다.
+
+## 참고
+
+- pyrun-connector의 인증 설정(token 또는 username/password)이 필요할 수 있습니다.
+- 입력 파라미터는 파이썬 모듈에서 `input` 오브젝트로 전달됩니다.

package/helps/integration/task/pyrun-execute.md

@@ -0,0 +1,36 @@
+# pyrun-execute
+
+This task calls the Python Runner (pyrun) server's REST API (`/api/run/{module}`) via pyrun-connector,  
+executes the specified Python module, and returns the result.
+
+## parameters
+
+- **module**: Name of the Python module to execute (required)
+- **input-params**: (Optional) Input parameters (key-value object) to pass to the Python module
+
+## Example
+
+```json
+{
+  "task": "pyrun-execute",
+  "connection": "my-pyrun",
+  "params": {
+    "module": "hello_world",
+    "input": {
+      "name": "John Doe",
+      "count": 3
+    }
+  }
+}
+```
+
+## Result
+
+- If successful, returns the result of the Python module execution.
+- Standard output (stdout) is logged, and standard error (stderr) is treated as an error.
+- If exit_code is not 0, the task is considered failed and an error is thrown.
+
+## Notes
+
+- pyrun-connector authentication (token or username/password) may be required.
+- The input parameters are passed as the `input` object to the Python module.