@things-factory/integration-base 9.0.5 → 9.0.12

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

@@ -0,0 +1,36 @@
+# pyrun-execute
+
+Tugas ini memanggil REST API pelayan Python Runner (pyrun) (`/api/run/{module}`) melalui pyrun-connector,  
+menjalankan modul Python yang ditetapkan dan memulangkan hasilnya.
+
+## Parameter
+
+- **module**: Nama modul Python yang hendak dijalankan (wajib)
+- **input-params**: (Pilihan) Parameter input (objek pasangan kunci-nilai) untuk dihantar ke modul Python
+
+## Contoh Penggunaan
+
+```json
+{
+  "task": "pyrun-execute",
+  "connection": "my-pyrun",
+  "params": {
+    "module": "hello_world",
+    "input": {
+      "name": "Ali",
+      "count": 3
+    }
+  }
+}
+```
+
+## Hasil
+
+- Jika berjaya, hasil pelaksanaan modul Python akan dipulangkan.
+- Output piawai (stdout) akan direkodkan dalam log, dan ralat piawai (stderr) akan dianggap sebagai ralat.
+- Jika exit_code bukan 0, tugas dianggap gagal dan ralat akan dibangkitkan.
+
+## Nota
+
+- Pengesahan pyrun-connector (token atau username/password) mungkin diperlukan.
+- Parameter input akan dihantar sebagai objek `input` ke modul Python.

package/helps/integration/task/pyrun-execute.zh.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/state-read.ja.md

@@ -1,8 +1,48 @@
 # state-read
 
-[状態登録簿(state-register)](../concept/state-register.md)で定義されている状態の値を読み取るタスクです。
+[状態登録簿(state-register)](../concept/state-register.md)に定義された一つの状態から値を読み取るタスクです。
 
 ## パラメーター
 
 - 名前
-  - 取得する状態の「名前」を指定します
+  - 読み取りたい対象状態の「名前」を指定します
+  - **動的サポート**: 以下のパターンを使用した動的置換をサポートします:
+    - `#{user.id}_status` - #{...} パターン使用
+    - `${user.role}_prefs` - ${...} パターン使用
+    - `{{domain.name}}_data` - {{...}} パターン使用
+    - `static_name` - 静的名前 (置換なし)
+
+## 使用例
+
+### 静的使用
+
+```json
+{
+  "task": "state-read",
+  "params": {
+    "name": "machine-10"
+  }
+}
+```
+
+### 動的使用
+
+```json
+{
+  "task": "state-read",
+  "params": {
+    "name": "#{machine.code}"
+  }
+}
+```
+
+### 混合使用
+
+```json
+{
+  "task": "state-read",
+  "params": {
+    "name": "#{machine.code}_${sensor.code}"
+  }
+}
+```

package/helps/integration/task/state-read.ko.md

@@ -1,8 +1,48 @@
 # state-read
 
-[상태등록부(state-register)](../concept/state-register.md)에 정의된 하나의 상태의 값을 읽어오는 태스크이다.
+[상태등록부(state-register)](../concept/state-register.md)에 정의된 하나의 상태에 값을 읽는 태스크이다.
 
 ## parameters
 
 - name
-  - 가져올 상태 "이름"을 지정한다
+  - 읽고자 하는 대상 상태 "이름"을 지정한다
+  - **동적 지원**: 다음 패턴을 사용한 동적 치환을 지원합니다:
+    - `#{user.id}_status` - #{...} 패턴 사용
+    - `${user.role}_prefs` - ${...} 패턴 사용
+    - `{{domain.name}}_data` - {{...}} 패턴 사용
+    - `static_name` - 정적 이름 (치환 없음)
+
+## 사용 예시
+
+### 정적 사용
+
+```json
+{
+  "task": "state-read",
+  "params": {
+    "name": "machine-10"
+  }
+}
+```
+
+### 동적 사용
+
+```json
+{
+  "task": "state-read",
+  "params": {
+    "name": "#{machine.code}"
+  }
+}
+```
+
+### 혼합 사용
+
+```json
+{
+  "task": "state-read",
+  "params": {
+    "name": "#{machine.code}_${sensor.code}"
+  }
+}
+```

