INTEGRITY Документация

← Cloudflare Workers KV / kv / api

Чтение пар «ключ-значение»

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

// Read individual key
env.NAMESPACE.get(key);

// Read multiple keys
env.NAMESPACE.get(keys);
# Read individual key
self.env.NAMESPACE.get(key)

# Read multiple keys
self.env.NAMESPACE.get(keys)

get() метод возвращает промис, который можно await для получения значения.

Если вы запрашиваете один ключ в виде строки, promise возвращает единственный ответ. Если ключ не найден, promise разрешается со значением null.

Вы также можете запросить массив ключей. Возвращаемое значение будет представлять собой Map найденных пар ключ-значение, причём для не найденных ключей null значения.

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

			// Read multiple keys, returns Map of values
			const values = await env.NAMESPACE.get(["first-key", "second-key"]);

			// Read single key with metadata, returns value or null
			const valueWithMetadata = await env.NAMESPACE.getWithMetadata("first-key");

			// Read multiple keys with metadata, returns Map of values
			const valuesWithMetadata = await env.NAMESPACE.getWithMetadata(["first-key", "second-key"]);

			return new Response({
				value: value,
				values: Object.fromEntries(values),
				valueWithMetadata: valueWithMetadata,
				valuesWithMetadata: Object.fromEntries(valuesWithMetadata)
			});
		} catch (e) {
			return new Response(e.message, { status: 500 });
		}
	},
};
from workers import WorkerEntrypoint, Response

class Default(WorkerEntrypoint):
    async def fetch(self, request):
        try:
            # Read single key, returns value or None
            value = await self.env.NAMESPACE.get("first-key")

            # Read multiple keys, returns dict of values
            values = await self.env.NAMESPACE.get(["first-key", "second-key"])

            # Read single key with metadata
            value_with_metadata = await self.env.NAMESPACE.getWithMetadata("first-key")

            # Read multiple keys with metadata
            values_with_metadata = await self.env.NAMESPACE.getWithMetadata(["first-key", "second-key"])

            return Response.json({
                "value": value,
                "values": values,
                "valueWithMetadata": value_with_metadata,
                "valuesWithMetadata": values_with_metadata,
            })
        except Exception as e:
            return Response(str(e), status=500)

Справочник

Ниже приведены методы для чтения из KV:

get() метод

Используйте get() метод для получения одного значения или нескольких значений, если указано несколько ключей:

Request a single key with get(key: string)

Чтобы получить значение для одного ключа, вызовите get() метод для любого пространства имен KV, привязанного к коду вашего Worker, с помощью:

env.NAMESPACE.get(key, type?);
// OR
env.NAMESPACE.get(key, options?);
self.env.NAMESPACE.get(key, type)
# OR
self.env.NAMESPACE.get(key, options)
Параметры
Ответ

Запрос нескольких ключей с помощью get(keys: string[])

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

env.NAMESPACE.get(keys, type?);
// OR
env.NAMESPACE.get(keys, options?);
self.env.NAMESPACE.get(keys, type)
# OR
self.env.NAMESPACE.get(keys, options)
Параметры
Ответ

Максимальный размер ответа составляет 25 MB. Ответы, которые превышают этот размер, будут завершаться ошибкой 413 Error сообщение об ошибке.

getWithMetadata() метод

Используйте getWithMetadata() метод для получения одного значения вместе с его метаданными или нескольких значений с их метаданными:

Request a single key with getWithMetadata(key: string)

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

env.NAMESPACE.getWithMetadata(key, type?);
// OR
env.NAMESPACE.getWithMetadata(key, options?);
self.env.NAMESPACE.getWithMetadata(key, type)
# OR
self.env.NAMESPACE.getWithMetadata(key, options)

Метаданные представляют собой сериализуемое значение, которое добавляется к каждой записи KV.

Параметры
Ответ

Если с запрошенной парой «ключ-значение» не связаны метаданные, null будет возвращено для metadata.

