メインコンテンツへスキップ

​
概要

ShannonはTemporalのネイティブSchedule APIを使用して定期タスク実行をサポートします。指定した間隔で自動的にタスクを実行するcronベースのスケジュールを作成できます。

​
機能

  • cronベースのスケジューリング（タイムゾーン対応）
  • リソース制限による乱用防止
  • 予算管理（実行ごとの課金）
  • 実行履歴（コスト追跡付き）
  • 一時停止/再開/削除操作
  • マルチテナント分離（ユーザー/テナント所有権）

​
スケジュール作成

新しい定期タスクスケジュールを作成します。 
curl -X POST http://localhost:8080/api/v1/schedules \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "name": "日次サマリー",
    "description": "日次アクティビティサマリーを生成",
    "cron_expression": "0 9 * * *",
    "timezone": "Asia/Tokyo",
    "task_query": "昨日のアクティビティを要約",
    "task_context": {
      "report_format": "markdown"
    },
    "max_budget_per_run_usd": 5.0,
    "timeout_seconds": 600
  }'

​
リクエストボディ

フィールド型必須説明
namestringはいスケジュール名（最大255文字）
descriptionstringいいえオプションの説明
cron_expressionstringはいCronスケジュール（5フィールド形式）
timezonestringいいえIANAタイムゾーン（デフォルト: UTC）
task_querystringはい実行するクエリ
task_contextobjectいいえタスクの追加コンテキスト
max_budget_per_run_usdnumberいいえ実行ごとの最大予算（デフォルト: 10.0）
timeout_secondsintegerいいえ実行タイムアウト（デフォルト: 600）

​
レスポンス

{
  "schedule_id": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Schedule created successfully",
  "next_run_at": "2025-12-16T09:00:00+09:00"
}

​
スケジュール一覧

ページネーションとフィルタリングでスケジュールを一覧表示します。 
curl "http://localhost:8080/api/v1/schedules?page=1&page_size=50&status=ACTIVE" \
  -H "Authorization: Bearer <token>"

​
クエリパラメータ

パラメータ型デフォルト説明
pageinteger1ページ番号
page_sizeinteger50ページあたりのアイテム数（最大100）
statusstring-ステータスでフィルタ（ACTIVE, PAUSED）

​
レスポンス

{
  "schedules": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "日次サマリー",
      "cron_expression": "0 9 * * *",
      "timezone": "Asia/Tokyo",
      "status": "ACTIVE",
      "next_run_at": "2025-12-16T09:00:00+09:00",
      "total_runs": 45,
      "successful_runs": 43,
      "failed_runs": 2
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 50
}

​
スケジュール詳細取得

特定のスケジュールの詳細を取得します。 
curl "http://localhost:8080/api/v1/schedules/{id}" \
  -H "Authorization: Bearer <token>"

​
レスポンス

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "日次サマリー",
  "description": "日次アクティビティサマリーを生成",
  "cron_expression": "0 9 * * *",
  "timezone": "Asia/Tokyo",
  "task_query": "昨日のアクティビティを要約",
  "task_context": {"report_format": "markdown"},
  "max_budget_per_run_usd": 5.0,
  "timeout_seconds": 600,
  "status": "ACTIVE",
  "created_at": "2025-01-01T00:00:00Z",
  "updated_at": "2025-01-15T10:00:00Z",
  "next_run_at": "2025-01-16T09:00:00+09:00",
  "last_run_at": "2025-01-15T09:00:00+09:00",
  "total_runs": 45,
  "successful_runs": 43,
  "failed_runs": 2
}

​
スケジュール更新

既存のスケジュールを更新します。 
curl -X PUT "http://localhost:8080/api/v1/schedules/{id}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "cron_expression": "0 10 * * *",
    "max_budget_per_run_usd": 8.0
  }'

​
リクエストボディ

すべてのフィールドはオプションです。指定されたフィールドのみ更新されます。
フィールド型説明
namestring新しいスケジュール名
descriptionstring新しい説明
cron_expressionstring新しいcronスケジュール
timezonestring新しいタイムゾーン
task_querystring新しいタスククエリ
task_contextobject新しいコンテキスト
max_budget_per_run_usdnumber新しい予算制限
timeout_secondsinteger新しいタイムアウト

​
実行履歴取得