package/helps/integration/task/state-read.md

@@ -1,8 +1,48 @@
 # state-read
 
-[State Register](../concept/state-register.md) defines a task to read the value of a state.
+[State Register](../concept/state-register.md) defines a task to read values from one state.
 
 ## parameters
 
 - name
-  - Specifies the "name" of the state to be retrieved
+  - Specifies the "name" of the target state to be read
+  - **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": "state-read",
+  "params": {
+    "name": "machine-10"
+  }
+}
+```
+
+### Dynamic Usage
+
+```json
+{
+  "task": "state-read",
+  "params": {
+    "name": "#{machine.code}"
+  }
+}
+```
+
+### Mixed Usage
+
+```json
+{
+  "task": "state-read",
+  "params": {
+    "name": "#{machine.code}_${sensor.code}"
+  }
+}
+```

package/helps/integration/task/state-read.ms.md

@@ -1,8 +1,48 @@
 # state-read
 
-[Daftar keadaan(state-register)](../concept/state-register.md) mendefinisikan tugas untuk membaca nilai suatu keadaan.
+[Daftar keadaan(state-register)](../concept/state-register.md) mendefinisikan tugas untuk membaca nilai dari satu keadaan.
 
 ## parameter
 
 - nama
-  - Menentukan "nama" keadaan yang hendak diambil
+  - Menentukan "nama" keadaan sasaran yang ingin dibaca
+  - **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": "state-read",
+  "params": {
+    "name": "machine-10"
+  }
+}
+```
+
+### Penggunaan Dinamik
+
+```json
+{
+  "task": "state-read",
+  "params": {
+    "name": "#{machine.code}"
+  }
+}
+```
+
+### Penggunaan Campuran
+
+```json
+{
+  "task": "state-read",
+  "params": {
+    "name": "#{machine.code}_${sensor.code}"
+  }
+}
+```

package/helps/integration/task/state-read.zh.md

@@ -1,8 +1,48 @@
 # state-read
 
-[状态登记册(state-register)](../concept/state-register.md)中定义了一个状态值的读取任务。
+[状态登记册(state-register)](../concept/state-register.md)中定义了从一个状态读取值的任务。
 
 ## 参数
 
 - 名称
-  - 指定要获取的状态的“名称”
+  - 指定要读取的目标状态的"名称"
+  - **动态支持**: 支持使用以下模式的动态替换:
+    - `#{user.id}_status` - 使用 #{...} 模式
+    - `${user.role}_prefs` - 使用 ${...} 模式
+    - `{{domain.name}}_data` - 使用 {{...}} 模式
+    - `static_name` - 静态名称 (无替换)
+
+## 使用示例
+
+### 静态使用
+
+```json
+{
+  "task": "state-read",
+  "params": {
+    "name": "machine-10"
+  }
+}
+```
+
+### 动态使用
+
+```json
+{
+  "task": "state-read",
+  "params": {
+    "name": "#{machine.code}"
+  }
+}
+```
+
+### 混合使用
+
+```json
+{
+  "task": "state-read",
+  "params": {
+    "name": "#{machine.code}_${sensor.code}"
+  }
+}
+```

package/helps/integration/task/state-write.ja.md

@@ -8,5 +8,48 @@
 
 - 名前
   - 書き込みたい対象状態の「名前」を指定します
+  - **動的サポート**: 以下のパターンを使用した動的置換をサポートします:
+    - `#{user.id}_status` - #{...} パターン使用
+    - `${user.role}_prefs` - ${...} パターン使用
+    - `{{domain.name}}_data` - {{...}} パターン使用
+    - `static_name` - 静的名前 (置換なし)
 - [アクセサ](../concept/data-accessor.md)
   - シナリオ内のステップ名で、書き込みたいデータを指定します。
