INTEGRITY Dokumentace

← Cloudflare Workers KV / kv / api

Čtení párů klíč-hodnota

Chcete-li získat hodnotu pro daný klíč, zavolejte get() metoda v rámci Vazba KV na libovolném KV namespace kterou jste navázali na svůj kód Workeru:

// 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() metoda vrací promise, na který můžete zavolat await k získání hodnoty.

Pokud požádáte o jeden klíč jako řetězec, dostanete v promise jedinou odpověď. Pokud klíč nebude nalezen, promise se vyřeší s literální hodnotou null.

Můžete si také vyžádat pole klíčů. Návratovou hodnotou bude Map nalezených párů klíč-hodnota, přičemž u nenalezených klíčů má null hodnoty.

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)

Referenční informace

Ke čtení z KV slouží následující metody:

get() metoda

Použijte get() metodu k získání jedné hodnoty, nebo více hodnot, pokud zadáte více klíčů:

Vyžádejte jeden klíč pomocí get(key: string)

Chcete-li získat hodnotu pro jediný klíč, zavolejte get() metodu na libovolném KV namespace, který jste navázali na kód svého Workeru pomocí:

env.NAMESPACE.get(key, type?);
// OR
env.NAMESPACE.get(key, options?);
self.env.NAMESPACE.get(key, type)
# OR
self.env.NAMESPACE.get(key, options)
Parametry
Odpověď

Vyžádejte více klíčů pomocí get(keys: string[])

Chcete-li získat hodnoty pro více klíčů, zavolejte get() metodu na libovolném KV namespace, který jste navázali na kód svého Workeru pomocí:

env.NAMESPACE.get(keys, type?);
// OR
env.NAMESPACE.get(keys, options?);
self.env.NAMESPACE.get(keys, type)
# OR
self.env.NAMESPACE.get(keys, options)
Parametry
Odpověď

Limit velikosti odpovědi je 25 MB. Odpovědi nad tuto velikost selžou s chybou 413 Error chybová zpráva.

getWithMetadata() metoda

Použijte getWithMetadata() metodu k získání jedné hodnoty spolu s jejími metadaty, nebo více hodnot s jejich metadaty:

Vyžádejte jeden klíč pomocí getWithMetadata(key: string)

Chcete-li získat hodnotu pro daný klíč spolu s jeho metadaty, zavolejte getWithMetadata() metodu na libovolném KV namespace, který jste navázali na kód svého Workeru:

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

Metadata jsou serializovatelná hodnota, kterou připojíte k každé položce KV.

Parametry
Odpověď

Pokud k požadovanému páru klíč-hodnota neexistují žádná metadata, null bude vráceno pro metadata.

Vyžádejte více klíčů pomocí getWithMetadata(keys: string[])

Chcete-li získat hodnoty pro danou sadu klíčů spolu s jejich metadaty, zavolejte getWithMetadata() metodu na libovolném KV namespace, který jste navázali na kód svého Workeru pomocí:

env.NAMESPACE.getWithMetadata(keys, type?);
// OR
env.NAMESPACE.getWithMetadata(keys, options?);
self.env.NAMESPACE.getWithMetadata(keys, type)
# OR
self.env.NAMESPACE.getWithMetadata(keys, options)
Parametry
Odpověď

Pokud k požadovanému páru klíč-hodnota neexistují žádná metadata, null bude vráceno pro metadata.

Limit velikosti odpovědi je 25 MB. Odpovědi nad tuto velikost selžou s chybou 413 Error chybová zpráva.

Pokyny

Parametr typu

U jednoduchých hodnot použijte výchozí text typ, který vám poskytne vaši hodnotu jako string. Pro pohodlí json je také zadán, což převede hodnotu JSON na objekt ještě před tím, než vám tento objekt vrátí. Pro velké hodnoty použijte stream k vyžádání ReadableStream. Pro binární hodnoty použijte arrayBuffer k vyžádání ArrayBuffer.

U velkých hodnot záleží na volbě type může mít znatelný vliv na latenci a využití CPU. Pro srovnání, type lze seřadit od nejrychlejšího po nejpomalejší takto: stream, arrayBuffer, text, a json.

Parametr CacheTtl

cacheTtl je parametr, který určuje, jak dlouho (v sekundách) zůstává výsledek KV uložen v mezipaměti v tom místě globální sítě, odkud k němu přistupujete.

Nastavení délky doby v sekundách pomáhá snižovat latenci studeného čtení u klíčů, které se čtou poměrně zřídka. cacheTtl je užitečné, pokud svá data zapisujete jen jednou nebo jen zřídka.

cacheTtl se nedoporučuje, pokud svá data často aktualizujete a potřebujete vidět změny krátce po zápisu, protože zápisy provedené z jiných míst globální sítě nebudou viditelné, dokud nevyprší platnost hodnoty uložené v cache.

cacheTtl parametr musí být celé číslo větší nebo rovné 30. 60 je výchozí hodnota. Maximální hodnota pro cacheTtl je Number.MAX_SAFE_INTEGER ↗.

Jakmile je klíč jednou přečten se zadanou hodnotou cacheTtl v daném regionu zůstane v mezipaměti tohoto regionu až do konce cacheTtl nebo vyřazením z cache. To se týká regionální i centrální vrstvy vestavěného cachování KV. Při zápisu do Workers KV se regiony v regionální a centrální cachovací vrstvě uvnitř KV znovu ověří vůči nově zapsanému výsledku.

Získávání více klíčů na jedno volání Workeru pomocí hromadných požadavků

Workers jsou omezeni na 1,000 operací vůči externím službám na jedno volání. To platí i pro Workers KV, jak je popsáno v Limity Workers KV.

Chcete-li v rámci jedné operace přečíst více než 1,000 klíčů, můžete použít hromadné operace čtení, které umožňují načíst více klíčů najednou. Do limitu 1,000 operací se tyto počítají jako jedna operace.

Snížení kardinality slučováním klíčů

Pokud máte skupinu souvisejících párů klíč-hodnota se smíšeným vzorem využití (některé klíče jsou horké, jiné chladné), zvažte jejich sloučení. Sloučením chladných klíčů s horkými klíči se chladné klíče uloží do mezipaměti společně s horkými, což může zajistit rychlejší čtení, než kdyby zůstaly nekešované jako samostatné klíče.

Slučování do „super“ položky KV

Jednou z technik slučování je zahrnout všechny klíče a hodnoty do jednoho super objektu klíč-hodnota. Příklad je uveden níže.

key1: value1
key2: value2
key3: value3

se změní na

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

Sloučením hodnot těží studené klíče z toho, že zůstávají v cache zahřáté díky vzorcům přístupu k teplejším klíčům.

Nejlépe to funguje, pokud neočekáváte potřebu aktualizovat hodnoty nezávisle na sobě, což může vést k souběhu (race condition).

Další způsoby přístupu ke KV

Můžete číst páry klíč-hodnota v příkazovém řádku pomocí Wrangler a z REST API.