スケジューラーを使う（ベータ版）

hanamii のスケジューラーは、「毎朝 10 時に」「毎時 0 分に」のように決めた時刻に、デプロイしたアプリの指定した URL（パス）へ hanamii がリクエストを送る機能です（ベータ版）。いわゆる cron の代わりに使えます。

たとえば次のような処理に向いています。

• 毎日決まった時刻に、集計やレポートの作成を走らせる
• 定期的に外部 API からデータを取り込んで、データベースを更新する
• 期限切れのデータやセッションを毎晩まとめて削除する
• 1 日 1 回、お知らせメールやリマインドを送る

スケジューラーはプロジェクト詳細の スケジューラー タブで管理します。

しくみ

1. 設定した時刻になると、hanamii がアプリの指定したパスへ GET リクエスト を送ります
2. リクエストには Authorization: Bearer <秘密の値> ヘッダーが付きます。秘密の値は hanamii が自動で作り、アプリの環境変数 HANAMII_SCHEDULER_SECRET として渡します
3. アプリ側は、そのヘッダーを確認してから処理を実行し、応答を返します
4. 結果（HTTP ステータスと処理時間）が 実行履歴 に残ります

つまり、スケジューラーは「時刻になったらアプリを呼ぶ」役割だけを持ち、実際の処理はアプリの中に書きます。設定しただけでは何も実行されません。 処理を受け取る入口をアプリ側に用意してください。

前提

• スケジュールを追加・変更・削除できるのは、ワークスペースの オーナー・管理者・開発者 です。閲覧者はスケジュールと履歴を見るだけになります
• 対象のプロジェクトがデプロイ済みで、アプリが動いている必要があります
• 1 回のリクエストは、接続にかかる時間も含めて 5 分以内 に応答を返してください。5 分を超えた回は「タイムアウト」として記録されます
• 時刻は 分単位 で指定します。秒単位の指定はできません
• ベータ版のため、仕様や上限は今後変更される場合があります

1. アプリにリクエストの受け口を用意する

スケジューラーが呼ぶパスに、GET を受け付ける API を作ります。hanamii 以外からの呼び出しを弾くため、HANAMII_SCHEDULER_SECRET と Authorization ヘッダーの照合を必ず入れてください。

HANAMII_SCHEDULER_SECRET は hanamii が自動で設定します。値を自分で見たり、環境変数の画面で登録したりする必要はありません（hanamii の予約名のため、自分で同じ名前の環境変数を登録することはできません）。

Next.js（App Router）の例

app/api/cron/route.ts

export async function GET(request: Request) {
  const secret = process.env.HANAMII_SCHEDULER_SECRET
  const authorization = request.headers.get('authorization')

  if (!secret || authorization !== `Bearer ${secret}`) {
    return new Response('Unauthorized', { status: 401 })
  }

  // ここに定期実行したい処理を書きます

  return Response.json({ ok: true })
}

Express（Node.js）の例

app.get('/api/cron', async (req, res) => {
  const secret = process.env.HANAMII_SCHEDULER_SECRET
  if (!secret || req.headers.authorization !== `Bearer ${secret}`) {
    return res.status(401).send('Unauthorized')
  }

  // ここに定期実行したい処理を書きます

  res.json({ ok: true })
})

Python（Flask）の例

import os
from flask import request, abort, jsonify

@app.get("/api/cron")
def cron():
    secret = os.environ.get("HANAMII_SCHEDULER_SECRET")
    if not secret or request.headers.get("Authorization") != f"Bearer {secret}":
        abort(401)

    # ここに定期実行したい処理を書きます

    return jsonify(ok=True)

受け口を書くときのコツ

• 成功したら 2xx を返してください。 実行履歴では、2xx 以外の応答は「失敗（HTTP 500）」のように記録されます
• 5 分以内に終わる処理にしてください。 時間のかかる処理は、1 回で扱う件数を絞って回数を増やす、または処理をキューに積んですぐ応答を返す、といった分け方が安全です
• 同じ処理が 2 回走っても問題ない作りにしてください。 「結果不明」と記録された回は、アプリ側で処理が完了していることがあります（後述）。重複して実行されても壊れない、いわゆる冪等（べきとう）な処理にしておくと安心です
• パスは / から始まる相対パスで、英数字と . _ - が使えます。/health や /ready など hanamii が内部で使うパスは指定できません