+
+## 使用例
+
+### 静的使用
+
+```json
+{
+  "task": "state-write",
+  "params": {
+    "name": "user_status",
+    "accessor": "machine-10"
+  }
+}
+```
+
+### 動的使用
+
+```json
+{
+  "task": "state-write",
+  "params": {
+    "name": "#{machine.code}",
+    "accessor": "result.status"
+  }
+}
+```
+
+### 混合使用
+
+```json
+{
+  "task": "state-write",
+  "params": {
+    "name": "#{machine.code}_${sensor.code}",
+    "accessor": "user.preferences"
+  }
+}
+```

package/helps/integration/task/state-write.ko.md

@@ -8,5 +8,48 @@
 
 - name
   - 쓰고자 하는 대상 상태 "이름"을 지정한다
+  - **동적 지원**: 다음 패턴을 사용한 동적 치환을 지원합니다:
+    - `#{user.id}_status` - #{...} 패턴 사용
+    - `${user.role}_prefs` - ${...} 패턴 사용
+    - `{{domain.name}}_data` - {{...}} 패턴 사용
+    - `static_name` - 정적 이름 (치환 없음)
 - [accessor](../concept/data-accessor.md)
   - 시나리오 내의 하나의 스텝이름으로, 쓰고자 하는 데이타를 지정한다.
+
+## 사용 예시
+
+### 정적 사용
+
+```json
+{
+  "task": "state-write",
+  "params": {
+    "name": "user_status",
+    "accessor": "machine-10"
+  }
+}
+```
+
+### 동적 사용
+
+```json
+{
+  "task": "state-write",
+  "params": {
+    "name": "#{machine.code}",
+    "accessor": "result.status"
+  }
+}
+```
+
+### 혼합 사용
+
+```json
+{
+  "task": "state-write",
+  "params": {
+    "name": "#{machine.code}_${sensor.code}",
+    "accessor": "user.preferences"
+  }
+}
+```

package/helps/integration/task/state-write.md

@@ -1,12 +1,55 @@
 # state-write
 
-[State Register](../concept/state-register.md) defines a task for writing a value to a state.
+[State Register](../concept/state-register.md) defines a task to write values to one state.
 
-> ⚠️ If the StateRegister with the specified name has autoPublish enabled, writing a value will automatically trigger a data publish event.
+> ⚠️ If autoPublish is set to true in the StateRegister with the specified name, data publish will automatically occur when writing values.
 
 ## parameters
 
 - name
   - Specifies the "name" of the target state to be written
+  - **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)
 - [accessor](../concept/data-accessor.md)
-  - A step name within the scenario, specifying the data to be written.
+  - As a step name within the scenario, specifies the data to be written.
+
+## Usage Examples
+
+### Static Usage
+
+```json
+{
+  "task": "state-write",
+  "params": {
+    "name": "user_status",
+    "accessor": "machine-10"
+  }
+}
+```
+
+### Dynamic Usage
+
+```json
+{
+  "task": "state-write",
+  "params": {
+    "name": "#{machine.code}",
+    "accessor": "result.status"
+  }
+}
+```
+
+### Mixed Usage
+
+```json
+{
+  "task": "state-write",
+  "params": {
+    "name": "#{machine.code}_${sensor.code}",
+    "accessor": "user.preferences"
+  }
+}
+```

package/helps/integration/task/state-write.ms.md

@@ -8,5 +8,48 @@
 
 - nama
   - Menentukan "nama" keadaan sasaran yang ingin ditulis
+  - **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)
 - [aksesor](../concept/data-accessor.md)
   - Sebuah nama langkah dalam skenario, yang menentukan data yang ingin ditulis.
+
+## Contoh Penggunaan
+
+### Penggunaan Statik
+
+```json
+{
+  "task": "state-write",
+  "params": {
+    "name": "user_status",
+    "accessor": "machine-10"
+  }
+}
+```
+
+### Penggunaan Dinamik
+
+```json
+{
+  "task": "state-write",
+  "params": {
+    "name": "#{machine.code}",
+    "accessor": "result.status"
+  }
+}
+```
+
+### Penggunaan Campuran
+
+```json
+{
+  "task": "state-write",
+  "params": {
+    "name": "#{machine.code}_${sensor.code}",
+    "accessor": "user.preferences"
+  }
+}
+```

package/helps/integration/task/state-write.zh.md

@@ -7,6 +7,49 @@
 ## 参数
 
 - 名称
