iii-custom-triggers

カスタムトリガー

同等の機能：カスタムイベントアダプター、Webhook レシーバー

主な概念

タスクに該当する場合は、以下の概念を使用してください。すべてのカスタムトリガーに必要なわけではありません。

• registerTriggerType(id, handler) は、registerTrigger および unregisterTrigger コールバックを備えた新しいトリガータイプを定義します
• ハンドラーには、id、function_id、config を含む TriggerConfig が渡されます
• 外部イベントが発生したら、iii.trigger(function_id, event) を呼び出して登録済みの関数を実行します
• トリガータイプが不要になったら、unregisterTriggerType でクリーンアップします
• 組み込みのトリガータイプ名（http、cron、queue、state、stream、subscribe）を再利用しないでください

アーキテクチャ

外部イベントソース（Webhook、ファイル監視、IoT、CDC など）
  → カスタムトリガーハンドラー（registerTriggerType）
    → iii.trigger(function_id, event)
      → 登録済みの関数がイベントを処理

使用する iii プリミティブ

プリミティブ	用途
registerTriggerType(id, handler)	ライフサイクルフックを備えた新しいトリガータイプを定義します
unregisterTriggerType(id)	カスタムトリガータイプをクリーンアップします
TriggerConfig: { id, function_id, config }	トリガーハンドラーに渡される設定
iii.trigger(function_id, event)	イベント発生時に登録済みの関数を実行します

リファレンス実装

完全な動作例については、../references/custom-triggers.js を参照してください。外部イベントを監視し、登録済みの関数に振り分けるカスタムトリガータイプの例です。

Python 版も利用できます：../references/custom-triggers.py

Rust 版も利用できます：../references/custom-triggers.rs

一般的なパターン

このパターンを使用するコードには、該当する場合、一般に以下が含まれます。

• registerWorker(url, { workerName }) — ワーカーの初期化
• registerTriggerType(id, { registerTrigger, unregisterTrigger }) — カスタムトリガーを定義します
• registerTrigger(config) — 関数がこのトリガータイプを購読するときに iii が呼び出します
• unregisterTrigger(config) — 関数が購読を解除するときに iii が呼び出します
• iii.trigger(config.function_id, eventPayload) — 対象の関数を実行します
• unregisterTrigger 内のクリーンアップロジック（接続を閉じる、リスナーを削除する、インターバルをクリアする）
• const logger = new Logger() — 構造化ロギング

このパターンの適用

タスクに該当する場合は、以下の方法で適用してください。

• イベントソースを表す一意のトリガータイプ名（例：file-watcher、mqtt、db-cdc）を選びます
• registerTrigger でリスナーを開始します（ソケットを開く、エンドポイントをポーリングする、トピックを購読する）
• リソースリークを防ぐため、unregisterTrigger でリスナーを停止します
• 登録解除を適切に行えるよう、config.id をキーとしてアクティブなリスナーをマップに保存します
• iii.trigger(function_id, event) の呼び出し時に、関連するイベントデータをペイロードに含めます

パターンの適用範囲

• タスクで組み込みの HTTP ルートを使用する場合は、iii-http-endpoints を優先してください。
• タスクで組み込みの cron スケジュールを使用する場合は、iii-cron-scheduling を優先してください。
• タスクで組み込みのキュートリガーを使用する場合は、iii-queue-processing を優先してください。
• イベントソースに対応する組み込みトリガータイプが iii にない場合は、iii-custom-triggers を使用してください。

使用する場面

• タスクの主な内容が iii エンジンでの iii-custom-triggers に関する場合は、このスキルを使用してください。
• リクエストでこのパターンまたは同等の実装が直接求められている場合に使用します。

適用範囲

• 無関係なタスクへの汎用的な代替手段として、このスキルを使用しないでください。
• より具体的な iii スキルが適している場合、このスキルを適用してはいけません。
• このスキルの例を適用する前に、必ず環境と安全性の制約を確認してください。