Cloudflare Workers KV の初歩

Cloudflare Workers KV は、Cloudflare のエッジサーバからアクセスできる、グローバルなキーバリューストア。
Workers スクリプトからアクセスして使う。
各エッジサーバ毎に存在するのではなく全てのエッジサーバが共有するストアであるため、API など様々な用途で使える。
そしてエッジサーバで動くため、レイテンシが小さくなるというメリットもある。

この記事では、既に Cloudflare Workers を利用しているサイトに Workers KV を導入する手順を見ていく。

まず、名前空間を作成し、それを Workers と紐付ける必要がある。
名前空間の作成は Cloudflare のダッシュボードからもできるが、ここでは CLI ツールの wrangler を使う方法を紹介する。

Workers スクリプトのディレクトリで、以下のコマンドを実行する。wrangler.tomlのaccount_idが設定されている必要があるので注意。

$ wrangler kv:namespace create "MY_KV"
🌀  Creating namespace with title "my-worker-kv-MY_KV"
✨  Success!
Add the following to your configuration file:
kv_namespaces = [
     { binding = "MY_KV", id = "********" }
]

こうすると、my-worker-kv-MY_KVという名前空間が作られる。
my-worker-kvはwrangler.tomlのnameに設定していた値。この値と、先程のコマンドで指定した値を-で連結したものが、Workers KV の名前空間になる。

my-worker-kv-MY_KVはプロダクションで使うことにして、それとは別に開発環境用の名前空間を作成する。

$ wrangler kv:namespace create "MY_KV" --preview
🌀  Creating namespace with title "my-worker-kv-MY_KV_preview"
✨  Success!
Add the following to your configuration file in your kv_namespaces array:
{ binding = "MY_KV", preview_id = "xxxxxxxx", id = "********" }

これで新しくmy-worker-kv-MY_KV_previewという名前空間が作られたので、これを開発環境で使うことにする。

Cloudflare のダッシュボードで、これらの名前空間が作られていることを確認できる。

最後に、名前空間の設定をwrangler.tomlに書き込む。

[env.preview]
kv_namespaces = [
  { binding = "MY_KV", preview_id = "xxxxxxxx" }
]

[env.production]
kv_namespaces = [
  { binding = "MY_KV", id = "********" }
]

これでWorkers スクリプトのなかで、MY_KVという名前で Workers KV にアクセスできるようになった。

早速コードを書いてみる。

addEventListener("fetch", (event) => {
  event.respondWith(handleRequest(event));
});

async function handleRequest(event) {
  let value = await MY_KV.get("my-key");

  if (value === null) {
    value = new Date().toUTCString();
    await MY_KV.put("my-key", value);
  }

  return new Response(value, {
    headers: {
      "content-type": "text/plain",
    },
  });
}

MY_KV.getが値の取得、MY_KV.putが値のセットだということが分かれば、上記のコードの内容はすぐに理解できると思う。
初回アクセス時の現在時刻を Workers KV に保存し、それ以降のアクセスでは保存された時刻を使い続ける。

ローカルで動作確認するためには、$ wrangler dev --env previewで開発環境を起動する。

$ wrangler dev --env preview
💁  watching "./"
👂  Listening on http://127.0.0.1:8787

http://127.0.0.1:8787にアクセスすると、my-worker-kv-MY_KV_previewにmy-key: 現在時刻というペアを保存する。
my-worker-kv-MY_KVは影響を受けない。

そして$ wrangler publish --env productionでプロダクションにデプロイできる。

プロダクションにアクセスすると、my-worker-kv-MY_KVにmy-key: 現在時刻というペアを保存する。