iii-trigger-actions

トリガーアクション

比較対象：RPC、メッセージキュー、ファイア・アンド・フォーゲットのパターン

主な概念

タスクに適している場合は、以下の概念を使用してください。すべての呼び出しで3つのモードすべてを使う必要はありません。

• 同期（デフォルト）：呼び出し元は、関数が結果を返すか、タイムアウトするまで処理をブロックします
• Void（TriggerAction.Void()）：ファイア・アンド・フォーゲットでディスパッチし、すぐにnullを返します。再試行は保証されません
• Enqueue（TriggerAction.Enqueue({ queue })）：名前付きキュー経由で処理し、自動再試行とバックオフを行います。messageReceiptIdを返します
• 選択の目安：結果が必要なら同期を使用します。確実な完了が必要ならEnqueueを使用します。任意の副作用ならVoidを使用します

アーキテクチャ

呼び出し元は、オプションのアクションパラメーターを指定してtrigger()を呼び出します。同期モードではハンドラーの結果を待ちます。Voidモードではディスパッチ後、すぐにnullを返します。Enqueueモードではペイロードを名前付きキューに追加し、コンシューマーが再試行保証付きで処理します。

使用する iii のプリミティブ

プリミティブ	目的
trigger({ function_id, payload })	同期呼び出し。結果が返るまでブロックします
trigger({ ..., action: TriggerAction.Void() })	ファイア・アンド・フォーゲット。すぐにnullを返します
trigger({ ..., action: TriggerAction.Enqueue({ queue }) })	名前付きキューによる耐久性のある非同期処理。レシートを返します
iii trigger --function-id=ID --payload=JSON	CLIトリガー（エンジンバイナリの一部）
--timeout-ms	トリガーのタイムアウトを設定するCLIフラグ（デフォルトは30s）

参考実装

3つの呼び出しモードを比較し、同期、Void、Enqueueの各パターンをいつどのように使うかを示す、動作する完全な例については、../references/trigger-actions.jsを参照してください。

Python版もあります：../references/trigger-actions.py

Rust版もあります：../references/trigger-actions.rs

よくあるパターン

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

• await iii.trigger({ function_id: 'users::get', payload: { id } }) — 同期呼び出し。結果を直接取得します
• iii.trigger({ function_id: 'analytics::track', payload: event, action: TriggerAction.Void() }) — ファイア・アンド・フォーゲット
• iii.trigger({ function_id: 'orders::process', payload: order, action: TriggerAction.Enqueue({ queue: 'payments' }) }) — 耐久性のあるキューへの追加
• 同期呼び出しは関数の結果を直接返します
• Voidはnull / Noneを返します
• Enqueueは追跡用に{ messageReceiptId: string }を返します
• iii trigger --function-id='users::get' --payload='{"id":"123"}' — CLI経由で呼び出します
• iii trigger --function-id='users::get' --payload='{"id":"123"}' --timeout-ms=5000 — カスタムタイムアウトを指定します

このパターンの応用

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

• 呼び出し元が処理を続けるために結果を必要とする場合は、同期をデフォルトにします
• ロギング、分析、または失敗しても問題のない副作用にはVoidを使用します
• 確実に完了させる必要がある処理（支払い、メール、通知など）にはEnqueueを使用します
• 1つのハンドラーでモードを組み合わせます。検証には同期呼び出しを使用し、その後の処理にはEnqueueを使用します
• 名前付きキューを使うと、ワークロードの種類ごとに再試行と並行処理を設定できます

パターンの適用範囲

• キューの設定（再試行、並行処理、FIFO順序）については、iii-engine-configを優先してください。
• キューに追加されたジョブが再試行を使い切った場合のDLQ処理については、iii-dead-letter-queuesを優先してください。
• 関数の登録とトリガーのバインドについては、iii-functions-and-triggersを優先してください。
• 主な課題が適切な呼び出しモードの選択である場合は、iii-trigger-actionsを使用してください。

使用する場面

• タスクの主な対象が iii エンジンの iii-trigger-actions である場合に、このスキルを使用します。
• リクエストでこのパターンまたは同等の実装が直接求められた場合に適用します。

適用範囲

• 関連のないタスクに対する汎用的なフォールバックとして、このスキルを使用しないでください。
• より具体的な iii スキルが適している場合、このスキルを適用してはいけません。
• このスキルの例を適用する前に、必ず環境と安全性の制約を確認してください。