← Cloudflare Workflows / workflows / build

Události a parametry

Při spuštění Workflow může přijmout volitelnou událost. Tato událost může obsahovat data, se kterými váš Workflow dále pracuje, například podrobnosti požadavku, uživatelská data načtená z databáze (například D1 nebo KV) nebo z webhooku, případně zprávy od konzumenta Queue.

Události jsou důležitou součástí Workflow, protože často potřebujete, aby Workflow pracoval s daty. Vzhledem k tomu, že daná instance Workflow běží odolně, jsou události užitečným způsobem, jak Workflow předat data, která by měla zůstat neměnná (nemění se), případně představují data, s nimiž Workflow potřebuje v daný okamžik pracovat.

Předání dat do Workflow

Parametry do Workflow můžete předat třemi způsoby:

Jako volitelný argument pro create metody na Vazba na Workflow při spouštění Workflow z Workeru.
Pomocí --params příznak při použití wrangler CLI ke spuštění Workflow.
Pomocí step.waitForEvent API, které instanci Workflow umožňuje čekat na přijetí události (a volitelných dat) zatímco běží. Instance Workflow mohou přijímat události z externích služeb přes HTTP nebo prostřednictvím Workers API pro Workflows.

Jako parametr můžete předat libovolný objekt serializovatelný do JSON.

export default {
	async fetch(req, env) {
		let someEvent = { url: req.url, createdTimestamp: Date.now() };
		// Trigger our Workflow
		// Pass our event as the second parameter to the `create` method
		// on our Workflow binding.
		let instance = await env.MY_WORKFLOW.create({
			id: crypto.randomUUID(),
			params: someEvent,
		});

		return Response.json({
			id: instance.id,
			details: await instance.status(),
		});
	},
};

export default {
	async fetch(req: Request, env: Env) {
		let someEvent = { url: req.url, createdTimestamp: Date.now() };
		// Trigger our Workflow
		// Pass our event as the second parameter to the `create` method
		// on our Workflow binding.
		let instance = await env.MY_WORKFLOW.create({
			id: crypto.randomUUID(),
			params: someEvent,
		});

		return Response.json({
			id: instance.id,
			details: await instance.status(),
		});
	},
};

Chcete-li předat parametry pomocí wrangler rozhraní příkazového řádku předejte řetězec JSON jako druhý parametr workflows trigger podpříkaz:

npx wrangler@latest workflows trigger workflows-starter '{"some":"data"}'

🚀 Workflow instance "57c7913b-8e1d-4a78-a0dd-dce5a0b7aa30" has been queued successfully

Čekání na události

Běžící Workflow může čekat na událost (nebo události) voláním step.waitForEvent ve Workflow, díky které můžete odesílat události do Workflow dvěma způsoby:

Pomocí Workers API binding: volejte instance.sendEvent pro odesílání událostí konkrétním instancím workflow.
Prostřednictvím REST API (HTTP API) Koncový bod pro události.

Protože waitForEvent je součástí WorkflowStep API ji můžete v rámci Workflow volat vícekrát a pomocí řídicích konstrukcí podmíněně čekat na událost.

Volání waitForEvent vyžaduje, abyste zadali type (až 100 znaků ¹), která se používá k přiřazení odpovídajícího type při odesílání události do instance Workflow.

Pokud chcete například počkat na fakturační webhook:

export class MyWorkflow extends WorkflowEntrypoint {
	async run(event, step) {
		// Other steps in your Workflow
		let stripeEvent = await step.waitForEvent(
			"receive invoice paid webhook from Stripe",
			{ type: "stripe-webhook", timeout: "1 hour" },
		);
		// Rest of your Workflow
	}
}

export class MyWorkflow extends WorkflowEntrypoint<Env, Params> {
	async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
		// Other steps in your Workflow
		let stripeEvent = await step.waitForEvent<IncomingStripeWebhook>(
			"receive invoice paid webhook from Stripe",
			{ type: "stripe-webhook", timeout: "1 hour" },
		);
		// Rest of your Workflow
	}
}

Výše uvedený příklad:

Volání waitForEvent s type z stripe-webhook - odpovídající sendEvent volání by tedy bylo await instance.sendEvent({type: "stripe-webhook", payload: webhookPayload}).
Používá TypeScript parametr typu ↗ pro určení typu návratové hodnoty step.waitForEvent jako naši IncomingStripeWebhook.
Pokračuje se zbytkem Workflow.

Výchozí časový limit pro waitForEvent volání je 24 hodin, což lze změnit předáním { timeout: WorkflowTimeoutDuration } jako druhý argument do svého waitForEvent volání.

let event = await step.waitForEvent("wait for human approval", {
	type: "approval-flow",
	timeout: "15 minutes",
});

let event = await step.waitForEvent(
		"wait for human approval",
		{ type: "approval-flow", timeout: "15 minutes" },
	);

Timeout můžete nastavit v rozmezí od 1 sekundy až po 365 dní.

Chování časového limitu

