コンテンツにスキップ

始める

このガイドでは、以下のことを説明します：

  • Durable Objectを定義するクラスの作成。
  • Fetch APIを介して別のWorkerからDurable Objectをインスタンス化し、通信する。
  • Durable Objectをデプロイする。
  1. Sign up for a Cloudflare account ↗.
  2. Install npm ↗.
  3. Install Node.js ↗.

Node.js version manager

Use a Node version manager like Volta ↗ or nvm ↗ to avoid permission issues and change Node.js versions. Wrangler, discussed later in this guide, requires a Node version of 16.17.0 or later.

1. ダッシュボードでDurable Objectsを有効にする

Durable Objectsを有効にするには、Workersの有料プランを購入する必要があります：

  1. Cloudflareダッシュボード ↗にログインし、アカウントを選択します。
  2. Workers & Pages > Plansに移動します。
  3. Purchase Workers Paidを選択し、Durable Objectsを有効にするための支払いプロセスを完了します。

2. Workerプロジェクトを作成する

Durable ObjectにはWorkerからアクセスします。あなたのWorkerアプリケーションは、Durable Objectと対話するためのインターフェースです。

Workerプロジェクトを作成するには、次のコマンドを実行します：

Terminal window
npm create cloudflare@latest -- durable-object-starter

create cloudflare@latestを実行すると、WranglerというWorkers CLIがインストールされます。プロジェクトのテストとデプロイにはWranglerを使用します。

For setup, select the following options:

  • For What would you like to start with?, choose Hello Worldの例.
  • For Which template would you like to use?, choose Durable Objectsを使用したHello World Worker.
  • For Which language do you want to use?, choose JavaScript / Typescript.
  • For Do you want to use git for version control?, choose Yes.
  • For Do you want to deploy your application?, choose No (we will be making some changes before deploying).

これにより、新しいディレクトリが作成され、コードを書くためのsrc/index.jsまたはsrc/index.tsファイルと、wrangler.toml設定ファイルが含まれます。

新しいディレクトリに移動します：

Terminal window
cd durable-object-starter

3. Durable Objectを定義するクラスを書く

Durable Objectを作成しアクセスする前に、その動作は通常のエクスポートされたJavaScriptクラスによって定義される必要があります。

MyDurableObjectクラスには、2つのパラメータを持つコンストラクタがあります。最初のパラメータstateは、Durable Objectに特有の状態を含み、ストレージにアクセスするためのメソッドが含まれています。2番目のパラメータenvは、アップロード時にWorkerに関連付けたバインディングを含みます。

export class MyDurableObject {
  constructor(state, env) {}
}

Workersはfetch APIを介してDurable Objectと通信します。Workerと同様に、Durable Objectはイベントハンドラを登録することによって、受信したfetchイベントをリッスンします。Durable Objectの場合、fetchハンドラはクラスのメソッドとして定義されます。

あなたのファイルは次のようになります：

export class MyDurableObject {
  constructor(state, env) {}


  async fetch(request) {
    return new Response("Hello World");
  }
}

Workerは、ヘッダー、HTTPメソッド、リクエストボディ、またはリクエストURIを介してDurable Objectに情報を渡すことができます。

4. Durable Objectをインスタンス化し、通信する

fetch()ハンドラを使用すると、WorkerからDurable Objectをインスタンス化し、通信することができます。

Durable Objectと通信するために、fetchハンドラは次のようになります：

export default {
  async fetch(request, env) {
    let id = env.MY_DURABLE_OBJECT.idFromName(new URL(request.url).pathname);


    let stub = env.MY_DURABLE_OBJECT.get(id);


    let response = await stub.fetch(request);


    return response;
  },
};

