catalyst-job-scheduling

Catalyst のジョブスケジューリング

ジョブスケジューリングでは、バックグラウンド処理を3つの要素で実行します。ジョブプール（容量を管理するコンテナ）、ジョブ（API／SDK／MCP経由で即時に送信する1回の実行）、cron（スケジュールに従ってジョブを送信するスケジューラー）です。このスキルと参照資料に記載された事実は、特に記載がない限り、稼働中のCatalystプロジェクト（2026年8月）で実行時に検証済みです。

前提条件

操作を行う前に、references/job-scheduling-basics.mdを読み込んでください。ほとんどの失敗の原因となる5つのセットアップルールを解説しています。ジョブプールは先に作成する必要がある（デフォルトはない）、ターゲットはJOBタイプの関数である必要がある、すべての時間値は秒単位、job_nameの制限、関数とプールのメモリ制約です。

仕組み

1. ターゲットのタイプを特定する：ジョブ関数（最も一般的）、Webhook（任意のHTTP URL）、Circuit、AppSailのいずれかです。一致するタイプのジョブプールを作成／確認します（Functionプールはmemory（MB）でサイズを指定し、それ以外は同時実行数number（1～10）で指定します）。
2. 単発の処理 → 即時ジョブを送信する（MCPのCatalystbyZoho_Create_Immediate_JobまたはSDKのjobScheduling().job().submitJob()）。繰り返しまたは遅延させる処理 → Periodic／OneTime／Calendar／CronExpressionを選択してcronを作成します（CatalystbyZoho_Create_Cron_JobまたはSDKのcron().createCron()）。どちらの方法でも正確なペイロードについては、references/job-scheduling-basics.mdを読み込んでください。
3. ジョブ関数のハンドラーを記述する (jobRequest, context)：catalyst.initialize(context, { scope: 'admin' })でSDKを初期化し、jobRequest.getAllJobParams()で入力を読み取ります（すべての値は文字列として渡されます）。最後に必ずcontext.closeWithSuccess()またはcloseWithFailure()を呼び出してください。失敗するとリトライチェーンが開始されます。
4. リトライ、動的スケジューリング、Webhookターゲット、またはモニタリングを行う場合は、references/job-scheduling-advanced.mdを読み込んでください。リトライのセマンティクス（parent_job_idで関連付けられた新しいジョブレコード）、発火時の動作（Periodic cronは作成時と更新時に即時発火し、過去の日付のOneTimeは即時発火し、OneTimeは発火後に自動的に無効化されます）、可観測性に関する注意点（成功／失敗カウンターは0のまま、動的cronはリストAPIに表示されません）について説明しています。
5. カウンターではなくジョブレコードで確認する：CatalystbyZoho_Get_Job_By_Idでは、job_status（PENDING → RUNNING → SUCCESS | FAILURE）、execution_time、dispatch_delay、response_codeを確認できます。cronのsuccess_count／failure_countは0のままなので、信用しないでください。

セキュリティチェックリスト

• jobRequest.getJobDetails()やgetJobMetaDetails()を丸ごとログに記録しないでください。実行時にそれらのheadersには有効な認証情報（X-ZC-PROJECT-SECRET-KEY、X-ZC-Admin-Cred-Token）が含まれます。必要なフィールドだけを抽出してください。
• 自分のプロジェクトの関数URLをターゲットとするWebhookジョブには、同じ認証情報ヘッダーが含まれます。Webhook受信側のログは機密情報として扱ってください。
• ジョブ関数は管理者権限で実行されます。params経由で受け取った値をクエリに使う前に、検証し、許可リストと照合してください。
• ジョブのheaders／paramsにシークレットを保存しないでください。Get_Job_By_Id／Get_Cron_Job_By_Id／List_All_Cronsでは、それらが平文で返されます。cron／ジョブのダンプをそのままチャット、課題、ログに貼り付けないでください。

ハルシネーション防止の注意点

• SDKの列挙値CRON_TYPE.CALENDER（「Calender」）はスペルミスで、サーバーに拒否されます。文字列'Calendar'を使用してください。
• retry_intervalの単位はミリ秒ではありません。秒単位で、60～86400です。15 * 60 * 1000は拒否されます。
• 即時ジョブとスケジュール済みジョブのタイムアウトは、どちらも15分です。context.getMaxExecutionTimeMs()は文字列"900000"を返します（計算前にparseIntを使用してください）。一方、getRemainingExecutionTimeMs()は数値を返します。

トリガー

• 「ジョブのスケジュール設定」、「ジョブプール」、「jobpool」、jobpool_id、「ジョブプールを作成」
• 「ジョブを送信」、「即時ジョブ」、「バックグラウンドジョブ」、「この関数をジョブとして実行」、submitJob、Create_Immediate_Job
• 「cron」、「cron ジョブ」、「スケジュール済み関数」、「関数をスケジュール設定」、「繰り返しジョブ」、createCron、Create_Cron_Job、cron_expression、time_of_execution、「Periodic」、「OneTime cron」、「Calendar cron」
• 「ジョブを再試行」、number_of_retries、retry_interval、parent_job_id、「督促」、「請求スケジュール」、「トライアル期限切れジョブ」
• pauseCron、resumeCron、runCron、deleteCron、「cron を一時停止」、「cron を手動で実行」、Submit_Cron_Job
• エラー：「指定された関数はジョブ関数ではありません」、「job_name に使用できるのは英数字とアンダースコアのみです」、「job_name は1～20文字にしてください」、「再試行間隔は60秒以内にしてください」、「ジョブプールを削除する前に、関連するすべての事前定義済み cron を削除してください」、「ジョブ関数に割り当てられたメモリが多すぎます」
• 「Webhook ジョブ」、「スケジュールに従って URL を呼び出す」、notify_url

参考資料

ファイル	クエリの内容に応じて読み込む資料
references/job-scheduling-basics.md	基本概念、ジョブプール、即時ジョブ、4種類すべての cron、MCP ツールのワークフロー、Node SDK の呼び出し、ジョブ関数ハンドラーのテンプレート、CLI の設定
references/job-scheduling-advanced.md	再試行の動作、動的（コード内）cron の作成、実行・タイミングの動作、Webhook を宛先とするジョブ、notify_url、監視・可観測性、セキュリティ上のガードレール、プール容量のルール