はじめに

次を実行して、kv-tutorial という名前の新しいプロジェクトを作成します。

npm create cloudflare@latest -- kv-tutorial

yarn create cloudflare kv-tutorial

pnpm create cloudflare@latest kv-tutorial

セットアップでは、次のオプションを選びます。

• What would you like to start with? では、Hello World example を選びます。
• Which template would you like to use? では、Worker only を選びます。
• Which language do you want to use? では、TypeScript を選びます。
• Do you want to use git for version control? では、Yes を選びます。
• Do you want to deploy your application? では、No を選びます（デプロイ前にいくつか変更します）。

次のような kv-tutorial ディレクトリが作成されます。

新しい kv-tutorial ディレクトリには、次が含まれます。

• index.ts 内の "Hello World" Worker。
• wrangler.jsonc 設定ファイル。wrangler.jsonc により、kv-tutorial Worker が KV データベースへアクセスします。

作成した Worker プロジェクトのディレクトリへ移動します。

cd kv-tutorial

Cloudflare ダッシュボードで、Workers & Pages ページを開きます。

Create application を選択します。

Start with Hello World! > Get started を選択します。

Worker に名前を付けます。このチュートリアルでは、Worker 名を kv-tutorial にします。

Deploy を選択します。

ターミナルを開き、次のコマンドを実行します。

npx wrangler kv namespace create <BINDING_NAME>

npx wrangler kv namespace create <BINDING_NAME> サブコマンドは、新しいバインディング名を引数に取ります。KV 名前空間は、Worker 名（Wrangler ファイルから取得）と指定したバインディング名を連結して作成されます。<BINDING_ID> はランダムに生成されます。

このチュートリアルでは、バインディング名に USERS_NOTIFICATION_CONFIG を使います。

npx wrangler kv namespace create USERS_NOTIFICATION_CONFIG

🌀 Creating namespace with title "USERS_NOTIFICATION_CONFIG"
✨ Success!
Add the following to your configuration file in your kv_namespaces array:
{
	"kv_namespaces": [
		{
			"binding": "USERS_NOTIFICATION_CONFIG",
			"id": "<BINDING_ID>"
		}
	]
}

Cloudflare ダッシュボードで、Workers KV ページを開きます。

Create instance を選択します。

名前空間の名前を入力します。このチュートリアルでは kv_tutorial_namespace を使います。

Create を選択します。

Wrangler ファイルに、手順 2 でターミナルに出力された値を追加します。

{
	"kv_namespaces": [
		{
			"binding": "USERS_NOTIFICATION_CONFIG",
			"id": "<BINDING_ID>"
		}
	]
}

[[kv_namespaces]]
binding = "USERS_NOTIFICATION_CONFIG"
id = "<BINDING_ID>"

バインディング名は、作成した名前空間と一致させる必要はありません。バインディング名は参照用です。具体的には次のとおりです。

• binding に設定した値（文字列）が、Worker 内でこの KV 名前空間を参照するときに使われます。このチュートリアルでは USERS_NOTIFICATION_CONFIG にしてください。
• バインディングは 有効な JavaScript 変数名 ↗ である必要があります。たとえば binding = "MY_KV" や binding = "routingConfig" は、どちらも有効なバインディング名です。
• バインディングは Worker 内の env.<BINDING_NAME> で使えます。このチュートリアルでは env.USERS_NOTIFICATION_CONFIG です。

Cloudflare ダッシュボードで、Workers & Pages ページを開きます。

手順 1 で作成した kv-tutorial Worker を選択します。

Bindings タブを開き、Add binding を選択します。

KV namespace > Add binding を選択します。

Variable name にバインディング名（BINDING_NAME）を入力し、ドロップダウンから 手順 2 で作成した KV 名前空間（kv_tutorial_namespace）を選びます。

Add binding を選択して、バインディングをデプロイします。

ターミナルで wrangler kv key put サブコマンドを実行し、キーと値をそれぞれ入力します。<KEY> と <VALUE> は任意の値です。

npx wrangler kv key put --binding=<BINDING_NAME> "<KEY>" "<VALUE>"

このチュートリアルでは、手順 2 で作成した KV 名前空間に、キー user_1 と値 enabled を追加します。

npx wrangler kv key put --binding=USERS_NOTIFICATION_CONFIG "user_1" "enabled"

Writing the value "enabled" to key "user_1" on namespace <BINDING_ID>.

Cloudflare ダッシュボードで、Workers KV ページを開きます。

作成した KV 名前空間（kv_tutorial_namespace）を選択します。

