コンテンツにスキップ

始める

Workers KVは、あなたのCloudflare Workersアプリケーションに低遅延、高スループットのグローバルストレージを提供します。Workers KVは、ユーザー設定データ、ルーティングデータ、A/Bテストの設定、認証トークンの保存に最適で、読み取りが多いワークロードに適しています。

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

  • KV名前空間の作成
  • Cloudflare WorkerからKV名前空間にキーと値のペアを書き込む
  • KV名前空間からキーと値のペアを読み取る

前提条件

続行するには：

  1. まだであれば、Cloudflareアカウント ↗にサインアップしてください。
  2. npm ↗をインストールします。
  3. Node.js ↗をインストールします。権限の問題を避け、Node.jsのバージョンを変更するために、Volta ↗やnvm ↗のようなNodeバージョンマネージャを使用してください。Wranglerは、16.13.0以上のNodeバージョンを必要とします。
  4. Wranglerのインストールを最新バージョンに更新します。

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

KV名前空間に読み書きするための新しいWorkerを作成します。

  1. 次のコマンドを実行して、kv-tutorialという名前の新しいプロジェクトを作成します：

    Terminal window
    npm create cloudflare@latest -- kv-tutorial

    For setup, select the following options:

    • For What would you like to start with?, choose Hello World example.
    • For Which template would you like to use?, choose Hello World Worker.
    • For Which language do you want to use?, choose 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).

    これにより、以下のような新しいkv-tutorialディレクトリが作成されます。

    • ディレクトリkv-tutorial/
      • ディレクトリnode_modules/
        • …
      • ディレクトリtest/
        • …
      • ディレクトリsrc
        • index.ts
      • package-lock.json
      • package.json
      • testconfig.json
      • vitest.config.mts
      • worker-configuration.d.ts
      • wrangler.toml

    新しいkv-tutorialディレクトリには以下が含まれています：

    • index.tsにある「Hello World」Worker。
    • wrangler.toml設定ファイル。wrangler.tomlは、kv-tutorial WorkerがKVデータベースにアクセスする方法です。

  2. 作成したWorkerプロジェクトのディレクトリに移動します：

    Terminal window
    cd kv-tutorial

2. KV名前空間を作成する

KV名前空間は、Cloudflareのグローバルネットワークに複製されたキーと値のデータベースです。

Wranglerまたはダッシュボードを介してKV名前空間を作成できます。

Wranglerを介してKV名前空間を作成する

Wranglerを使用すると、KV名前空間内のエントリを追加、リスト、取得、削除できます。

Wranglerを介してKV名前空間を作成するには：

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

    Terminal window
    npx wrangler kv namespace create <YOUR_NAMESPACE>

    npx wrangler kv namespace create <YOUR_NAMESPACE>サブコマンドは、新しいバインディング名を引数として受け取ります。KV名前空間は、あなたのWorkerの名前（wrangler.tomlファイルから）と提供したバインディング名の連結を使用して作成されます。idはランダムに生成されます。

    Terminal window
    npx wrangler kv namespace create <YOUR_NAMESPACE>
    🌀  Creating namespace with title <YOUR_WORKER-YOUR_NAMESPACE>
    ✨  Success!
    Add the following to your configuration file:
    kv_namespaces = [
      { binding = <YOUR_BINDING>, id = "e29b263ab50e42ce9b637fa8370175e8" }
    ]

  2. wrangler.tomlファイルに、ターミナルで生成された値を使って以下を追加します：

    kv_namespaces = [
        { binding = "<YOUR_BINDING>", id = "<YOUR_ID>" }
    ]

    バインディング名は、作成した名前空間に対応する必要はありません。バインディング名は単なる参照です。具体的には：

    • <YOUR_BINDING>に設定した値（文字列）は、Worker内でこのデータベースを参照するために使用されます。このチュートリアルでは、バインディング名をDBと名付けます。
    • バインディングは有効なJavaScript変数名 ↗である必要があります。例えば、binding = "MY_KV"やbinding = "routingConfig"は、どちらもバインディングの有効な名前です。
    • あなたのバインディングは、Worker内でenv.<YOUR_BINDING>として利用可能です。

ダッシュボードを介してKV名前空間を作成する

  1. Cloudflareダッシュボード ↗にログインします。
  2. Workers & Pages > KVを選択します。
  3. Create a namespaceを選択します。
  4. 名前空間の名前を入力します。
  5. Addを選択します。

3. Wranglerを使用してKV名前空間と相互作用する

Wranglerを介して、または直接WorkersアプリケーションからKV名前空間と相互作用できます。

Wranglerを介して値を書く

Wranglerを使用して空のKV名前空間に値を書き込むには：

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

    Terminal window
    npx wrangler kv key put --binding=<YOUR_BINDING> "<KEY>" "<VALUE>"
    Writing the value "<VALUE>" to key "<KEY>" on namespace e29b263ab50e42ce9b637fa8370175e8.

