← Cloudflare Workers KV / kv / api

Список ключей

Чтобы получить список всех ключей в вашем пространстве имён KV, вызовите list() метод объекта Привязка KV для любого Пространство имён KV привязанных к коду вашего Worker:

env.NAMESPACE.list();

await self.env.NAMESPACE.list()

list() метод возвращает промис, который можно 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, вызовите list() метод объекта Привязка KV для любого пространства имен KV, привязанного к коду вашего Worker:

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 }>
  • A Promise который разрешается объектом, содержащим keys, list_complete, а также cursor атрибуты.
    • keys является массивом, который содержит объект для каждого перечисленного ключа. Каждый объект имеет атрибуты name, expiration (необязательно), и metadata (необязательно). Если для пары ключ-значение задан срок действия (expiration), он будет указан в абсолютном формате, даже если был задан в виде TTL. Если у пары ключ-значение заданы метаданные (metadata) с непустым значением, они будут присутствовать в ответе.
    • list_complete это булево значение, которое будет false если есть ещё ключи для получения, даже если keys массив пуст.
    • cursor это string используемый для постраничной разбивки ответов.

list() метод возвращает промис, который разрешается объектом следующего вида:

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

keys свойство будет содержать массив объектов, описывающих каждый ключ. Такой объект будет иметь от одного до трёх собственных ключей: name ключа, а при необходимости и expiration и metadata значения.

name это string, expiration является числовым значением, и metadata имеет тот же тип, который был задан изначально. expiration значение возвращается только в том случае, если у ключа есть срок действия, и оно будет представлено в абсолютной форме, даже если было задано в форме TTL. Любое metadata возвращается только в том случае, если с указанным ключом связаны metadata, отличные от null.

Если list_complete это false, есть ещё ключи для получения, даже если keys массив пуст. Вы будете использовать cursor свойство, чтобы получить больше ключей. См. Пагинация для дополнительных сведений.

Подумайте о хранении значений в метаданных, если они умещаются в ограничение на размер метаданных. Хранение значений в metadata более эффективно, чем list() с последующим get() на ключ. При использовании put(), оставьте value параметр пустым и вместо этого укажите свойство в объекте метаданных:

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

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

Изменения могут становиться видимыми в течение 60 секунд (или значения, заданного с помощью cacheTtl из get() или getWithMetadata() метод) отразились в приложении, вызывающем метод для пространства имен 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 также будет возвращено. В этом случае можно вызвать list() ещё раз с cursor для получения следующей партии ключей:

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 аргумент необходимо передавать во всех последующих вызовах вместе с исходными аргументами.

Подумайте о хранении значений в метаданных, если они умещаются в ограничение на размер метаданных. Хранение значений в metadata более эффективно, чем list() с последующим get() на ключ. При использовании put(), оставьте value параметр пустым и вместо этого укажите свойство в объекте метаданных:

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

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

Вы также можете получение списка ключей в командной строке с помощью Wrangler или с помощью REST API.