機能 - Qaptly Docs

機能とは？

機能は、実行ノードが実行できるアクションです。各機能は以下を定義します:

アクション内容 (名前と説明)
入力パラメータ (JSON Schema)
出力データ (JSON Schema)
発火させる可能性のあるイベント

機能構造

{
  "action": "domain.action_name",
  "name": "人間が読める名前",
  "description": "AI とユーザーのための詳細な説明",
  "params": {
    "type": "object",
    "properties": { ... },
    "required": [ ... ]
  },
  "returns": {
    "type": "object",
    "properties": { ... }
  },
  "events": ["event.name1", "event.name2"]
}

必須フィールド

フィールド	型	説明
`action`	string	ユニークなアクション識別子 (`domain.action`)
`name`	string	短い人間が読める名前
`params`	JSON Schema	入力パラメータ定義
`returns`	JSON Schema	出力データ定義

オプションフィールド

フィールド	型	説明
`description`	string	詳細な説明 (AI が使用)
`events`	string[]	このアクションが発火させる可能性のあるイベント

JSON Schema

機能はパラメータと戻り値を定義するために JSON Schema Draft 2020-12 を使用します。

JSON Schema を使う理由

✅ 自己文書化 - データ構造を記述
✅ 検証 - Qaptly は送信前にパラメータを検証
✅ 型安全性 - エラーを早期に検出
✅ AI に優しい - AI があなたの API を理解できる

基本的な型

{
  "type": "string"    // テキスト
}

{
  "type": "number"    // 数値 (整数または浮動小数点)
}

{
  "type": "boolean"   // true/false
}

{
  "type": "array",    // リスト
  "items": { ... }
}

{
  "type": "object",   // 辞書/マップ
  "properties": { ... }
}

機能例

1. シンプルなアクション (パラメータなし)

入力パラメータなしで現在の WiFi ステータスを取得:

{
  "action": "wifi.status",
  "name": "WiFi ステータスを取得",
  "description": "SSID、信号強度、IP アドレスを含む現在の WiFi 接続ステータスを返します",
  "params": {
    "type": "object",
    "properties": {},
    "required": []
  },
  "returns": {
    "type": "object",
    "properties": {
      "connected": {
        "type": "boolean",
        "description": "WiFi が接続されているかどうか"
      },
      "ssid": {
        "type": "string",
        "description": "ネットワーク名 (接続している場合)"
      },
      "signal": {
        "type": "number",
        "description": "信号強度 (dBm)"
      },
      "ip": {
        "type": "string",
        "description": "割り当てられた IP アドレス"
      }
    }
  },
  "events": []
}

2. 必須パラメータ付きアクション

必須 SSID とオプションパスワードで WiFi に接続:

{
  "action": "wifi.connect",
  "name": "WiFi に接続",
  "description": "指定した WiFi ネットワークに接続します。オープン ネットワークではパスワードはオプションです。",
  "params": {
    "type": "object",
    "properties": {
      "ssid": {
        "type": "string",
        "description": "接続する WiFi ネットワークの SSID",
        "minLength": 1,
        "maxLength": 32
      },
      "password": {
        "type": "string",
        "description": "WiFi パスワード (オープン ネットワークでは不要)"
      },
      "timeout": {
        "type": "number",
        "description": "接続タイムアウト (秒)",
        "default": 30,
        "minimum": 5,
        "maximum": 300
      }
    },
    "required": ["ssid"]
  },
  "returns": {
    "type": "object",
    "properties": {
      "connected": {
        "type": "boolean"
      },
      "ip": {
        "type": "string"
      },
      "gateway": {
        "type": "string"
      }
    }
  },
  "events": ["wifi.connected", "wifi.connection_failed"]
}

3. 配列パラメータ付きアクション

複数の GPIO ピンを同時に制御:

{
  "action": "gpio.set_multiple",
  "name": "複数の GPIO ピンを設定",
  "description": "複数の GPIO ピンを HIGH または LOW 状態に同時に設定",
  "params": {
    "type": "object",
    "properties": {
      "pins": {
        "type": "array",
        "description": "ピン設定の配列",
        "items": {
          "type": "object",
          "properties": {
            "pin": {
              "type": "number",
              "description": "GPIO ピン番号",
              "minimum": 0,
              "maximum": 40
            },
            "state": {
              "type": "string",
              "description": "ピンの状態",
              "enum": ["HIGH", "LOW"]
            }
          },
          "required": ["pin", "state"]
        },
        "minItems": 1
      }
    },
    "required": ["pins"]
  },
  "returns": {
    "type": "object",
    "properties": {
      "success": {
        "type": "boolean"
      },
      "updated_pins": {
        "type": "array",
        "items": {
          "type": "number"
        }
      }
    }
  },
  "events": []
}

4. 列挙型選択肢付きアクション