Запрос нескольких ключей с помощью getWithMetadata(keys: string[])

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

env.NAMESPACE.getWithMetadata(keys, type?);
// OR
env.NAMESPACE.getWithMetadata(keys, options?);
self.env.NAMESPACE.getWithMetadata(keys, type)
# OR
self.env.NAMESPACE.getWithMetadata(keys, options)
Параметры
Ответ

Если с запрошенной парой «ключ-значение» не связаны метаданные, null будет возвращено для metadata.

Максимальный размер ответа составляет 25 MB. Ответы, которые превышают этот размер, будут завершаться ошибкой 413 Error сообщение об ошибке.

Рекомендации

Параметр типа

Для простых значений используйте значение по умолчанию text тип, который предоставляет значение в виде string. Для удобства json также можно указать тип, который преобразует значение JSON в объект, прежде чем вернуть его вам. Для больших значений используйте stream чтобы запросить ReadableStream. Для двоичных значений используйте arrayBuffer чтобы запросить ArrayBuffer.

Для больших значений выбор type может заметно влиять на задержку и использование CPU. Для сравнения, type можно упорядочить от самого быстрого к самому медленному в следующем порядке: stream, arrayBuffer, text, а также json.

Параметр CacheTtl

cacheTtl это параметр, определяющий время в секундах, в течение которого результат KV кэшируется в той точке глобальной сети, из которой к нему обращаются.

Указание времени в секундах помогает снизить задержку холодного чтения для ключей, которые читаются относительно редко. cacheTtl полезен, если ваши данные записываются один раз или изменяются редко.

cacheTtl не рекомендуется, если ваши данные часто обновляются и вам нужно видеть изменения вскоре после записи, поскольку записи, сделанные из других точек глобальной сети, не будут видны, пока не истечёт срок действия кешированного значения.

cacheTtl параметр должен быть целым числом, большим или равным 30. 60 используется по умолчанию. Максимальное значение для cacheTtl это Number.MAX_SAFE_INTEGER ↗.

После того как ключ был прочитан с заданным cacheTtl в регионе, он останется закэшированным в этом регионе до конца cacheTtl или вытеснения из кеша. Это затрагивает региональный и центральный уровни встроенного кеширования KV. При записи в Workers KV регионы регионального и центрального уровней кеширования внутри KV повторно проверяются с учётом только что записанного результата.

Получение большего количества ключей за один вызов Worker с помощью массовых запросов

За один вызов Worker может выполнить не более 1,000 операций к внешним сервисам. Это ограничение распространяется на Workers KV, как описано в Лимиты Workers KV.

Чтобы прочитать более 1000 ключей за одну операцию, можно использовать массовые операции чтения для чтения нескольких ключей за один раз. Такая операция считается одной операцией в рамках лимита в 1000 операций.

Снижение кардинальности за счёт объединения ключей

Если у вас есть набор связанных пар «ключ-значение» со смешанным характером использования (часть ключей «горячие», часть «холодные»), рассмотрите возможность их объединения. Объединяя «холодные» ключи с «горячими», вы добиваетесь того, что «холодные» ключи кешируются вместе с «горячими», а это обеспечивает более быстрое чтение, чем если бы они оставались некешированными по отдельности.

Объединение в «супер» запись KV

Один из способов объединения заключается в том, чтобы сделать все ключи и значения частью единого супер-объекта «ключ-значение». Пример приведён ниже.

key1: value1
key2: value2
key3: value3

становится

coalesced: {
  key1: value1,
  key2: value2,
  key3: value3,
}

Объединение значений позволяет холодным ключам оставаться в кэше благодаря паттернам доступа к более часто запрашиваемым (горячим) ключам.

Это лучше всего подходит, если вы не планируете обновлять значения независимо друг от друга, поскольку это может привести к состоянию гонки.

Другие способы доступа к KV

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