← Cloudflare Workflows / workflows / build

Spouštění Workflows

Workflows můžete spouštět jak programově, tak prostřednictvím Workflows API, mimo jiné:

1. S Workers prostřednictvím HTTP požadavků v fetch handleru nebo bindingy z queue nebo scheduled handler
2. V pravidelném intervalu definovaném pomocí schedules u bindingu Workflow ve vaší konfiguraci Wrangler
3. Pomocí Workflows REST API
4. Pomocí wrangler CLI ve svém terminálu

S Workflows můžete programově pracovat z libovolného skriptu Workers vytvořením vazby na Workflow. Worker může být navázán na více Workflows, včetně těch definovaných v jiných projektech (skriptech) Workers ve vašem účtu.

Workflow můžete spustit:

• Přímo přes HTTP pomocí fetch handler
• Z Queue consumer uvnitř queue handler
• Podle pravidelného plánu definovaného pomocí schedules na bindingu Workflow v wrangler.jsonc
• Z Cron Trigger uvnitř scheduled handler
• V rámci Durable Object

Abyste se z kódu Workers mohli navázat na Workflow, musíte definovat binding ke konkrétnímu Workflow. Chcete-li se například napojit na Workflow definovaný v úvodní příručka, byste nakonfigurovali Konfigurační soubor Wrangler s následujícím:

{
	"$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" řádek definuje proměnnou JavaScript, na které jsou dostupné metody našeho Workflow, včetně create (která spustí novou instanci) nebo get (která vrací stav existující instance).

Pokud chcete vytvářet instance Workflow v pravidelném intervalu, přidejte schedules pole (až 100 výrazů cron na účet) do vazby Workflow v konfiguraci 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 * * * *" ]

Každý odpovídající cron výraz automaticky vytvoří novou instanci Workflow. Použijte to, když chcete spouštět Workflow podle rozvrhu, aniž byste definovali na nejvyšší úrovni triggers.crons a samostatný scheduled handler.

Naplánované instance obsahují odpovídající cron výraz a naplánovaný čas spuštění na 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));
		}
	}
}

Na Workers Paid, instance Workflow vytvořené schedules může běžet až jednu hodinu na jedno spuštění cronu, aniž by spotřeboval slot souběžnosti Workflow. Pokud se instance po uplynutí tohoto okna pozastaví nebo uspí, uvolní své místo a po obnovení vstoupí do běžné fronty souběžnosti. Pokračuje, jakmile je k dispozici slot souběžnosti.

Při konfiguraci plánů Workflow používejte nejnovější verzi Wrangleru. Pokud vaše místní schéma Wrangleru nerozpoznává schedules ještě nemáte, před nasazením aktualizujte Wrangler.

Následující příklad ukazuje, jak lze Workflows spravovat přímo z Workeru, mimo jiné:

• Zjištění stavu existující instance Workflow podle jejího ID
• Vytváření (spouštění) nové instance Workflow
• Vracení stavu daného ID instance

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(),
		});
	},
};

Stav libovolné běžící instance Workflow můžete zjistit zavoláním status pro konkrétní ID instance. To umožňuje programově zjistit, zda je instance ve frontě (čeká na naplánování), aktivně běží, je pozastavená, nebo je v chybovém stavu.

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

Pole status může nabývat těchto hodnot:

  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;

Pokud váš Workflow registruje obslužné rutiny rollbacku na step.do(), zkontrolovat rollback po dokončení instance, aby bylo možné zjistit, zda kompenzační kroky proběhly úspěšně. Zatímco rollback aktivně probíhá, Workers API nadále vrací status: "running".

Instanci Workflow můžete explicitně pozastavit (a později obnovit) zavoláním pause pro konkrétní ID instance.

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

Pozastavenou instanci Workflow můžete obnovit zavoláním resume pro konkrétní ID instance.

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

Volání resume u instance, která aktuálně není pozastavena, nebude mít žádný účinek.

Instanci Workflow můžete zastavit/ukončit zavoláním terminate pro konkrétní ID instance.

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

Chcete-li před ukončením spustit registrované rollback handlery, předejte rollback: true:

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

Rollback handlery můžete spouštět také z Wrangleru:

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

Jakmile je zastavena nebo ukončena, instance Workflow nelze být obnoven.

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

Restartováním instance se okamžitě zruší všechny rozpracované kroky, vymaže se veškerý mezistav a Workflow se bude chovat, jako by běžel poprvé.

Chcete-li restartovat instanci od konkrétního kroku místo od začátku, přečtěte si restart v referenční dokumentaci Workers API.

Novou instanci Workflow můžete vytvořit i v rámci kroku jiného Workflow. Nadřazený Workflow přitom nečeká na dokončení podřízeného Workflow: pokračuje ve vykonávání ihned po úspěšném vytvoření podřízené instance.

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
		});
	}
}

Pokud se podřízený Workflow nepodaří spustit, krok selže a bude opakován podle vaší konfigurace opakování. Jakmile je podřízená instance úspěšně vytvořena, běží nezávisle na nadřazené instanci.

Viz Dokumentace Workflows REST API.

Viz Rychlý start s CLI kde se dozvíte více o tom, jak spravovat a spouštět Workflows z příkazové řádky.