事前定義された選択肢から LED の色を設定:

{
  "action": "led.set_color",
  "name": "LED の色を設定",
  "description": "LED を事前定義された色の 1 つに変更",
  "params": {
    "type": "object",
    "properties": {
      "color": {
        "type": "string",
        "description": "LED の色",
        "enum": ["red", "green", "blue", "yellow", "white", "off"]
      },
      "brightness": {
        "type": "number",
        "description": "明度レベル (0-100)",
        "minimum": 0,
        "maximum": 100,
        "default": 100
      }
    },
    "required": ["color"]
  },
  "returns": {
    "type": "object",
    "properties": {
      "success": {
        "type": "boolean"
      },
      "current_color": {
        "type": "string"
      }
    }
  },
  "events": ["led.color_changed"]
}

JSON Schema 機能

検証制約

{
  "type": "string",
  "minLength": 1,
  "maxLength": 100,
  "pattern": "^[a-zA-Z0-9_]+$"
}

{
  "type": "number",
  "minimum": 0,
  "maximum": 100,
  "multipleOf": 5
}

{
  "type": "array",
  "minItems": 1,
  "maxItems": 10,
  "uniqueItems": true
}

デフォルト値

{
  "properties": {
    "timeout": {
      "type": "number",
      "default": 30,
      "description": "リクエスト タイムアウト (秒)"
    }
  }
}

列挙型

{
  "properties": {
    "mode": {
      "type": "string",
      "enum": ["auto", "manual", "scheduled"],
      "description": "操作モード"
    }
  }
}

ネストされたオブジェクト

{
  "properties": {
    "config": {
      "type": "object",
      "properties": {
        "host": {"type": "string"},
        "port": {"type": "number"},
        "ssl": {"type": "boolean"}
      },
      "required": ["host", "port"]
    }
  }
}

イベント宣言

機能が発火させる可能性のあるイベントを宣言:

{
  "action": "wifi.scan",
  "events": [
    "wifi.scan_complete",
    "wifi.scan_failed",
    "wifi.network_found"
  ]
}

ベストプラクティス: このアクションに直接関連するイベントのみをリストに含めてください。実行ノードが出力できるすべての可能なイベントをリストに含めないでください。

アクション命名規則

形式

domain.action

標準ドメイン

ドメイン	用途	例
`wifi`	WiFi 制御	`scan`, `connect`, `disconnect`, `status`
`bluetooth`	Bluetooth	`scan`, `pair`, `unpair`
`network`	ネットワーク診断	`ping`, `traceroute`, `dns_lookup`
`gpio`	ハードウェア GPIO	`read`, `write`, `mode`
`sensor`	センサー読み取り	`temperature`, `humidity`, `pressure`
`system`	システム操作	`reboot`, `shutdown`, `info`
`file`	ファイル操作	`read`, `write`, `list`, `delete`

カスタムドメイン

ベンダー固有のアクションの場合は以下を使用:

vendor.domain.action

例:

acme.motor.rotate
acme.motor.stop
acme.motor.set_speed

説明のベストプラクティス

適切な説明は AI が実行ノードを理解するのに役立ちます:

❌ 不十分な説明

{
  "description": "WiFi をスキャン"
}

✅ 良い説明

{
  "description": "範囲内で利用可能な WiFi ネットワークをスキャンし、SSID、dBm 単位の信号強度、MHz 単位の周波数、セキュリティ タイプ (open、WEP、WPA、WPA2、WPA3) を返します"
}

ガイドライン

具体的に - 正確に何をするのか?
重要なデータを言及 - どのような情報が返されるのか?
単位を含める - dBm、MHz、秒など
副作用を記載 - 状態が変わるのか?
AI のために記述 - 将来の AI 統合では説明が使用されます

完全な例

すべての機能を含む包括的な機能:

{
  "action": "sensor.read_temperature",
  "name": "温度センサーを読み取り",
  "description": "DHT22 センサーから現在の温度を読み取り、摂氏または華氏で値を返します。必要に応じてキャリブレーション オフセットを適用します。前回の読み取りから 0.5 度以上異なる場合、temperature_changed イベントをトリガーします。",
  "params": {
    "type": "object",
    "properties": {
      "unit": {
        "type": "string",
        "description": "温度単位",
        "enum": ["celsius", "fahrenheit"],
        "default": "celsius"
      },
      "offset": {
        "type": "number",
        "description": "適用するキャリブレーション オフセット (選択した単位)",
        "default": 0,
        "minimum": -10,
        "maximum": 10
      },
      "precision": {
        "type": "number",
        "description": "小数点以下の桁数",
        "enum": [0, 1, 2],
        "default": 1
      }
    },
    "required": []
  },
  "returns": {
    "type": "object",
    "properties": {
      "temperature": {
        "type": "number",
        "description": "現在の温度読み取り値"
      },
      "unit": {
        "type": "string",
        "description": "使用された測定単位"
      },
      "timestamp": {
        "type": "string",
        "description": "読み取りの ISO 8601 タイムスタンプ",
        "format": "date-time"
      },
      "sensor_id": {
        "type": "string",
        "description": "センサー ハードウェア識別子"
      }
    }
  },
  "events": ["sensor.temperature_changed", "sensor.read_error"]
}