KV Pairs タブを開きます。

任意の <KEY> を入力します。

任意の <VALUE> を入力します。

Add entry を選択します。

ターミナルで wrangler kv key get サブコマンドを実行し、キーを入力します。

npx wrangler kv key get --binding=<BINDING_NAME> "<KEY>"

このチュートリアルでは、手順 2 で作成した KV 名前空間から、キー user_1 の値を取得します。

npx wrangler kv key get --binding=USERS_NOTIFICATION_CONFIG "user_1" --text

put コマンドと同様に、get コマンドでも --binding または --namespace-id の 2 通りで KV 名前空間へアクセスできます。

Cloudflare ダッシュボードで、Workers KV ページを開きます。

作成した KV 名前空間（kv_tutorial_namespace）を開きます。

KV Pairs タブを開きます。

Worker スクリプトの Env インターフェイスに、KV バインディングを追加します。JavaScript でプロジェクトをブートストラップした場合、この手順は不要です。

interface Env {
	USERS_NOTIFICATION_CONFIG: KVNamespace;
	// ... other binding types
}

USERS_NOTIFICATION_CONFIG の put() メソッドで、新しいキーバリューペアを作成します。KV 名前空間に、キー user_2 と値 disabled を追加します。

let value = await env.USERS_NOTIFICATION_CONFIG.put("user_2", "disabled");

KV の get() メソッドで、KV 名前空間に保存したデータを取得します。KV 名前空間から、キー user_2 の値を取得します。

let value = await env.USERS_NOTIFICATION_CONFIG.get("user_2");

Cloudflare ダッシュボードで、Workers & Pages ページを開きます。

作成した kv-tutorial Worker を開きます。

Edit Code を選択します。

workers.js ファイルの内容を空にし、次のコードを貼り付けます。

export default {
	async fetch(request, env, ctx) {
		try {
			await env.USERS_NOTIFICATION_CONFIG.put("user_2", "disabled");
			const value = await env.USERS_NOTIFICATION_CONFIG.get("user_2");
			if (value === null) {
				return new Response("Value not found", { status: 404 });
			}
			return new Response(value);
		} catch (err) {
			console.error(`KV returned error:`, err);
			const errorMessage =
				err instanceof Error
					? err.message
					: "An unknown error occurred when accessing KV storage";
			return new Response(errorMessage, {
				status: 500,
				headers: { "Content-Type": "text/plain" },
			});
		}
	},
};

export interface Env {
  USERS_NOTIFICATION_CONFIG: KVNamespace;
}

export default {
  async fetch(request, env, ctx): Promise<Response> {
    try {
      await env.USERS_NOTIFICATION_CONFIG.put("user_2", "disabled");
      const value = await env.USERS_NOTIFICATION_CONFIG.get("user_2");
      if (value === null) {
        return new Response("Value not found", { status: 404 });
      }
      return new Response(value);
    } catch (err) {
      console.error(`KV returned error:`, err);
      const errorMessage =
        err instanceof Error
          ? err.message
          : "An unknown error occurred when accessing KV storage";
      return new Response(errorMessage, {
        status: 500,
        headers: { "Content-Type": "text/plain" },
      });
    }
  },
} satisfies ExportedHandler<Env>;

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

1. KV の put() メソッドで、BINDING_NAME へキーを書き込みます。
2. KV の get() メソッドで同じキーを読み取ります。キーが null の場合（未設定、または存在しない場合）はエラーを返します。
3. JavaScript の try...catch ↗ で例外を捕捉します。Workers KV や fetch() を使う外部 API など、何らかのサービスへ書き込みまたは読み取りを行うときは、例外を明示的に処理してください。

ブラウザーは、get() メソッドで指定した KEY に対応する VALUE を返します。

Deploy の横にあるドロップダウン矢印を選び、Save を選択します。

次のコマンドを実行し、KV を Cloudflare のグローバルネットワークへデプロイします。

npm run deploy

新しく作成した Workers KV アプリケーションの URL を開きます。

たとえば新しい Worker の URL が kv-tutorial.<YOUR_SUBDOMAIN>.workers.dev なら、https://kv-tutorial.<YOUR_SUBDOMAIN>.workers.dev/ へアクセスすると、Worker が Workers KV への書き込み（および読み取り）を行います。

Cloudflare ダッシュボードで、Workers & Pages ページを開きます。

kv-tutorial Worker を選択します。

Deployments を選択します。

Version History テーブルから Deploy version を選択します。

Deploy version ページで Deploy を選択します。

これで、最新バージョンの Worker コードが本番へデプロイされます。