← Cloudflare Queues / queues / tutorials

Обработка ограничений частоты запросов внешних API

В этом руководстве описано, как использовать Queues для обработки ограничений частоты запросов внешних API на примере приложения, которое отправляет уведомления по электронной почте с помощью Resend ↗. Однако этот подход можно использовать для обработки ограничений скорости запросов любого внешнего API.

Resend является сервисом, который позволяет отправлять электронные письма из вашего приложения через API. У Resend по умолчанию установлен лимит скорости ↗ в размере двух запросов в секунду. Вы будете использовать Queues, чтобы соблюдать это ограничение скорости Resend.

1. Зарегистрируйтесь для получения Аккаунт Cloudflare ↗.
2. Установка Node.js ↗.

4. Зарегистрируйтесь для Resend ↗ и создать ключ API, следуя руководству на Документация Resend ↗.

5. Кроме того, вам потребуется доступ к Cloudflare Queues.

Стоимость Queues уже включена в ежемесячную стоимость подписки на тарифный план Workers Paid, а плата взимается на основе операций с вашими очередями. Ограниченная версия Queues также доступна на тарифе Workers Free. См. Цены для дополнительных сведений.

Прежде чем использовать Queues, необходимо включить её через панель управления Cloudflare ↗. Для использования Queues необходим тарифный план Workers Paid.

Чтобы включить Queues:

1. На панели управления Cloudflare перейдите к разделу Queues страницу.

   Перейдите в Queues ↗

2. Выберите Включить Queues.

Для начала создайте приложение Worker с помощью create-cloudflare CLI ↗. Откройте окно терминала и выполните следующую команду:

npm create cloudflare@latest -- resend-rate-limit-queue

Для настройки выберите следующие параметры:

• Для С чего вы хотите начать?, выберите Hello World example.
• Для Какой шаблон вы хотите использовать?, выберите Worker only.
• Для Какой язык вы хотите использовать?, выберите TypeScript.
• Для Хотите использовать git для контроля версий?, выберите Yes.
• Для Хотите развернуть приложение?, выберите No (мы внесём некоторые изменения перед развёртыванием).

Затем перейдите в только что созданный каталог:

cd resend-rate-limit-queue

Вам нужно создать очередь и привязку к вашему Worker. Выполните следующую команду, чтобы создать очередь с именем rate-limit-queue:

npx wrangler queues create rate-limit-queue

Creating queue rate-limit-queue.
Created queue rate-limit-queue.

В файле Wrangler добавьте следующее:

{
	"queues": {
		"producers": [
			{
				"binding": "EMAIL_QUEUE",
				"queue": "rate-limit-queue"
			}
		],
		"consumers": [
			{
				"queue": "rate-limit-queue",
				"max_batch_size": 2,
				"max_batch_timeout": 10,
				"max_retries": 3
			}
		]
	}
}

[[queues.producers]]
binding = "EMAIL_QUEUE"
queue = "rate-limit-queue"

[[queues.consumers]]
queue = "rate-limit-queue"
max_batch_size = 2
max_batch_timeout = 10
max_retries = 3

Важно указать max_batch_size для очереди потребителя, равное двум, важно, поскольку API Resend по умолчанию ограничивает скорость двумя запросами в секунду. Такой размер пакета позволяет очереди обрабатывать сообщения пакетами по два. Если размер пакета меньше двух, очередь будет ждать 10 секунд, чтобы собрать следующее сообщение. Если больше сообщений нет, очередь обработает сообщение, находящееся в пакете. Дополнительную информацию см. на документация по пакетной обработке, повторным попыткам и задержкам

Итоговый файл Wrangler должен выглядеть примерно так, как в примере ниже.

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "resend-rate-limit-queue",
	"main": "src/index.ts",
	// Set this to today's date
	"compatibility_date": "2026-08-28",
	"compatibility_flags": [
		"nodejs_compat"
	],
	"queues": {
		"producers": [
			{
				"binding": "EMAIL_QUEUE",
				"queue": "rate-limit-queue"
			}
		],
		"consumers": [
			{
				"queue": "rate-limit-queue",
				"max_batch_size": 2,
				"max_batch_timeout": 10,
				"max_retries": 3
			}
		]
	}
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "resend-rate-limit-queue"
main = "src/index.ts"
# Set this to today's date
compatibility_date = "2026-08-28"
compatibility_flags = [ "nodejs_compat" ]