検証

Qaptly はコマンドを送信する前にパラメータを検証:

# Qaptly からのコマンド
{
  "action": "wifi.connect",
  "params": {
    "ssid": "HomeWiFi",
    "timeout": 45
  }
}

# ✅ 有効: すべての必須パラメータが存在し、型が正しい

# ❌ 無効: 必須パラメータが欠落
{
  "action": "wifi.connect",
  "params": {
    "timeout": 45  // "ssid" が欠落
  }
}

# ❌ 無効: 型が違う
{
  "action": "wifi.connect",
  "params": {
    "ssid": 12345,  // string である必要があります
    "timeout": "45"  // number である必要があります
  }
}

動的機能 (高度)

機能が変わる実行ノード (検出されたセンサーなど) の場合、以下が可能:

初期登録 - 基本的な機能で登録
検出 - 利用可能なハードウェアを検出
再接続 - 更新された機能で切断して再接続

# 新しいセンサーを検出した後
async def update_capabilities():
    # 現在の接続を閉じる
    await websocket.close()

    # 新しい機能を追加
    capabilities.append({
        "action": "sensor.read_humidity",
        "name": "湿度センサーを読み取り",
        ...
    })

    # 更新された機能で再接続
    await connect_and_register()

機能の更新には切断と再登録が必要です。実行ノードアーキテクチャを適切に計画してください。

機能をテスト

JSON Schema 定義をテスト:

import jsonschema

# スキーマを定義
schema = {
    "type": "object",
    "properties": {
        "ssid": {"type": "string"},
        "timeout": {"type": "number"}
    },
    "required": ["ssid"]
}

# 有効なパラメータ
params = {"ssid": "HomeWiFi", "timeout": 30}
jsonschema.validate(params, schema)  # ✅ エラーなし

# 無効なパラメータ
params = {"timeout": 30}  # ssid がありません
jsonschema.validate(params, schema)  # ❌ ValidationError

次のステップ

プロトコルリファレンス

メッセージ形式仕様

例

完全に動作する実装

クイックスタート

最初の実行ノードを構築

認証

セキュリティとキー管理

Android Pilot

iOS Pilot

カスタム Pilots (UPP)

機能

機能とは？

機能構造

必須フィールド

オプションフィールド

JSON Schema

JSON Schema を使う理由

基本的な型

機能例

1. シンプルなアクション (パラメータなし)

2. 必須パラメータ付きアクション

3. 配列パラメータ付きアクション

4. 列挙型選択肢付きアクション

JSON Schema 機能

検証制約

デフォルト値

列挙型

ネストされたオブジェクト

イベント宣言

アクション命名規則

形式

標準ドメイン

カスタムドメイン

説明のベストプラクティス

❌ 不十分な説明

✅ 良い説明

ガイドライン

完全な例

検証

動的機能 (高度)

機能をテスト

次のステップ

プロトコルリファレンス

例

クイックスタート

認証

​機能とは？

​機能構造

​必須フィールド

​オプションフィールド

​JSON Schema

​JSON Schema を使う理由

​基本的な型

​機能例

​1. シンプルなアクション (パラメータなし)

​2. 必須パラメータ付きアクション

​3. 配列パラメータ付きアクション

​4. 列挙型選択肢付きアクション

​JSON Schema 機能

​検証制約

​デフォルト値

​列挙型

​ネストされたオブジェクト

​イベント宣言

​アクション命名規則

​形式

​標準ドメイン

​カスタムドメイン

​説明のベストプラクティス

​❌ 不十分な説明

​✅ 良い説明

​ガイドライン

​完全な例

​検証

​動的機能 (高度)

​機能をテスト

​次のステップ

プロトコルリファレンス

例

クイックスタート

認証

機能とは？

機能構造

必須フィールド

オプションフィールド

JSON Schema

JSON Schema を使う理由

基本的な型

機能例

1. シンプルなアクション (パラメータなし)

2. 必須パラメータ付きアクション

3. 配列パラメータ付きアクション

4. 列挙型選択肢付きアクション

JSON Schema 機能

検証制約

デフォルト値

列挙型

ネストされたオブジェクト

イベント宣言

アクション命名規則

形式

標準ドメイン

カスタムドメイン

説明のベストプラクティス

❌ 不十分な説明

✅ 良い説明

ガイドライン

完全な例

検証

動的機能 (高度)

機能をテスト

次のステップ