コンテンツにスキップ

キーと値のペアを読み取る

特定のキーの値を取得するには、あなたのWorkerコードにバインドされている任意のKV名前空間のget()メソッドを呼び出します：

env.NAMESPACE.get(key);

get()メソッドは、値を取得するためにawaitできるPromiseを返します。キーが見つからない場合、Promiseはリテラル値nullで解決されます。

例

Worker内からキーを読み取る例：

export default {
  async fetch(request, env, ctx) {
    try {
      const value = await env.NAMESPACE.get("first-key");


      if (value === null) {
        return new Response("値が見つかりません", {status: 404});
      }
      return new Response(value);
    }
    catch (e)
    {
      return new Response(e.message, {status: 500});
    }
  },
};

参照

KVから読み取るために提供されるメソッド：

get()メソッド

特定のキーの値を取得するには、あなたのWorkerコードにバインドされている任意のKV名前空間のget()メソッドを呼び出します：

env.NAMESPACE.get(key, type?, options?);

get()メソッドは、値を取得するためにawaitできるPromiseを返します。キーが見つからない場合、Promiseはリテラル値nullで解決されます。

パラメータ

  • key: string
    • KVペアのキー。
  • type: "text" | "json" | "arrayBuffer" | "stream"
    • オプション。返される値のタイプ。デフォルトはstringです。
  • options: { cacheTtl: number, type: "text" | "json" | "arrayBuffer" | "stream" }
    • オプション。cacheTtlとtypeプロパティを含むオブジェクト。cacheTtlプロパティは、KV結果がアクセスされるグローバルネットワークロケーションにキャッシュされる時間の長さ（秒単位）を定義します（最小：60）。typeプロパティは、返される値のタイプを定義します。

レスポンス

  • response: Promise<string | Object | ArrayBuffer | ReadableStream | null>
    • 要求されたKVペアの値。レスポンスタイプは、get()コマンドに提供されたtypeパラメータに応じて次のようになります：
      • text: string（デフォルト）。
      • json: JSON文字列からデコードされたオブジェクト。
      • arrayBuffer: ArrayBuffer ↗インスタンス。
      • stream: ReadableStream ↗。

get()メソッドは、古い値を返すことがあります。特定のキーが最近特定の場所で読み取られた場合、他の場所で行われたキーへの書き込みや更新は、表示されるまで最大60秒（またはcacheTtlの期間）かかることがあります。

getWithMetadata()メソッド

特定のキーの値とそのメタデータを取得するには、あなたのWorkerコードにバインドされている任意のKV名前空間のgetWithMetadata()メソッドを呼び出します：

env.NAMESPACE.getWithMetadata(key, type?, options?);

メタデータは、各KVエントリに追加するシリアライズ可能な値です。

パラメータ

  • key: string
    • KVペアのキー。
  • type: "text" | "json" | "arrayBuffer" | "stream"
    • オプション。返される値のタイプ。デフォルトはstringです。
  • options: { cacheTtl: number, type: "text" | "json" | "arrayBuffer" | "stream" }
    • オプション。cacheTtlとtypeプロパティを含むオブジェクト。cacheTtlプロパティは、KV結果がアクセスされるグローバルネットワークロケーションにキャッシュされる時間の長さ（秒単位）を定義します（最小：60）。typeプロパティは、返される値のタイプを定義します。

レスポンス

  • response: Promise<{ value: string | Object | ArrayBuffer | ReadableStream | null, metadata: string | null }>

    • 要求されたKVペアの値とメタデータを含むオブジェクト。値属性のタイプは、getWithMetadata()コマンドに提供されたtypeパラメータに応じて次のようになります：
      • text: string（デフォルト）。
      • json: JSON文字列からデコードされたオブジェクト。
      • arrayBuffer: ArrayBuffer ↗インスタンス。
      • stream: ReadableStream ↗。

要求されたキーと値のペアに関連するメタデータがない場合、メタデータにはnullが返されます。

getWithMetadata()メソッドは、古い値を返すことがあります。特定のキーが最近特定の場所で読み取られた場合、他の場所で行われたキーへの書き込みや更新は、表示されるまで最大60秒（またはcacheTtlの期間）かかることがあります。

例

メタデータ付きのキーをWorker内から読み取る例：

export default {
  async fetch(request, env, ctx) {
    try {
      const { value, metadata } = await env.NAMESPACE.getWithMetadata("first-key");


      if (value === null) {
        return new Response("値が見つかりません", {status: 404});
      }
      return new Response(value);
    }
    catch (e)
    {
      return new Response(e.message, {status: 500});
    }
  },
};

ガイダンス

タイプパラメータ

単純な値の場合、デフォルトのtextタイプを使用して、値をstringとして取得します。便利のために、jsonタイプも指定されており、JSON値をオブジェクトに変換してからオブジェクトを返します。大きな値の場合は、streamを使用してReadableStreamを要求します。バイナリ値の場合は、arrayBufferを使用してArrayBufferを要求します。

大きな値の場合、typeの選択はレイテンシーとCPU使用率に顕著な影響を与える可能性があります。参考までに、typeはstream、arrayBuffer、text、jsonの順に速いから遅いに並べることができます。

CacheTtlパラメータ

cacheTtlは、KV結果がアクセスされるグローバルネットワークロケーションにキャッシュされる時間の長さ（秒単位）を定義するパラメータです。

秒単位での時間の長さを定義することは、比較的頻繁に読み取られるキーのコールドリードレイテンシーを減らすのに役立ちます。cacheTtlは、データが一度書き込まれるか、まれに書き込まれる場合に便利です。

データが頻繁に更新され、書き込まれた後すぐに更新を確認する必要がある場合、cacheTtlは推奨されません。なぜなら、他のグローバルネットワークロケーションから行われた書き込みは、キャッシュされた値が期限切れになるまで表示されないからです。

cacheTtlパラメータは、60以上の整数でなければなりません。これがデフォルトです。

すでにキャッシュされたアイテムの有効なcacheTtlは、より低いcacheTtlで再取得することで減少させることができます。たとえば、NAMESPACE.get(key, {cacheTtl: 86400})を実行したが、後で24時間のキャッシュが長すぎることに気づいた場合、NAMESPACE.get(key, {cacheTtl: 300})またはNAMESPACE.get(key)を実行すると、提供されたcacheTtlを尊重して新しいデータを確認します。デフォルトは60秒です。

KVにアクセスする他の方法

コマンドラインからWranglerを使用してキーと値のペアを読み取ることができ、APIからも読み取ることができます。

Cloudflare DashboardDiscordCommunityLearning CenterSupport Portal
Cookie Settings