[[queues.producers]]
binding = "EMAIL_QUEUE"
queue = "rate-limit-queue"

[[queues.consumers]]
queue = "rate-limit-queue"
max_batch_size = 2
max_batch_timeout = 10
max_retries = 3

Добавление привязок в интерфейс окружения, в worker-configuration.d.ts, чтобы TypeScript корректно типизировал привязки. Тип очереди задаётся как Queue<Message>, где Message определяется на следующем шаге.

interface Env {
	EMAIL_QUEUE: Queue<Message>;
}

Приложение отправляет сообщение в очередь, когда Worker получает запрос. Для простоты в качестве сообщения в очередь будет отправляться адрес электронной почты. Новое сообщение будет отправлено в очередь с задержкой в одну секунду.

export default {
	async fetch(req, env, ctx): Promise<Response> {
		try {
			await env.EMAIL_QUEUE.send(
				{ email: await req.text() },
				{ delaySeconds: 1 },
			);
			return new Response("Success!");
		} catch (e) {
			return new Response("Error!", { status: 500 });
		}
	},
} satisfies ExportedHandler<Env>;

Это будет принимать запросы на любой подпуть и передавать тело запроса. Предполагается, что тело запроса содержит только адрес электронной почты. В продакшене следует проверять, что запрос был POST . Кроме того, не следует отправлять такие конфиденциальные данные (адрес электронной почты) напрямую в очередь. Вместо этого можно отправить в очередь сообщение с уникальным идентификатором пользователя. Затем очередь потребителя сможет использовать этот идентификатор, чтобы найти адрес электронной почты в базе данных и отправить письмо.

После отправки сообщения в очередь его обрабатывает Worker-потребитель. Он обрабатывает сообщение и отправляет письмо.

Поскольку вы ещё не настроили Resend, сообщение будет выводиться в консоль. После настройки Resend вы сможете использовать его для отправки письма.

Добавьте queue() обработчик, как показано ниже:

interface Message {
	email: string;
}

export default {
	async fetch(req, env, ctx): Promise<Response> {
		try {
			await env.EMAIL_QUEUE.send(
				{ email: await req.text() },
				{ delaySeconds: 1 },
			);
			return new Response("Success!");
		} catch (e) {
			return new Response("Error!", { status: 500 });
		}
	},
	async queue(batch, env, ctx): Promise<void> {
		for (const message of batch.messages) {
			try {
				console.log(message.body.email);
				// After configuring Resend, you can send email
				message.ack();
			} catch (e) {
				console.error(e);
				message.retry({ delaySeconds: 5 });
			}
		}
	},
} satisfies ExportedHandler<Env, Message>;

Приведённый выше queue() обработчик выведет адрес электронной почты в консоль и отправит письмо. Он также повторит обработку сообщения, если отправка письма завершится ошибкой. delaySeconds установлен равным пяти секундам, чтобы не отправлять письмо слишком быстро.

Чтобы протестировать приложение, выполните следующую команду:

npm run dev

Используйте следующую команду cURL, чтобы отправить запрос к приложению:

curl -X POST -d "[email protected]" http://localhost:8787/

[wrangler:inf] POST / 200 OK (2ms)
QueueMessage {
  attempts: 1,
  body: { email: '[email protected]' },
  timestamp: 2024-09-12T13:48:07.236Z,
  id: '72a25ff18dd441f5acb6086b9ce87c8c'
}

Чтобы вызвать Resend API, необходимо настроить ключ Resend API. Создайте .dev.vars файл в корне проекта и добавьте в него следующее:

RESEND_API_KEY='your-resend-api-key'

Замените your-resend-api-key на ваш фактический ключ API Resend.

Далее обновите Env интерфейс в worker-configuration.d.ts чтобы включить RESEND_API_KEY переменную.

interface Env {
	EMAIL_QUEUE: Queue<Message>;
	RESEND_API_KEY: string;
}

