blink-queue

MCP ツール

blink_queue_enqueue · blink_queue_schedule · blink_queue_list · blink_queue_stats · blink_queue_cancel · blink_queue_get · blink_queue_dlq_retry · blink_queue_create_queue

はじめに

# Check backend is deployed (required for queue delivery)
blink backend status

# Enqueue a task
blink queue enqueue send-welcome-email --payload '{"to":"[email protected]"}'

# Create a cron schedule
blink queue schedule create daily-digest "0 9 * * *" --payload '{"reportType":"daily"}'

# List tasks
blink queue list --status pending

# View stats
blink queue stats

最小 SDK バージョン：@blinkdotnew/sdk >= 2.9.0

重要なルール

1. バックエンドが必要です — まずバックエンドをデプロイしてください。バックエンドがないとキューの配信に失敗します
2. 先にハンドラーを記述してください — キューに登録する前に、backend/index.ts に POST /api/queue を追加してください
3. スケジュール名 = taskName — ハンドラーはスケジュールの name を taskName として受け取ります
4. ハンドラーの変更後にデプロイしてください — blink backend deploy
5. 2xx を返してください — 2xx 以外を返すと再試行され、その後デッドレターキューに移動します

ステップ 1 — backend/index.ts にハンドラーを追加する

import { createClient } from '@blinkdotnew/sdk'

app.post('/api/queue', async (c) => {
  const blink = createClient({ projectId: c.env.BLINK_PROJECT_ID, secretKey: c.env.BLINK_SECRET_KEY })
  // Your queue URL is public. Verify every delivery came from Blink Queue before
  // acting on it — one check covers both enqueued tasks and cron ticks. Read the
  // RAW body: the signature is over the exact bytes, so parse only after verifying.
  const body = await c.req.text()
  const ok = await blink.queue.verify({
    signature: c.req.header('upstash-signature') ?? '',
    body,
    signingKey: c.env.BLINK_QUEUE_SIGNING_KEY,
    nextSigningKey: c.env.BLINK_QUEUE_SIGNING_KEY_NEXT,  // platform-injected; used during key rotation
  })
  if (!ok) return c.json({ error: 'invalid signature' }, 401)

  const { taskName, payload } = JSON.parse(body)

  switch (taskName) {
    case 'send-welcome-email':
      await sendEmail(payload.to, payload.displayName)
      return c.json({ ok: true })

    case 'daily-digest':
      await generateDigest(payload.reportType)
      return c.json({ ok: true })

    default:
      return c.json({ error: `Unknown task: ${taskName}` }, 400)
  }
})

BLINK_QUEUE_SIGNING_KEY はバックエンドの環境変数に自動で注入されるため、設定する必要はありません。verify() は true または false を返し、キーがない場合にのみ例外をスローします。

ソースごとのペイロード：

ソース	配信される本文
blink.queue.enqueue(taskName, payload)	{ taskName, taskId, payload }
blink.queue.schedule(name, cron, payload)	{ taskName: name, payload }（taskId は含まれません）

ステップ 2 — デプロイしてから、キューに登録する

blink backend deploy
blink queue enqueue send-welcome-email --payload '{"to":"[email protected]"}' --queue emails --delay 10s

SDK メソッド

// Enqueue
await blink.queue.enqueue('send-welcome-email', { to: '[email protected]' })
await blink.queue.enqueue('send-welcome-email', { to: '[email protected]' }, {
  queue: 'emails', delay: '5m', retries: 3,
})

// Schedule — name IS the taskName
await blink.queue.schedule('daily-digest', '0 9 * * *', { type: 'daily' })
await blink.queue.schedule('daily-digest', '0 9 * * *', { type: 'daily' }, {
  timezone: 'America/New_York',
})

// Manage schedules
await blink.queue.pauseSchedule('daily-digest')
await blink.queue.resumeSchedule('daily-digest')
await blink.queue.deleteSchedule('daily-digest')

// Named queues (create once, idempotent)
await blink.queue.createQueue('emails', { parallelism: 10 })

// Inspect & manage
const tasks = await blink.queue.list({ status: 'pending', queue: 'emails' })
await blink.queue.cancel(taskId)
const dead = await blink.queue.listDead()
await blink.queue.retryDead(taskId)
const stats = await blink.queue.stats()

Cron パターン

Cron	実行タイミング
0 9 * * *	毎日午前 9 時
0 * * * *	毎時
*/15 * * * *	15 分ごと
0 9 * * 1	毎週月曜日の午前 9 時

よくあるエラー

エラー	原因	解決方法
タスクが配信されない	バックエンドがデプロイされていない	blink backend deploy
Unknown task: X	ハンドラーに該当する case がない	対応する case を追加する
タスクが再試行される	ハンドラーが 2xx 以外を返している	c.json({ ok: true }) を返す
cancel が 409 を返す	タスクが保留中ではない	'pending' のタスクのみキャンセルできます

課金

1 クレジット = 1,000 タスク（1 タスクあたり 0.001 クレジット）です。再試行と読み取りは無料です。Pro+ 限定です。