ジョブの投入

投入方法

performerと同じWorkerからは、defineTsumugiの戻り値を使ってジョブを投入します。
createClientは、performerを持たないWorkerからジョブを投入するためのクライアントです。

必要なbindingが不足していると、tsumugi.enqueue, tsumugi.enqueueMany, tsumugi.jobs(env)は例外を発生させます。
例外には、不足しているbindingの一覧が含まれます。
JOB_SHARD, TSUMUGI_DB, TSUMUGI_QUEUEは、常に必須です。
flowsを使う場合はRUNを、schedulesを使う場合はSCHEDULERを追加します。
remote()のperformerには、対応するService Bindingを用意します。

enqueue

const id = await tsumugi.enqueue(env, {
  binding: 'MAIL',
  payload: { to: 'a@example.com', subject: 'hi' },
});

戻り値はジョブIDです。
payloadの型は、指定したbindingの値から導出されます。
必須キーを指定しない場合、コンパイルエラーが発生します。

enqueueMany

tsumugi.enqueueManyは、複数のジョブを一括で投入します。

const ids = await tsumugi.enqueueMany(env, [
  { binding: 'MAIL', payload: { to: 'a@example.com', subject: 'hi' } },
  { binding: 'MAIL', payload: { to: 'b@example.com', subject: 'hi' } },
]);

件数が増えても、所要時間はほとんど変わりません。
戻り値の配列では、i番目の要素が入力のi番目のジョブに対応するIDです。

jobs

tsumugi.jobs(env)の戻り値は、envを事前に指定した型付きジョブ投入用オブジェクトです。

const jobs = tsumugi.jobs(env);

const id = await jobs.enqueue('MAIL', { to: 'a@example.com', subject: 'hi' });
await jobs.enqueue('CHARGE', { customerId: 'c1', amountJpy: 1200 }, { concurrencyKey: 'customer:c1' });

投入される内容は、tsumugi.enqueueと同一です。
違いは引数の形式に限られます。
キーを必須にしたperformerでは、optionsを省略した場合と、キーを指定しなかった場合に、コンパイルエラーが発生します。

オプション

shard数が2以上のbindingでは、partitionKeyを省略すると例外が発生します。
partitionKeyで投入先のshardを選択するのは、bindingsのshardsを適用する投入方法に限られます。
詳細は投入方法を参照してください。

予約実行

// 1時間後
await tsumugi.enqueue(env, { binding: 'MAIL', payload, delayMs: 60 * 60 * 1000 });

// 指定時刻
await tsumugi.enqueue(env, { binding: 'MAIL', payload, runAt: Date.parse('2026-08-01T09:00:00+09:00') });

有効期限

expiresInMsまたはexpiresAtを指定すると、期限を過ぎたジョブは実行されずにCANCELLEDへ遷移します。
一時停止や実行の遅れの後でも、期限切れの通知がまとめて実行されることはありません。

// 5分以内に開始できなければ実行しない
await tsumugi.enqueue(env, { binding: 'NOTIFY', payload, expiresInMs: 5 * 60 * 1000 });

実行中のジョブは、期限を過ぎても中断されません。
次のリトライ予定時刻が期限より後の場合、ジョブは失敗時にCANCELLEDへ遷移します。
FAILEDおよびSTALLEDのジョブを手動でリトライする際も、期限が適用されます。

重複排除

uniqueKeyを指定すると、同じキーのジョブがすでに存在するときは新しいジョブを作成しません。
このときの戻り値は、既存のジョブのIDです。

const id = await tsumugi.enqueue(env, {
  binding: 'SYNC',
  payload: { sku: 'X-1' },
  uniqueKey: 'sku:X-1',
});

重複した投入はエラーになりません。
例外も発生しません。
uniqueForMsの期間が経過すると、重複の判定は解除されます。
同じキーで再度投入すれば、新しいジョブが作成されます。

直列化

concurrencyKeyが同じジョブは、perKeyConcurrencyの件数まで同時に実行されます。
既定値は1なので、同じキーのジョブは1件ずつ順に実行されます。

await tsumugi.enqueue(env, {
  binding: 'CHARGE',
  payload: { customerId: 'c1', amountJpy: 1200 },
  concurrencyKey: 'customer:c1',
});

shard数が2以上のbindingでは、この直列化はpartitionKeyが同じshardの中に限られます。
詳細はshardを参照してください。

トレース情報

投入時にtraceparentを指定すると、performerのctx.traceparentに同じ値が渡されます。
リトライ時も同じ値が渡され、ダッシュボードはジョブの詳細にこの値を表示します。
enqueueManyは、ジョブごとのtraceparentを受け付けます。

await tsumugi.enqueue(env, {
  binding: 'MAIL',
  payload: { to: 'a@example.com', subject: 'hi' },
  traceparent: '00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01',
});

形式はW3C Trace Contextのversion 00(55文字)です。
各項目は小文字の16進数で記述します。
形式が正しくない値を指定すると、投入時に検証エラーが発生します。
trace-idまたはparent-idのすべての桁が0の値を指定した場合も、検証エラーが発生します。

ジョブID

<binding>#<shard>:<localId>

例: MAIL#0:xxxxxxxxxxxxxxxxxxxxxxxx

shard数を変更しても、既存のジョブIDは同一のジョブを識別します。
ただし、変更の前後で、partitionKeyの値が同じジョブの投入先shardは変わる可能性があります。
concurrencyKeyとuniqueKeyによる制御はshardごとに実行されるので、投入先のshardが異なるジョブの間には適用されません。
shard数を減らすと、範囲外になったshardには実行時の設定変更が適用されません。
shardの詳細は、shardを参照してください。

別Workerからの投入

performerを持たないWorkerからの投入については、別Workerからの投入を参照してください。