Наконец, установите resend пакет ↗ с помощью следующей команды:

npm i resend

Теперь вы можете использовать RESEND_API_KEY переменную в коде.

В вашем src/index.ts файле импортируйте пакет Resend и обновите queue() обработчик для отправки письма.

import { Resend } from "resend";

interface Message {
	email: string;
}

export default {
	async fetch(req, env, ctx): Promise<Response> {
		try {
			await env.EMAIL_QUEUE.send(
				{ email: await req.text() },
				{ delaySeconds: 1 },
			);
			return new Response("Success!");
		} catch (e) {
			return new Response("Error!", { status: 500 });
		}
	},
	async queue(batch, env, ctx): Promise<void> {
		// Initialize Resend
		const resend = new Resend(env.RESEND_API_KEY);
		for (const message of batch.messages) {
			try {
				console.log(message.body.email);
				// send email
				const sendEmail = await resend.emails.send({
					from: "[email protected]",
					to: [message.body.email],
					subject: "Hello World",
					html: "<strong>Sending an email from Worker!</strong>",
				});

				// check if the email failed
				if (sendEmail.error) {
					console.error(sendEmail.error);
					message.retry({ delaySeconds: 5 });
				} else {
					// if success, ack the message
					message.ack();
				}
				message.ack();
			} catch (e) {
				console.error(e);
				message.retry({ delaySeconds: 5 });
			}
		}
	},
} satisfies ExportedHandler<Env, Message>;

queue() обработчик теперь отправит письмо через Resend API. Он также проверяет, не завершилась ли отправка письма ошибкой, и в этом случае повторит обработку сообщения.

Итоговый скрипт приведён ниже:

import { Resend } from "resend";

interface Message {
	email: string;
}

export default {
	async fetch(req, env, ctx): Promise<Response> {
		try {
			await env.EMAIL_QUEUE.send(
				{ email: await req.text() },
				{ delaySeconds: 1 },
			);
			return new Response("Success!");
		} catch (e) {
			return new Response("Error!", { status: 500 });
		}
	},
	async queue(batch, env, ctx): Promise<void> {
		// Initialize Resend
		const resend = new Resend(env.RESEND_API_KEY);
		for (const message of batch.messages) {
			try {
				// send email
				const sendEmail = await resend.emails.send({
					from: "[email protected]",
					to: [message.body.email],
					subject: "Hello World",
					html: "<strong>Sending an email from Worker!</strong>",
				});

				// check if the email failed
				if (sendEmail.error) {
					console.error(sendEmail.error);
					message.retry({ delaySeconds: 5 });
				} else {
					// if success, ack the message
					message.ack();
				}
			} catch (e) {
				console.error(e);
				message.retry({ delaySeconds: 5 });
			}
		}
	},
} satisfies ExportedHandler<Env, Message>;

Чтобы протестировать приложение, запустите сервер разработки с помощью следующей команды:

npm run dev

Используйте следующую команду cURL, чтобы отправить запрос к приложению:

curl -X POST -d "[email protected]" http://localhost:8787/

В панели управления Resend вы должны увидеть, что письмо было отправлено на указанный адрес электронной почты.

Чтобы развернуть Worker, выполните следующую команду:

npx wrangler deploy

Наконец, добавьте API-ключ Resend с помощью следующей команды:

npx wrangler secret put RESEND_API_KEY

Введите значение вашего ключа API. Ваш ключ API будет добавлен в проект. Теперь вы можете использовать RESEND_API_KEY переменную в коде.

Вы успешно создали Worker, который может отправлять электронные письма через Resend API с соблюдением ограничений по частоте запросов.

Чтобы протестировать Worker, можно использовать следующий запрос cURL. Замените <YOUR_WORKER_URL> на URL-адрес развёрнутого Worker.

curl -X POST -d "[email protected]" <YOUR_WORKER_URL>

См. репозиторий GitHub ↗ полный код для этого руководства. Если вы используете Hono ↗, вы можете обратиться к Пример с Hono ↗.

• Как работает Queues
• Группировка сообщений и повторные попытки в Queues
• Resend ↗