← Cloudflare Workflows / workflows / build

Запуск Workflows

Запускать Workflows можно как программно, так и через Workflows API, в том числе:

1. С Workers через HTTP запросы в fetch обработчика или привязки из queue или scheduled обработчик
2. Через регулярные интервалы, задав schedules для привязки Workflow в конфигурации Wrangler
3. С помощью Workflows REST API
4. Через wrangler CLI в терминале

Взаимодействовать с Workflows программно можно из любого скрипта Worker, создав привязку к Workflow. Worker может привязываться сразу к нескольким Workflows, в том числе к тем, что определены в других проектах (скриптах) Workers в вашем аккаунте.

Запустить Workflow можно:

• Напрямую по HTTP через fetch обработчик
• Из Потребитель очереди внутри queue обработчик
• По регулярному расписанию, задав schedules для привязки Workflow в wrangler.jsonc
• Из Cron Trigger внутри scheduled обработчик
• В пределах Durable Object

Чтобы привязать Workflow к коду вашего Worker, необходимо определить привязка к конкретному Workflow. Например, чтобы привязаться к Workflow, определённому в руководство по началу работы, вам нужно настроить конфигурационный файл Wrangler со следующим:

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "workflows-tutorial",
	"main": "src/index.ts",
	// Set this to today's date
	"compatibility_date": "2026-08-28",
	"workflows": [
		{
			// The name of the Workflow
			"name": "workflows-tutorial",
			// The binding name, which must be a valid JavaScript variable name.  This will
			// be how you call (run) your Workflow from your other Workers handlers or
			// scripts.
			"binding": "MY_WORKFLOW",
			// Must match the class defined in your code that extends the Workflow class
			"class_name": "MyWorkflow"
		}
	]
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "workflows-tutorial"
main = "src/index.ts"
# Set this to today's date
compatibility_date = "2026-08-28"

[[workflows]]
name = "workflows-tutorial"
binding = "MY_WORKFLOW"
class_name = "MyWorkflow"

binding = "MY_WORKFLOW" строка определяет переменную JavaScript, через которую доступны методы нашего Workflow, включая create (который запускает новый экземпляр) или get (который возвращает статус существующего экземпляра).

Если вы хотите создавать экземпляры Workflow с определённой периодичностью, добавьте schedules массив (до 100 cron-выражений на аккаунт) в привязку Workflow в конфигурации Wrangler:

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "workflows-tutorial",
	"main": "src/index.ts",
	// Set this to today's date
	"compatibility_date": "2026-08-28",
	"workflows": [
		{
			"name": "workflows-tutorial",
			"binding": "MY_WORKFLOW",
			"class_name": "MyWorkflow",
			"schedules": ["0 * * * *"]
		}
	]
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "workflows-tutorial"
main = "src/index.ts"
# Set this to today's date
compatibility_date = "2026-08-28"

[[workflows]]
name = "workflows-tutorial"
binding = "MY_WORKFLOW"
class_name = "MyWorkflow"
schedules = [ "0 * * * *" ]

Каждое совпадающее cron-выражение автоматически создаёт новый экземпляр Workflow. Используйте это, если хотите запускать Workflow по расписанию без определения верхнеуровневого triggers.crons и отдельный scheduled обработчик.

Запланированные экземпляры включают соответствующее cron-выражение и время запланированного запуска в event.schedule:

export class MyWorkflow extends WorkflowEntrypoint<Env> {
	async run(event: WorkflowEvent<unknown>, step: WorkflowStep) {
		if (event.schedule) {
			console.log(event.schedule.cron);
			console.log(new Date(event.schedule.scheduledTime));
		}
	}
}

На Workers Paid, экземпляры Workflow, созданные schedules может выполняться до одного часа за одно срабатывание cron, не занимая слот параллелизма Workflow. Если экземпляр приостанавливается или переходит в спящий режим после этого периода, он высвобождает слот и попадает в обычную очередь параллелизма при возобновлении. Выполнение возобновляется, когда становится доступен слот параллелизма.

При настройке расписаний Workflow используйте последнюю версию Wrangler. Если локальная схема Wrangler не распознаёт schedules ещё, обновите Wrangler перед развёртыванием.

Следующий пример показывает, как можно управлять Workflows из Worker, в том числе:

• Получение статуса существующего экземпляра Workflow по его ID
• Создание (запуск) нового экземпляра Workflow
• Возврат статуса по указанному ID экземпляра

interface Env {
	MY_WORKFLOW: Workflow;
}

export default {
	async fetch(req: Request, env: Env) {
		// Get instanceId from query parameters
		const instanceId = new URL(req.url).searchParams.get("instanceId");

		// If an ?instanceId=<id> query parameter is provided, fetch the status
		// of an existing Workflow by its ID.
		if (instanceId) {
			let instance = await env.MY_WORKFLOW.get(instanceId);
			return Response.json({
				status: await instance.status(),
			});
		}

		// Else, create a new instance of our Workflow, passing in any (optional)
		// params and return the ID.
		const newId = crypto.randomUUID();
		let instance = await env.MY_WORKFLOW.create({ id: newId });
		return Response.json({
			id: instance.id,
			details: await instance.status(),
		});
	},
};