スケジュールの実行履歴を取得します。 
curl "http://localhost:8080/api/v1/schedules/{id}/runs?page=1&page_size=20" \
  -H "Authorization: Bearer <token>"

​
レスポンス

{
  "runs": [
    {
      "workflow_id": "wf-abc-123",
      "query": "日次レポートを生成",
      "status": "COMPLETED",
      "result": "レポート生成完了...",
      "model_used": "gpt-4o",
      "provider": "openai",
      "total_tokens": 12500,
      "total_cost_usd": 0.45,
      "duration_ms": 150000,
      "triggered_at": "2025-01-15T09:00:00Z",
      "started_at": "2025-01-15T09:00:01Z",
      "completed_at": "2025-01-15T09:02:30Z"
    }
  ],
  "total_count": 45,
  "page": 1,
  "page_size": 20
}

​
レスポンスフィールド

フィールド型説明
runsarrayスケジュール実行記録のリスト
runs[].workflow_idstringこの実行のワークフローID
runs[].querystring実行されたクエリ
runs[].statusstring実行ステータス（例: COMPLETED、FAILED）
runs[].resultstring実行結果（空の場合は省略）
runs[].error_messagestring失敗時のエラーメッセージ（空の場合は省略）
runs[].model_usedstring使用されたLLMモデル（空の場合は省略）
runs[].providerstringLLMプロバイダー（空の場合は省略）
runs[].total_tokensinteger消費された合計トークン数
runs[].total_cost_usdnumber合計コスト（USD）
runs[].duration_msinteger実行時間（ミリ秒、空の場合は省略）
runs[].triggered_atstringトリガー時刻（ISO 8601）
runs[].started_atstring実行開始時刻（空の場合は省略）
runs[].completed_atstring実行完了時刻（空の場合は省略）
total_countinteger実行記録の総数
pageinteger現在のページ番号
page_sizeintegerページあたりのアイテム数

​
スケジュール一時停止

スケジュールを一時停止して今後の実行を停止します。 
curl -X POST "http://localhost:8080/api/v1/schedules/{id}/pause" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"reason": "一時的なメンテナンス"}'

​
レスポンス

{
  "message": "Schedule paused successfully",
  "paused_at": "2025-01-15T10:00:00Z"
}

​
スケジュール再開

一時停止したスケジュールを再開します。 
curl -X POST "http://localhost:8080/api/v1/schedules/{id}/resume" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"reason": "メンテナンス完了"}'

​
レスポンス

{
  "message": "Schedule resumed successfully",
  "next_run_at": "2025-01-16T09:00:00+09:00"
}

​
スケジュール削除

スケジュールを完全に削除します。 
curl -X DELETE "http://localhost:8080/api/v1/schedules/{id}" \
  -H "Authorization: Bearer <token>"

​
レスポンス

{
  "message": "Schedule deleted successfully"
}

​
Cron式フォーマット

標準のcron構文（5フィールド）を使用します: 
┌───────────── 分 (0 - 59)
│ ┌───────────── 時 (0 - 23)
│ │ ┌───────────── 日 (1 - 31)
│ │ │ ┌───────────── 月 (1 - 12)
│ │ │ │ ┌───────────── 曜日 (0 - 6)（日曜日から土曜日）
│ │ │ │ │
* * * * *

​
よく使う例

式説明
0 9 * * *毎日午前9時
0 */4 * * *4時間ごと
0 0 * * 1毎週月曜日の午前0時
30 8 1 * *毎月1日の午前8時30分
0 12 * * 1-5平日の正午
0 0 1,15 * *毎月1日と15日

​
リソース制限

Shannonは乱用を防ぐためリソース制限を強制します:
制限デフォルト環境変数
ユーザーあたりの最大スケジュール数50SCHEDULE_MAX_PER_USER
最小間隔60分SCHEDULE_MIN_INTERVAL_MINS
実行あたりの最大予算$10.00SCHEDULE_MAX_BUDGET_USD
予算制限を超過したスケジュールは自動的に一時停止されます。

​
エラーレスポンス

ステータスエラー説明
400Invalid cron expressionCron構文エラー
400Interval too short最小間隔未満
403Schedule limit reachedユーザーあたりの最大スケジュール数超過
404Schedule not found無効なスケジュールID
409Schedule already paused既に一時停止中のスケジュールは一時停止不可

​
次のステップ

タスク送信

1回限りのタスク送信

Temporal Workflow

Workflow実行を理解する