Když waitForEvent vyprší časový limit, Workflow vyvolá chybu a instance selže. Pokud chcete, aby váš Workflow pokračoval i v případě, že událost nebude přijata, obalte waitForEvent volání v try...catch blok:

try {
	const event = await step.waitForEvent("wait for approval", {
		type: "approval",
		timeout: "1 hour",
	});
	// Handle the received event
} catch (e) {
	// Timeout occurred - handle the case where no event was received
	console.log("No approval received, proceeding with default action");
}

try {
	const event = await step.waitForEvent("wait for approval", {
		type: "approval",
		timeout: "1 hour",
	});
	// Handle the received event
} catch (e) {
	// Timeout occurred - handle the case where no event was received
	console.log("No approval received, proceeding with default action");
}

Odesílání událostí běžícím workflows

Instance Workflow čekající na události pomocí waitForEvent API lze odesílat události pomocí instance.sendEvent API:

export default {
	async fetch(req, env) {
		const instanceId = new URL(req.url).searchParams.get("instanceId");
		const webhookPayload = await req.json();

		let instance = await env.MY_WORKFLOW.get(instanceId);
		// Send our event, with `type` matching the event type defined in
		// our step.waitForEvent call
		await instance.sendEvent({
			type: "stripe-webhook",
			payload: webhookPayload,
		});

		return Response.json({
			status: await instance.status(),
		});
	},
};

export default {
	async fetch(req: Request, env: Env) {
		const instanceId = new URL(req.url).searchParams.get("instanceId");
		const webhookPayload = await req.json<Payload>();

		let instance = await env.MY_WORKFLOW.get(instanceId);
		// Send our event, with `type` matching the event type defined in
		// our step.waitForEvent call
		await instance.sendEvent({
			type: "stripe-webhook",
			payload: webhookPayload,
		});

		return Response.json({
			status: await instance.status(),
		});
	},
};

Podobně jako waitForEvent příkladu v tomto průvodci type vlastnost v naší waitForEvent a sendEvent pole se musí shodovat.
Chcete-li odeslat více událostí do Workflow, který má více waitForEvent volání zavolejte sendEvent s odpovídajícím type nastavená vlastnost (až 100 znaků ¹).
Události lze také odesílat pomocí rozhraní REST API (HTTP API) přes Koncový bod pro události.

TypeScript a parametry typu

Ve výchozím nastavení WorkflowEvent předaný do run metoda vaší definice Workflow má typ, který odpovídá následujícímu:

export type WorkflowCronSchedule = {
	/** Cron expression that triggered this event. */
	cron: string;
	/** Timestamp of the scheduled trigger, in milliseconds since the Unix epoch. */
	scheduledTime: number;
};

export type WorkflowEvent<T> = {
	/** The data passed as the parameter when the Workflow instance was triggered. */
	payload: Readonly<T>;
	/** The timestamp that the Workflow was triggered. */
	timestamp: Date;
	/** ID of the current Workflow instance. */
	instanceId: string;
	/** Name of the current Workflow. */
	workflowName: string;
	/** Metadata for Workflow instances created by a cron schedule. */
	schedule?: WorkflowCronSchedule;
};

Když je instance Workflow vytvořena pomocí cron plánu nakonfigurovaného na Workflow bindingu, event.schedule obsahuje cron výraz, který vytvořil instanci, a plánovaný čas spuštění:

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

Tyto události můžete volitelně typovat definováním vlastního typu a jeho předáním jako parametr typu ↗ do WorkflowEvent:

// Define a type that conforms to the events your Workflow instance is
// instantiated with
interface YourEventType {
	userEmail: string;
	createdTimestamp: number;
	metadata?: Record<string, string>;
}

Když předáte svůj YourEventType na WorkflowEvent jako parametr typu, event.payload vlastnost nyní má typ YourEventType v celé definici vašeho Workflow:

src/index.ts

// Import the Workflow definition
import { WorkflowEntrypoint, WorkflowStep, WorkflowEvent} from 'cloudflare:workers';

export class MyWorkflow extends WorkflowEntrypoint {
	// Pass your type as a type parameter to WorkflowEvent
	// The 'payload' property will have the type of your parameter.
	async run(event: WorkflowEvent<YourEventType>, step: WorkflowStep) {
		let state = await step.do("my first step", async () => {
			// Access your properties via event.payload
          let userEmail = event.payload.userEmail
          let createdTimestamp = event.payload.createdTimestamp
        })

        await step.do("my second step", async () => { /* your code here */ })
	}
}

Parametr typu můžete zadat také do Workflows typ při vytváření (spouštění) instance Workflow pomocí create metoda v rámci Workers API. Upozorňujeme, že to ne přenášet informace o typech do samotného Workflow, protože typy TypeScript jsou konstrukcí, která existuje pouze v době sestavení.

Poznámky pod čarou

Vzor pro shodu: ^[a-zA-Z0-9_][a-zA-Z0-9-_]*$ ↩ ↩²