列出键

要列出 KV 命名空间中的所有键，请在已绑定到 Worker 代码的任何 KV 命名空间 的 KV 绑定（binding） 上调用 list() 方法：

env.NAMESPACE.list();

await self.env.NAMESPACE.list()

list() 方法返回一个 promise，你可以 await 以获取值。

从 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});
    }
  },
};

from workers import WorkerEntrypoint, Response

class Default(WorkerEntrypoint):
    async def fetch(self, request):
        try:
            value = await self.env.NAMESPACE.list()

            return Response.json(value["keys"])
        except Exception as e:
            return Response(str(e), status=500)

KV 提供以下方法用于列出键：

• list()

要列出 KV 命名空间中的所有键，请在已绑定到 Worker 代码的任何 KV 命名空间的 KV 绑定（binding） 上调用 list() 方法：

env.NAMESPACE.list(options?)

self.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 是布尔值，如果还有更多键要获取则为 false，即使 keys 数组为空。
    • 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 形式设置也会以绝对值形式返回。仅当给定键有关联的非 null 元数据时才会返回任何 metadata。

如果 list_complete 为 false，则还有更多键要获取，即使 keys 数组为空。你将使用 cursor 属性获取更多键。有关更多详情，请参阅分页。

如果你的值适合元数据大小限制，请考虑将值存储在元数据中。将值存储在元数据中比 list() 后每个键执行 get() 更高效。使用 put() 时，将 value 参数留空，改为在 metadata 对象中包含属性：

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

await self.env.NAMESPACE.put(key, "", metadata={"value": value})

更改可能需要最多 60 秒（或使用 get() 或 getWithMetadata() 方法的 cacheTtl 设置的值）才能在调用 KV 命名空间方法的应用中反映。

列出以特定前缀开头的所有键。

例如，你可能已将键结构化为用户、用户 ID 和键名，以冒号分隔（如 user:1:<key>）。你可以使用以下代码获取用户编号一的键：

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

from workers import WorkerEntrypoint, Response

class Default(WorkerEntrypoint):
    async def fetch(self, request):
        value = await self.env.NAMESPACE.list(prefix="user:1:")
        return Response(str(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 });

value = await self.env.NAMESPACE.list()

cursor = value.get("cursor")

next_value = await self.env.NAMESPACE.list(cursor=cursor)

检查 keys 中的空数组不足以确定是否还有更多键要获取。相反，请使用 list_complete。

keys 中可能为空数组，但仍有更多键要获取，因为最近过期或删除的键 ↗必须迭代但不会包含在返回的 keys 中。

在对大型结果集进行去分页同时提供 prefix 参数时，必须在所有后续调用中连同初始参数一起提供 prefix 参数。

如果你的值适合元数据大小限制，请考虑将值存储在元数据中。将值存储在元数据中比 list() 后每个键执行 get() 更高效。使用 put() 时，将 value 参数留空，改为在 metadata 对象中包含属性：

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

await self.env.NAMESPACE.put(key, "", metadata={"value": value})

你也可以使用 Wrangler 在命令行列出键，或使用 REST API。