--bindingの代わりに、--namespace-idを使用して、どのKV名前空間が操作を受け取るかを指定することもできます：

Terminal window
npx wrangler kv key put --namespace-id=e29b263ab50e42ce9b637fa8370175e8 "<KEY>" "<VALUE>"
Writing the value "<VALUE>" to key "<KEY>" on namespace e29b263ab50e42ce9b637fa8370175e8.

ローカルモードでキーと値を作成するには、コマンドの最後に--localフラグを追加します：

Terminal window
npx wrangler kv key put --namespace-id=xxxxxxxxxxxxxxxx "<KEY>" "<VALUE>" --local

Wranglerを介して値を取得する

Wranglerを使用して値にアクセスするには：

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

    Terminal window
    # [OPTIONS]を--bindingまたは--namespace-idに置き換えます
    npx wrangler kv key get [OPTIONS] "<KEY>"

    KV名前空間は2つの方法で指定できます：

    --bindingを使用して
    Terminal window
    npx wrangler kv key get --binding=<YOUR_BINDING> "<KEY>"

    --namespace-idを使用して
    Terminal window
    npx wrangler kv key get --namespace-id=<YOUR_ID> "<KEY>"

プレビュー名前空間と相互作用するために--previewフラグを追加できます。

複数のキーと値のペアを指定されたKV名前空間に書き込むためのkv bulkドキュメントを参照してください。

4. WorkerからKV名前空間にアクセスする

Worker内からバインディングにアクセスできます。

  1. Workerスクリプト内で、EnvインターフェースにKV名前空間を追加します：

    interface Env {
      YOUR_KV_NAMESPACE: KVNamespace;
      // ... 他のバインディングタイプ
    }

  2. YOUR_KV_NAMESPACEのput()メソッドを使用して、新しいキーと値のペアを作成するか、特定のキーの値を更新します：

    let value = await env.YOUR_KV_NAMESPACE.put(key, value);

  3. KVのget()メソッドを使用して、KVデータベースに保存したデータを取得します：

    let value = await env.YOUR_KV_NAMESPACE.get("KEY");

あなたのWorkerコードは次のようになります：

export interface Env {
  YOUR_KV_NAMESPACE: KVNamespace;
}


export default {
  async fetch(request, env, ctx): Promise<Response> {
    try {
      await env.YOUR_KV_NAMESPACE.put("KEY", "VALUE");
      const value = await env.YOUR_KV_NAMESPACE.get("KEY");
      if (value === null) {
        return new Response("Value not found", { status: 404 });
      }
      return new Response(value);
    } catch (err) {
      // プロダクションアプリケーションでは、KVの
      // 読み取りを再試行するか、デフォルトのコードパスにフォールバックすることを選択できます。
      console.error(`KV returned error: ${err}`);
      return new Response(err, { status: 500 });
    }
  },
} satisfies ExportedHandler<Env>;

上記のコードは：

  1. KVのput()メソッドを使用してYOUR_KV_NAMESPACEにキーを書き込みます。
  2. KVのget()メソッドを使用して同じキーを読み取り、キーがnullの場合（またはキーが設定されていない場合、または存在しない場合）にエラーを返します。
  3. JavaScriptのtry...catch ↗例外処理を使用して、潜在的なエラーをキャッチします。Workers KVやfetch()を使用した外部APIからの読み書きなど、サービスからの読み書きを行う際には、例外を明示的に処理することを期待するべきです。

プロジェクトをローカルで実行するには、プロジェクトディレクトリ内で次のコマンドを入力します：

Terminal window
npx wrangler dev

wrangler devを実行すると、WranglerはWorkerを確認するためのURL（通常はlocalhost:8787）を提供します。ブラウザは、Wranglerが提供したURLにアクセスすると、あなたの値を表示します。

5. KVをデプロイする

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

    Terminal window
    npx wrangler deploy

  2. 新しく作成したWorkers KVアプリケーションのURLにアクセスします。

    例えば、新しいWorkerのURLがkv-tutorial.<YOUR_SUBDOMAIN>.workers.devの場合、https://kv-tutorial.<YOUR_SUBDOMAIN>.workers.dev/にアクセスすると、あなたのWorkerにリクエストが送信され、Workers KVから書き込み（および読み取り）が行われます。

まとめ

このチュートリアルを完了することで、あなたは：

  1. KV名前空間を作成しました
  2. その名前空間に書き込みと読み取りを行うWorkerを作成しました
  3. プロジェクトをグローバルにデプロイしました。

次のステップ

機能リクエストがある場合やバグを見つけた場合は、Cloudflare DevelopersコミュニティにDiscordで参加して ↗、直接フィードバックを共有してください。

Cloudflare DashboardDiscordCommunityLearning CenterSupport Portal
Cookie Settings