2. 実行する時刻を決める

設定方法は 2 つあります。画面から設定する 方法と、プロジェクトのルートに hanamii.json を置く 方法です。どちらか一方を使ってください。同じパスを両方で設定した場合はファイルの内容が優先され、画面からはそのパスを変更できなくなります。

方法 A: 画面から設定する

1. プロジェクト詳細の スケジューラー タブを開く
2. 利用設定 で 利用する を選ぶ。スケジュールがまだないときは、追加フォームが開きます
3. パス に、手順 1 で用意した受け口のパス（例: /api/cron）を入力する
4. 実行間隔 のタブで時刻を決める（下表）
5. 時刻の基準 を選ぶ。初期値は 日本時間（JST） です
6. 保存して有効化 を押す

保存したスケジュールは一覧に表示され、編集 と 削除 ができます。追加した時点で有効になり、一覧に「次回: 2026/10/14 10:00 JST」のように次の実行時刻が出ます。

方法 B: hanamii.json で設定する

プロジェクトのルート（package.json などと同じ階層）に hanamii.json を置きます。GitHub 連携でルートディレクトリを指定している場合は、そのディレクトリの直下に置いてください。

{
  "schedules": [
    {
      "path": "/api/cron",
      "schedule": "0 10 * * *"
    },
    {
      "path": "/api/cleanup",
      "schedule": "30 3 * * 1",
      "timezone": "UTC"
    }
  ]
}

• 書けるのは schedules の中の path / schedule / timezone だけです。それ以外の項目があるとデプロイ時にエラーになります
• 同じ path を 2 つ書くことはできません
• ファイルサイズの上限は 4,096 バイトです。件数の上限はありません
• 内容に誤りがあると、ZIP のチェック時またはデプロイ時に「hanamii.json の schedules[0].schedule を確認してください」のように、どの項目が問題かが表示されます。直してアップロードし直してください

hanamii.json を置いたときの動きは次のとおりです。

• デプロイが成功するたびに、ファイルの内容がそのまま反映されます
• ファイルで設定したスケジュールは、画面からは編集・停止・削除できません。一覧には「hanamii.json で設定」と表示されます
• 変更したいときは、ファイルを直して再デプロイします。止めたいときは、ファイルからその項目を消して（またはファイルごと消して）再デプロイします
• 同じパスを画面でも設定していた場合は、ファイルの内容が優先されます。違うパスの画面設定はそのまま残ります
• 認証用の値は hanamii が自動で用意するため、鍵の手動設定は不要です

cron 式の書き方

「個別」タブと hanamii.json では、cron 式を直接書きます。左から 分・時・日・月・曜日 の 5 項目を半角スペースで区切ります。

┌ 分（0〜59）
│ ┌ 時（0〜23）
│ │ ┌ 日（1〜31）
│ │ │ ┌ 月（1〜12）
│ │ │ │ ┌ 曜日（0〜7、0 と 7 が日曜）
│ │ │ │ │
0 10 * * *

• 使えるのは数字と * , - / だけです。@daily や MON のような文字の指定はできません
• 日と曜日は同時に指定できません（どちらか一方は * にします）
• 時刻の基準（JST か UTC）はスケジュールごとに決まります。UTC のスケジュールは、一覧に日本時間も併記されます

3. 有効になるのを待つ

画面から設定した場合は保存した時点で、hanamii.json の場合はデプロイが成功した時点で、スケジュールが登録されます。

はじめて有効化したときは、hanamii が「今動いているアプリへ安全に送れるか」を確認します。その間は スケジューラーを準備しています と表示されます。しばらくして一覧のラベルが 有効 になれば準備完了です。

一覧のラベルの意味は次のとおりです。

実行履歴を見る

スケジューラータブの下部に、過去 30 日間 の実行履歴が新しい順に並びます。1 行に「予定時刻・パス・結果・HTTP ステータス・処理時間」が出ます。

ヒント: 履歴には hanamii から見た結果だけが残ります。処理の中身（何件処理したか、どこでエラーになったか）は、アプリ側で ランタイムログ に出力しておくと追いやすくなります。

