Cloudflare Workflowsのワークフローを自分で実装する方法

Cloudflareの新機能であるWorkflowsは複数のステップに分かれたタスクを実行できる機能であり、Cloudflare Workersを利用しています。Workflowを作成する際は、Class形式でワークフローを実装し、Bindingした後にwranglerでデプロイする必要があります。ベータ版の機能ではありますが、複数のステップの実行やリトライをさせたいワークフローを作成する際に便利であり、単一のフローとしては使いやすい機能と言えます。

Cloudflarenには、複数のステップに分かれたタスクを実行できるWorkflows機能がベータ提供されています。最も簡単なセットアップ方法はcreate-cloudflareコマンドを利用することですが、既存のプロジェクトへ後から追加するケースなどを考えて、手組みに挑戦してみました。

Cloudflare Workersプロジェクトをセットアップする

Cloudflare WorkflowsはCloudflare Workersを利用しています。そのため、セットアップは手組みする場合でもnpx create cloudflareを使うのが簡単です。

% npm create cloudflare

TypeScriptを使う場合は、cf-typegenも実行してworker-configutation.d.tsファイルを作りましょう。これでEnvの型定義がグローバルに利用できます。

% npm run cf-typegen

Workflowをクラスで定義する

早速ワークフローを追加します。ワークフローはClass形式で実装しますので、src/workflows/MyWorkflow.tsのようなフローごとのファイルを作りましょう。step.doの中にステップごとにやらせたい作業を定義していきます。

import { WorkflowEntrypoint, WorkflowEvent, WorkflowStep } from 'cloudflare:workers';
type Params = {};

export class MyWorkflow extends WorkflowEntrypoint<Env, Params> {
    async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
        let state = step.do('my first step', async () => {
            return [1, 2, 3];
        });

        step.do('my second step', async () => {
            for (let data in state) {
                console.log({data})
            }
        });
    }
}

作成したWorkflowクラスを`wrangler.jsonc`に登録する

作成したワークフローをWorkersから利用するには、KVやR2などと同様Bindingが必要です。wrangler.jsoncにworkflowsキーの配列で識別名・Bindingした後に使う変数名・利用するクラスの名前の3つを指定しましょう。

{
    "$schema": "node_modules/wrangler/config-schema.json",
    "name": "workflow-demo",
    "main": "src/index.ts",
    "compatibility_date": "2025-03-03",
    "observability": {
        "enabled": true
    },
    "workflows": [
        {
            "name": "workflows-starter",
            "binding": "MY_WORKFLOW",
            "class_name": "MyWorkflow"
        }
    ]

Workflowを実行するAPIを作る

最後にワークフローを実行する処理を、Workersに追加しましょう。今回はシンプルにsrc/index.tsへREST APIとして実装しました。


export * from './workflows/MyWorkflow.ts'

export default {
    async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
        let url = new URL(request.url);

        if (url.pathname.startsWith('/favicon')) {
            return Response.json({}, { status: 404 });
        }
        const instance = await env.MY_WORKFLOW.create();

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

ここでポイントとなるのは、１行目のexportしている部分です。Workflowのクラスをexportしないとwranglerでテストやデプロイする際にエラーが発生します。

> wrangler deploy

✘ [ERROR] Your Worker depends on the following Workflows, which are not exported in your entrypoint file: MyWorkflow.

  You should export these objects from your entrypoint, src/index.ts.

エントリーポイントでexportしてやることで、Bindingしたクラスをenv.BINDING_NAMEとして使えるようになるということみたいですね。

Wranglerでデプロイする

最後にデプロイしてみましょう。

% wrangler deploy

「まだオープンベータの機能だよ」という警告がでます。この辺りはベータ版を使うことをどれくらい許容できるかという話にはなりますね。

▲ [WARNING] Workflows is currently in open beta.

curlでAPIを呼び出すと、Cloudflareダッシュボードのワークフローページに実行履歴が出てきました。

ステップごとのoutputが確認できます。step.do内で実装した処理の戻り値がでますので、戻り値を必要としないステップでもデバッグに使える情報はreturnしておくのがよさそうです。

おわりに

ベータ版の機能ですが、複数ステップの実行かつリトライをさせたいワークフローなどをCloudflareで作るには、なかなか良さそうな機能でした。一方でAWSのStep Functionsほどの多機能さはなく、並列処理や条件分岐を組むことや、頑張って組んだ際のフロー可視化などはこれからかなと思います。

とはいえ単一のフローとしてはなかなか良さそうですので、細々としたタスクを処理させるのに使っていこうと思います。

Documents

https://developers.cloudflare.com/workflows/build/workers-api/