上記のコードでは、次のことを行っています：

  1. HTTPリクエストを受け取るためのfetch()ハンドラなど、Workerの主要なイベントハンドラをエクスポートしました。
  2. fetch()ハンドラにenvを渡しました。バインディングは、イベントハンドラまたはクラスコンストラクタが呼び出されるときに渡される環境オブジェクトのプロパティとして提供されます。バインディングのidFromName()関数を呼び出すことで、文字列から派生したオブジェクトIDを使用します。システムにランダムなユニークIDを生成させることもできます。システム生成のユニークIDはパフォーマンス特性が優れていますが、後でオブジェクトに再アクセスするためにIDをどこかに保存する必要があります。
  3. URLパスからオブジェクトIDを導出しました。MY_DURABLE_OBJECT.idFromName()は、同じ文字列を入力として与えられた場合、常に同じIDを返します（同じクラスで呼び出された場合）。しかし、異なる文字列（または異なるクラス）に対しては決して同じIDを返しません。この場合、各ユニークパスに対して新しいオブジェクトを作成しています。
  4. IDを使用してDurable Objectのスタブを構築しました。スタブは、Durable Objectにメッセージを送信するために使用されるクライアントオブジェクトです。
  5. リクエストをDurable Objectに転送しました。stub.fetch()は、リクエストのURLに関係なく、常にオブジェクトに送信されるため、グローバルなfetch()関数と同じシグネチャを持っています。新しいオブジェクトにリクエストを送信する最初の時に、そのオブジェクトが作成されます。オブジェクトに耐久性のある状態を保存しない場合、後で自動的に削除されます（再度リクエストすると再作成されます）。耐久性のある状態を保存する場合、オブジェクトはメモリから追い出されることがありますが、その耐久性のある状態は永続的に保持されます。
  6. return responseでクライアントにHTTPレスポンスを返しました。

Durable Objectとの通信について詳しくは、WorkerからDurable Objectにアクセスするを参照してください。

5. Durable Objectバインディングを構成する

Bindingsは、WorkersがCloudflare開発者プラットフォーム上のリソースと対話することを可能にします。Workerプロジェクトのwrangler.tomlにおけるDurable Objectバインディングには、バインディング名（このガイドではMY_DURABLE_OBJECTを使用）とクラス名（MyDurableObject）が含まれます。

[[durable_objects.bindings]]
name = "MY_DURABLE_OBJECT"
class_name = "MyDurableObject"


# または


[durable_objects]
bindings = [
  { name = "MY_DURABLE_OBJECT", class_name = "MyDurableObject" }
]

[[durable_objects.bindings]]セクションには、次のフィールドが含まれます：

  • name - 必須。Worker内で使用するバインディング名。
  • class_name - 必須。バインドしたいクラス名。
  • script_name - オプション。現在の環境のWorkerコードがデフォルトです。

6. マイグレーションを使用してDurable Objectクラスを構成する

マイグレーションは、クラス名からランタイム状態へのマッピングプロセスです。新しいDurable Objectクラスを作成する際、または既存のDurable Objectクラスを名前変更、削除、または転送する際にマイグレーションを実行します。

マイグレーションは、wrangler.tomlファイルの[[migrations]]構成キーを介して実行されます。

新しいDurable Objectクラスを作成するためのDurable Objectマイグレーションは、Workerのwrangler.tomlファイルで次のようになります：

[[migrations]]
tag = "v1" # 各エントリに対してユニークであるべき
new_classes = ["MyDurableObject"] # 新しいクラスの配列

マイグレーションプロセスについて詳しくは、Durable Objectsのマイグレーションを参照してください。

7. Durable Object Workerをローカルで開発する

Durable Objectをローカルでテストするには、wrangler devを実行します：

Terminal window
npx wrangler dev

コンソールには、Durable Objectから返されたHello world文字列が表示されるはずです。

8. Durable Object Workerをデプロイする

Durable Object Workerをデプロイするには：

Terminal window
npx wrangler deploy

デプロイが完了すると、Cloudflareダッシュボード ↗のWorkers & Pages > Overviewで新しく作成したDurable Object Workerを見ることができるはずです。

あなたのDurable Object Workerを<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.devでプレビューします。

このチュートリアルを終えることで、Durable Objectを作成、テスト、デプロイすることに成功しました。

関連リソース

Cloudflare DashboardDiscordCommunityLearning CenterSupport Portal
Cookie Settings