Вы можете проверить статус любого выполняющегося экземпляра Workflow, вызвав status для конкретного ID экземпляра. Это позволяет программно проверять, находится ли экземпляр в очереди (ожидает планирования), активно выполняется, приостановлен или завершился с ошибкой.

let instance = await env.MY_WORKFLOW.get("abc-123");
let status = await instance.status(); // Returns an InstanceStatus

Возможные значения status:

  status:
    | "queued" // means that instance is waiting to be started (see concurrency limits)
    | "running"
    | "paused"
    | "errored"
    | "terminated" // user terminated the instance while it was running
    | "complete"
    | "waiting" // instance is hibernating and waiting for sleep or event to finish
    | "waitingForPause" // instance is finishing the current work to pause
    | "unknown";
  error?: {
    name: string,
    message: string
  };
	output?: unknown;
	rollback:
		| {
				outcome: "complete" | "failed";
				error: {
					name: string,
					message: string,
				} | null,
		  }
		| null;

Если ваш Workflow регистрирует обработчики отката для step.do(), проверить rollback после завершения экземпляра, чтобы проверить, успешно ли завершились компенсирующие шаги. Пока откат активно выполняется, Workers API продолжает возвращать status: "running".

Вы можете явно приостановить экземпляр Workflow (и позже возобновить его), вызвав pause для конкретного ID экземпляра.

let instance = await env.MY_WORKFLOW.get("abc-123");
await instance.pause(); // Returns Promise<void>

Возобновить приостановленный экземпляр Workflow можно вызовом resume для конкретного ID экземпляра.

let instance = await env.MY_WORKFLOW.get("abc-123");
await instance.resume(); // Returns Promise<void>

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

Остановить или завершить экземпляр Workflow можно вызовом terminate для конкретного ID экземпляра.

let instance = await env.MY_WORKFLOW.get("abc-123");
await instance.terminate(); // Returns Promise<void>

Чтобы перед завершением выполнить зарегистрированные обработчики отката, передайте rollback: true:

let instance = await env.MY_WORKFLOW.get("abc-123");
await instance.terminate({ rollback: true }); // Returns Promise<void>

Также вы можете запускать обработчики отката из Wrangler:

npx wrangler workflows instances terminate <WORKFLOW_NAME> <INSTANCE_ID> --rollback
# For a local Workflows instance during wrangler dev:
npx wrangler workflows instances terminate <WORKFLOW_NAME> <INSTANCE_ID> --local --rollback

После остановки или завершения экземпляр Workflow не может быть возобновлён.

let instance = await env.MY_WORKFLOW.get("abc-123");
await instance.restart(); // Returns Promise<void>

Перезапуск экземпляра немедленно отменяет все выполняющиеся шаги, стирает промежуточное состояние и запускает Workflow заново, как будто он выполняется впервые.

Чтобы перезапустить экземпляр с определённого шага, а не с начала, см. restart в справочнике Workers API.

Вы можете создать новый экземпляр Workflow внутри шага другого Workflow. Родительский Workflow не будет блокироваться в ожидании завершения дочернего Workflow: он продолжает выполнение сразу после успешного создания дочернего экземпляра.

export class ParentWorkflow extends WorkflowEntrypoint {
	async run(event, step) {
		// Perform initial work
		const result = await step.do("initial processing", async () => {
			// ... processing logic
			return { fileKey: "output.pdf" };
		});

		// Trigger a child workflow for additional processing
		const childInstance = await step.do("trigger child workflow", async () => {
			return await this.env.CHILD_WORKFLOW.create({
				id: `child-${event.instanceId}`,
				params: { fileKey: result.fileKey },
			});
		});

		// Parent continues immediately - not blocked by child workflow
		await step.do("continue with other work", async () => {
			console.log(`Started child workflow: ${childInstance.id}`);
			// This runs right away, regardless of child workflow status
		});
	}
}

export class ParentWorkflow extends WorkflowEntrypoint<Env, Params> {
	async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
		// Perform initial work
		const result = await step.do("initial processing", async () => {
			// ... processing logic
			return { fileKey: "output.pdf" };
		});

		// Trigger a child workflow for additional processing
		const childInstance = await step.do("trigger child workflow", async () => {
			return await this.env.CHILD_WORKFLOW.create({
				id: `child-${event.instanceId}`,
				params: { fileKey: result.fileKey },
			});
		});

		// Parent continues immediately - not blocked by child workflow
		await step.do("continue with other work", async () => {
			console.log(`Started child workflow: ${childInstance.id}`);
			// This runs right away, regardless of child workflow status
		});
	}
}

Если дочерний Workflow не удается запустить, шаг завершится с ошибкой и будет повторен согласно вашей конфигурации повторных попыток. После успешного создания дочернего экземпляра он выполняется независимо от родительского.

См. Документация по Workflows REST API.

См. Быстрый старт CLI чтобы узнать больше об управлении и запуске Workflows через командную строку.