← Cloudflare Workers KV / kv / api

Výpis klíčů

Chcete-li vypsat všechny klíče ve svém jmenném prostoru KV, zavolejte list() metoda v rámci Vazba KV na libovolném KV namespace kterou jste navázali na svůj kód Workeru:

env.NAMESPACE.list();

await self.env.NAMESPACE.list()

list() metoda vrací promise, na který můžete zavolat await k získání hodnoty.

Příklad výpisu klíčů z Workeru:

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)

K výpisu klíčů v KV slouží následující metoda:

• list()

Chcete-li vypsat všechny klíče ve svém jmenném prostoru KV, zavolejte list() metoda v rámci Vazba KV na libovolném KV namespace, který jste navázali na kód svého Workeru:

env.NAMESPACE.list(options?)

self.env.NAMESPACE.list(options)

• options: { prefix?: string, limit?: string, cursor?: string }
  • Objekt s atributy prefix (volitelné), limit (volitelné), nebo cursor (volitelné).
    • prefix je string která představuje prefix, pomocí kterého můžete filtrovat všechny klíče.
    • limit je maximální počet vrácených klíčů. Výchozí hodnota je 1,000 klíčů, což je zároveň maximum. Je nepravděpodobné, že byste tuto výchozí hodnotu chtěli měnit, ale je zde uvedena pro úplnost.
    • cursor je string používaný pro stránkování odpovědí.

• response: Promise<{ keys: { name: string, expiration?: number, metadata?: object }[], list_complete: boolean, cursor: string }>
  • A Promise který se rozřeší objektem obsahujícím keys, list_complete, a cursor atributy.
    • keys je pole, které obsahuje objekt pro každý uvedený klíč. Každý objekt má atributy name, expiration (volitelné), a metadata (volitelné). Pokud má daný pár klíč-hodnota nastavenou platnost, bude uvedena v absolutní podobě (i v případě, že byla zadána ve formě TTL). Pokud má pár klíč-hodnota nastavená nenulová metadata, budou tato metadata uvedena.
    • list_complete je boolean, který bude false pokud je třeba načíst další klíče, i když keys pole je prázdné.
    • cursor je string používaný pro stránkování odpovědí.

list() metoda vrací promise, který se rozřeší objektem, jenž vypadá následovně:

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

keys vlastnost bude obsahovat pole objektů popisujících jednotlivé klíče. Tento objekt bude mít jeden až tři vlastní klíče: name klíče a volitelně jeho expiration a metadata hodnoty.

name je string, expiration hodnota je číslo a metadata odpovídá typu, který byl nastaven na začátku. expiration hodnota bude vrácena pouze v případě, že má klíč nastavenou expiraci, a to ve formě absolutní hodnoty, i když byla nastavena ve formě TTL. Jakýkoli metadata bude vrácena pouze tehdy, pokud má daný klíč přiřazená metadata s hodnotou jinou než null.

Pokud list_complete je false, je k dispozici více klíčů k načtení, i když keys pole je prázdné. Použijete cursor vlastnost k získání dalších klíčů. Viz Stránkování pro další podrobnosti.

Zvažte uložení hodnot do metadat, pokud se vaše hodnoty vejdou do limit velikosti metadat. Ukládání hodnot do metadat je efektivnější než list() následované get() na klíč. Při použití put(), nechte value parametr prázdný a místo toho zahrňte vlastnost do objektu metadata:

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

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

Změny se mohou projevit až za 60 sekund (nebo za hodnotu nastavenou pomocí cacheTtl get() nebo getWithMetadata() metody) se projeví v aplikaci, která tuto metodu na KV namespace volá.

Vypište všechny klíče začínající určitým prefixem.

Klíče můžete například strukturovat pomocí uživatele, ID uživatele a názvu klíče, oddělených dvojtečkami (například user:1:<key>). Klíče pro uživatele číslo jedna byste získali pomocí následujícího kódu:

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"]))

Tím se vrátí všechny klíče začínající na "user:1:" prefix.

Klíče se vždy vracejí v lexikografickém pořadí podle svých bajtů UTF-8.

Pokud je k načtení ještě více klíčů, list_complete klíč bude nastaven na false a cursor bude také vrácen. V takovém případě můžete zavolat list() znovu s cursor hodnotu, abyste získali další dávku klíčů:

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)

Kontrola prázdného pole v keys nestačí k určení, zda existují další klíče k načtení. Použijte místo toho list_complete.

Je možné mít prázdné pole v keys, ale ještě máte další klíče k načtení, protože nedávno vypršelé nebo odstraněné klíče ↗ musí projít iterací, ale nebude součástí vrácených dat keys.

Pokud chcete zrušit stránkování velké sady výsledků a zároveň zadat prefix argument, prefix argument musí být uveden ve všech následujících voláních spolu s počátečními argumenty.

Zvažte uložení hodnot do metadat, pokud se vaše hodnoty vejdou do limit velikosti metadat. Ukládání hodnot do metadat je efektivnější než list() následované get() na klíč. Při použití put(), nechte value parametr prázdný a místo toho zahrňte vlastnost do objektu metadata:

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

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

Můžete také vypsat klíče v příkazovém řádku pomocí Wrangler nebo pomocí REST API.