Хранилище KV

KV (от key-value, «ключ — значение») — быстрое хранилище, где под строковым ключом лежит строка. Оно встроено в функции и доступно им по имени, без строк подключения.

KV для простого «положил — прочитал»: кеш, сессии, настройки, счётчики просмотров. Для таблиц и связей между записями оно не годится — берите базу D1.

Объявление

Пространство KV объявляется в wrangler.jsonc в списке kv_namespaces:

{
  "kv_namespaces": [
    { "binding": "CACHE", "id": "cache" }
  ]
}

• binding — имя переменной, под которой хранилище видно в коде: env.CACHE.
• id — имя, которое вы указываете в командах CLI.

Пространств может быть несколько — например, отдельные для кеша и для настроек.

Чтение и запись из кода

export default {
  async fetch(request, env) {
    const url = new URL(request.url);

    // Записать (третий аргумент — опции, например срок жизни в секундах)
    if (url.pathname === "/set") {
      const key = url.searchParams.get("key");
      const value = url.searchParams.get("value") ?? "1";
      await env.CACHE.put(key, value, { expirationTtl: 60 });
      return Response.json({ ok: true });
    }

    // Прочитать
    if (url.pathname === "/get") {
      const key = url.searchParams.get("key");
      const value = await env.CACHE.get(key);
      return Response.json({ key, value });
    }

    // Удалить
    if (url.pathname === "/delete") {
      const key = url.searchParams.get("key");
      await env.CACHE.delete(key);
      return Response.json({ ok: true });
    }

    // Список ключей
    const { keys } = await env.CACHE.list();
    return Response.json(keys);
  },
};

Основные методы:

• get(key) — значение по ключу или null, если ключа нет.
• put(key, value, options?) — записать. В options можно задать expirationTtl (срок жизни в секундах) или expiration (Unix-время истечения в секундах). Без опций ключ живёт бессрочно.
• delete(key) — удалить ключ.
• list() — перечень ключей ({ keys, list_complete, cursor }).

Значение — строка. Чтобы положить объект, сериализуйте его сами, например JSON.stringify(...), и разберите обратно через JSON.parse.

Массовый импорт

Набор ключей заливается одной командой из JSON-файла формата Wrangler. Каждая строка — объект с полем key и полем value:

[
  { "key": "greeting", "value": "привет" },
  { "key": "plan", "value": "pro" },
  { "key": "logo", "value": "<base64>", "base64": true },
  { "key": "offer", "value": "скидка", "expiration": 1730000000 }
]

• key — ключ, value — значение (строка).
• base64: true — значение закодировано в base64; так заливают двоичные данные.
• expiration — Unix-время в секундах, когда ключ истекает. Без него ключ бессрочный.

Файл должен лежать внутри каталога проекта и попадать в архив (не исключаться .gitignore). Команда — из каталога проекта:

webshield apps kv import --app api CACHE seed/keys.json

CACHE здесь — это id пространства из конфига. Импорт добавляет или обновляет ключи: существующие перезаписываются новыми значениями.

Массовое удаление

Удалить список ключей — тем же форматом, только с полем key:

[
  { "key": "greeting" },
  { "key": "plan" }
]

webshield apps kv delete-keys --app api CACHE old-keys.json

Тонкости

• Функция должна быть уже выкачена — команды выполняются на её узлах, рядом с хранилищем.
• Импорт и удаление повторяются сами, если связь с функцией оборвалась: запись и удаление по ключу безопасно выполнить дважды.
• История и вывод операций — во вкладке Данные.
• Возврат к моменту возвращает и KV: вкладка Данные → Вернуть данные к моменту. Подробнее — в Функциях.