Workflows の createBatch() は配列渡しが非推奨に、重複 ID は errors で返る

Cloudflare Workflows の createBatch() に、配列の代わりに options オブジェクトを渡す形が加わった（Cloudflare の changelog、2026年10月8日付）。配列を渡す書き方は非推奨になったが、changelog は既存の配列形式のコードは引き続き動くとしている。非推奨化そのものが配列形式の即時停止を意味するわけではない。

書き換える理由は戻り値にある。新しい形は作成できたインスタンスを created に、作成できなかった入力を errors に分けて返す。すでに存在する ID と、同じバッチの中で重複した ID は、黙ってスキップされずに errors へ入る。1回の呼び出しで作れるのは最大100件。ローカル開発でこの形を使い、wrangler types で型を得るには Wrangler 4.148.0 以上が要る。

count と instances、どちらで包むか

options オブジェクトには二つの書き方がある。選ぶ基準は「ID を自分で決めるかどうか」だ。

同じ params のインスタンスを数だけ作る

全インスタンスが同じ options でよく、ID にこだわらないなら count を渡す。ID は生成される。

const result = await env.MY_WORKFLOW.createBatch({
  count: 10,
  params: { report: "daily" },
});

定期レポートのように、同じ入力で並列に走らせたいだけのジョブはこちらで足りる。配列を Array.from などで組み立てていたコードなら、その組み立て自体が要らなくなる。

ID と params を 1件ずつ指定する

注文 ID のように、業務側のキーをインスタンス ID にしているなら instances を使う。

const { created, errors } = await env.MY_WORKFLOW.createBatch({
  instances: [
    { id: "order-1", params: { orderId: 1 } },
    { id: "order-2", params: { orderId: 2 } },
  ],
});

for (const error of errors) {
  console.log(error.index, error.id, error.code, error.message);
}

公式Workers APIの「Migrate from the array form」は、旧形式に渡していた配列を instances に移し、戻り値を created から読む方法を示している。各要素は create() と同じoptionsを受け取り、id と params は任意だ。上の例は両方を明示している。

errors に入るものと、その読み方

errors の各要素には入力位置の index、code、message があり、入力でIDを指定した場合は id も入る。index は入力の中での位置を指すので、どの入力が作られなかったかを入力側の配列と照合できる。instances 形式なら id でも照合できる。

ここで注意したいのは、既存 ID も errors として返る点だ。ID の衝突を「すでにあるなら何もしない」という冪等性の仕組みとして使い、同じバッチを再実行してきたコードは、新しい形に移すと既存IDに対する errors が返るため、これをすべて失敗として警報に流すと誤検知になる。

Workers APIの createBatch リファレンスは、既存IDとの衝突とバッチ内の重複を異なるエラーコードで区別している。再実行時に想定した既存ID衝突だけを別扱いにし、重複入力や想定外のエラーを無視しないよう分岐を決めたい。errors があることだけでバッチ全体の失敗とも成功とも判断できず、created と合わせて未作成の入力を追う必要がある。

バッチ内の重複IDは、同じIDを持つ先の入力だけが作成される。paramsが異なる入力を機械的に削る前に、どちらを実行すべきかを入力側で確認したい。

不正なIDや保持期間など無効なoptionsがある場合は、インスタンスを作成する前に呼び出し自体が例外になる。戻り値の errors だけを調べる処理ではこの失敗を拾えないため、呼び出しの例外処理も残す。

移行の順番

1. Wrangler を 4.148.0 以上に上げ、wrangler types で型を再生成する。古い Wrangler のままだとローカル開発で新しい形が使えない。
2. ID が不要な呼び出しは count + params に、ID を指定する呼び出しは instances に書き換える。
3. 戻り値を { created, errors } で受け、想定内の既存ID衝突、重複入力、その他のエラーの扱いを分ける。呼び出し自体の例外も処理する。
4. 1回あたりの件数が100件を超えうる呼び出しは、分割して送る。

旧配列形式の戻り値はインスタンスの配列で、既存IDや重複IDはスキップされて戻り値にも入らない。移行後は created を成功分として読み、未作成分の扱いを追加する。配列を包む変更だけで、戻り値まで以前と同じと考えないようにしたい。

Workflows には、インスタンスを一括で削除する操作も加わっている（Workflows のインスタンス一括削除）。作成と削除の両方をバッチで扱うなら、件数の上限と結果の扱いを両側で揃えておくと運用が読みやすい。