キーのリスト

KV 名前空間内のすべてのキーをリストするには、Worker コードにバインドした任意の KV 名前空間の KV バインディングの list() メソッドを呼び出します:

env.NAMESPACE.list();

list() メソッドは、値を取得するために await できる Promise を返します。

例

Worker 内からキーをリストする例:

export default {
  async fetch(request, env, ctx) {
    try {
      const value = await env.NAMESPACE.list();

      return new Response(JSON.stringify(value.keys), {
        status: 200
      });
    }
    catch (e)
    {
      return new Response(e.message, {status: 500});
    }
  },
};

参照

KV のキーをリストするために提供されるメソッド:

list()

`list()` メソッド

env.NAMESPACE.list(options?)

パラメータ

options: { prefix?: string, limit?: string, cursor?: string }
- prefix（オプション）、limit（オプション）、または cursor（オプション）という属性を持つオブジェクト。
  - prefix は、すべてのキーをフィルタリングするために使用できるプレフィックスを表す string です。
  - limit は、返されるキーの最大数です。デフォルトは 1,000 で、これが最大です。このデフォルトを変更したいとは考えにくいですが、完全性のために含まれています。
  - cursor は、レスポンスのページネーションに使用される string です。

レスポンス

response: Promise<{ keys: { name: string, expiration?: number, metadata?: object }[], list_complete: boolean, cursor: string }>
- keys、list_complete、および cursor 属性を含むオブジェクトに解決される Promise です。
  - keys は、リストされた各キーのオブジェクトを含む配列です。各オブジェクトには、name、expiration（オプション）、および metadata（オプション）という属性があります。キーと値のペアに有効期限が設定されている場合、有効期限は存在し、絶対値形式で返されます（TTL 形式で設定されていても）。キーと値のペアに非 null のメタデータが設定されている場合、メタデータは存在します。
  - list_complete はブール値で、keys 配列が空であっても、取得するキーがまだある場合は false になります。
  - cursor は、レスポンスのページネーションに使用される string です。

list() メソッドは、次のようなオブジェクトで解決される Promise を返します:

{
  "keys": [
    {
      "name": "foo",
      "expiration": 1234,
      "metadata": { "someMetadataKey": "someMetadataValue" }
    }
  ],
  "list_complete": false,
  "cursor": "6Ck1la0VxJ0djhidm1MdX2FyD"
}

keys プロパティには、各キーを説明するオブジェクトの配列が含まれます。そのオブジェクトには、キーの name と、オプションでキーの expiration および metadata 値が含まれます。

name は string で、expiration 値は数値で、metadata は最初に設定された任意の型です。expiration 値は、キーに有効期限が設定されている場合のみ返され、絶対値形式で返されます（TTL 形式で設定されていても）。metadata は、指定されたキーに非 null の関連メタデータがある場合のみ返されます。

list_complete が false の場合、取得するキーがまだあり、keys 配列が空であっても、さらに取得する必要があります。cursor プロパティを使用して、さらにキーを取得します。詳細についてはページネーションを参照してください。

値が metadata-size limit に収まる場合は、メタデータに値を保存することを検討してください。メタデータに値を保存する方が、各キーに対して list() の後に get() を行うよりも効率的です。put() を使用する際は、value パラメータを空にし、代わりにメタデータオブジェクトにプロパティを含めます:

await NAMESPACE.put(key, "", {
  metadata: { value: value },
});

変更は、KV 名前空間でメソッドを呼び出すアプリケーションに反映されるまで最大 60 秒（または get() または getWithMetadata() メソッドの cacheTtl で設定された値）かかる場合があります。

ガイダンス

プレフィックスによるリスト

特定のプレフィックスで始まるすべてのキーをリストします。

たとえば、ユーザー、ユーザー ID、およびコロンで区切られたキー名で構造化されたキーがある場合（例: user:1:<key>）、次のコードを使用してユーザー番号 1 のキーを取得できます:

export default {
  async fetch(request, env, ctx) {
    const value = await env.NAMESPACE.list({ prefix: "user:1:" });
    return new Response(value.keys);
  },
};

これにより、"user:1:" プレフィックスで始まるすべてのキーが返されます。

順序

キーは常に UTF-8 バイトに従って辞書式順序で返されます。

ページネーション

取得するキーがさらにある場合、list_complete キーは false に設定され、cursor も返されます。この場合、次のバッチのキーを取得するために cursor 値を使用して再度 list() を呼び出すことができます:

const value = await NAMESPACE.list();

const cursor = value.cursor;

const next_value = await NAMESPACE.list({ cursor: cursor });

keys に空の配列があるかどうかを確認するだけでは、さらに取得するキーがあるかどうかを判断するには不十分です。代わりに list_complete を使用してください。

keys に空の配列がある場合でも、さらに取得するキーがある可能性があります。これは、最近期限切れまたは削除されたキー ↗を反復処理する必要があるためですが、返される keys には含まれません。

大きな結果セットのページネーションを行う際に prefix 引数を提供する場合、すべての後続の呼び出しで prefix 引数を初期引数とともに提供する必要があります。

`list()` 操作のメタデータによるストレージの最適化

await NAMESPACE.put(key, "", {
  metadata: { value: value },
});

KV へのアクセスのための他のメソッド

コマンドラインで Wrangler を使用してキーをリストすることも、API を使用してリストすることもできます。

Cloudflare Dashboard Discord Community Learning Center Support Portal

Cookie Settings