-  - 指定要写入的目标状态的“名称”
+  - 指定要写入的目标状态的"名称"
+  - **动态支持**: 支持使用以下模式的动态替换:
+    - `#{user.id}_status` - 使用 #{...} 模式
+    - `${user.role}_prefs` - 使用 ${...} 模式
+    - `{{domain.name}}_data` - 使用 {{...}} 模式
+    - `static_name` - 静态名称 (无替换)
 - [访问器](../concept/data-accessor.md)
   - 在场景中的一个步骤名称，用于指定要写入的数据。
+
+## 使用示例
+
+### 静态使用
+
+```json
+{
+  "task": "state-write",
+  "params": {
+    "name": "user_status",
+    "accessor": "machine-10"
+  }
+}
+```
+
+### 动态使用
+
+```json
+{
+  "task": "state-write",
+  "params": {
+    "name": "#{machine.code}",
+    "accessor": "result.status"
+  }
+}
+```
+
+### 混合使用
+
+```json
+{
+  "task": "state-write",
+  "params": {
+    "name": "#{machine.code}_${sensor.code}",
+    "accessor": "user.preferences"
+  }
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/integration-base",
-  "version": "9.0.5",
+  "version": "9.0.12",
   "main": "dist-server/index.js",
   "browser": "client/index.js",
   "things-factory": true,
@@ -45,5 +45,5 @@
     "readline": "^1.3.0",
     "ses": "^1.5.0"
   },
-  "gitHead": "da760d5cf77e2495da74360b1cdc1f99f13bb65f"
+  "gitHead": "2bb9eb1ca59f8b080ae7b0589c1cc085fe0f8a3f"
 }

package/translations/en.json

@@ -8,6 +8,7 @@
   "label.auth-key": "authentication key",
   "label.connectionTimeoutMillis": "Connection Timeout (milliseconds)",
   "label.idleTimeoutMillis": "Idle Timeout (milliseconds)",
+  "label.input-params": "input parameters",
   "label.login-api-url": "login API URL",
   "label.login-page-path": "login page path",
   "label.maxPoolConnection": "Max Pool Connection",

package/translations/ja.json

@@ -8,6 +8,7 @@
   "label.auth-key": "認証キー",
   "label.connectionTimeoutMillis": "接続タイムアウト（ミリ秒）",
   "label.idleTimeoutMillis": "アイドルタイムアウト（ミリ秒）",
+  "label.input-params": "入力パラメータ",
   "label.login-api-url": "ログインAPI URL",
   "label.login-page-path": "ログインページパス",
   "label.maxPoolConnection": "最大プール接続数",

package/translations/ko.json

@@ -8,6 +8,7 @@
   "label.auth-key": "인증 키",
   "label.connectionTimeoutMillis": "연결 시간 제한 (밀리초)",
   "label.idleTimeoutMillis": "유휴 시간 제한 (밀리초)",
+  "label.input-params": "입력 파라미터",
   "label.login-api-url": "로그인 API URL",
   "label.login-page-path": "로그인 페이지 경로",
   "label.maxPoolConnection": "최대 풀 연결 수",

package/translations/ms.json

@@ -8,6 +8,7 @@
   "label.auth-key": "Kunci pengesahan",
   "label.connectionTimeoutMillis": "Had Masa Sambungan (milisaat)",
   "label.idleTimeoutMillis": "Had Masa Tanpa Aktiviti (milisaat)",
+  "label.input-params": "parameter input",
   "label.login-api-url": "URL API log masuk",
   "label.login-page-path": "laluan halaman log masuk",
   "label.maxPoolConnection": "Sambungan Pool Maksimum",

package/translations/zh.json

@@ -8,6 +8,7 @@
   "label.auth-key": "认证密钥",
   "label.connectionTimeoutMillis": "连接超时时间（毫秒）",
   "label.idleTimeoutMillis": "空闲超时时间（毫秒）",
+  "label.input-params": "输入参数",
   "label.login-api-url": "登录API URL",
   "label.login-page-path": "登录页面路径",
   "label.maxPoolConnection": "最大连接池连接数",