利用時間を確認する

スケジューラータブの 今月の利用時間（このワークスペース） に、ワークスペース全体の実行時間（リクエストを送ってから応答が返るまでの合計）が表示されます。

• 目安として 通知基準 2,000 分/月 が設けられています。基準を超えても実行は止まりません
• 「推定時間」は、まだ結果が確定していない回の見込みで、実測とは別に表示されます
• 月の区切りは日本時間です

止める・消す

• 一時的に止める: 利用設定で 利用しない を選びます。画面から設定したスケジュールがすべて 無効 になり、設定は残ります。再開するときは 利用する を選びます
• 1 つだけ消す: 一覧の 削除 を押し、確認画面で 削除 を押します
• hanamii.json で設定したもの: 画面からは止められません。ファイルから項目を消して再デプロイしてください。ファイル由来のスケジュールが 1 つでも有効なあいだは、画面の 利用しない は選べません

気をつけること

過去のバージョンに切り替えたとき

デプロイ タブのバージョン情報から過去のバージョンへ切り替えると、スケジューラーは安全のため 一時停止 します（切り替え完了時にその旨が表示されます）。再開するには、現在のスケジューラー設定を含めてもう一度デプロイし、一覧のラベルが 有効 に戻ることを確認してください。

アクセス制御（IP 制限）と併用するとき

アクセス制御で接続元 IP を制限しているプロジェクトでは、hanamii からのスケジューラー通信を通すため、hanamii が管理する許可ルールを 1 つ自動で追加します。許可 IP の枠は全体で 10 件のため、自分で登録できる IP は 9 件まで になります。すでに 10 件登録している場合は、スケジュールを有効化できません。アクセス制御タブに「Hanamii管理のスケジューラー通信がAppRunの10枠中1枠を使用中です」と表示されます。カスタムドメインを使っている場合は、この制限はありません。

ローカルで試したいとき

ローカル開発環境には HANAMII_SCHEDULER_SECRET がありません。.env.local などに任意の値を入れ、次のように手で呼べば動作確認できます。

curl -H "Authorization: Bearer <ローカル用に決めた値>" http://localhost:3000/api/cron

そのほか

• 無料プランでも利用できます。無料プランで 30 日間アクセスがないプロジェクトは停止されるため、スケジューラーだけが動いているプロジェクトでは、停止の判定に注意してください
• 同じパス・同じ時刻・同じ時刻の基準の組み合わせは、1 つのプロジェクトに 1 件だけ登録できます
• スケジュールの件数に上限はありません
• 実行の予定時刻ちょうどに届くとは限りません。混み合っているときは数分ずれることがあります。秒単位の正確さが必要な処理には向いていません

よくある質問

時刻になっても実行されません

次の順で確認してください。

1. 一覧のラベルが 有効 になっているか。実行停止中 なら画面上部の案内に従います
2. 実行履歴に行があるか。行があって 失敗 なら、アプリ側の問題です（HTTP ステータスとランタイムログを確認）
3. 行がまったくないなら、スケジュールの時刻の基準（JST / UTC）と cron 式を見直してください。「個別」タブで保存した式は、一覧の表示で確認できます

POST で受けたいです

スケジューラーが送るのは GET だけです。受け口は GET で用意してください。

秘密の値（HANAMII_SCHEDULER_SECRET）を確認したいです

画面には表示されません。アプリの中で process.env.HANAMII_SCHEDULER_SECRET のように読むだけで照合できるため、値を知る必要はありません。環境変数の画面に同じ名前で登録することもできません。

1 つのプロジェクトで複数の処理を動かしたいです

パスを分けてスケジュールを複数登録してください（例: /api/cron/daily と /api/cron/hourly）。hanamii.json なら schedules に複数書けます。

失敗した回はやり直されますか

失敗した回を hanamii がやり直すことは期待しないでください。次の予定時刻に通常どおり実行されます。取りこぼしが困る処理は、アプリ側で「前回どこまで処理したか」を記録して、次回にまとめて処理する作りにしてください。

関連ガイド

• 環境変数の設定と反映
• データベースを使う（ベータ版）
• トラブルシューティング