KV 名前空間内のすべてのキーを一覧するには、Worker コードにバインドした任意の KV 名前空間 に対して、KV バインディング の list() メソッドを呼び出します。
env.NAMESPACE.list();await self.env.NAMESPACE.list()list() メソッドは Promise を返します。値を取得するには 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 のキーを一覧するには、次のメソッドを使います。
KV 名前空間内のすべてのキーを一覧するには、Worker コードにバインドした任意の KV 名前空間で list() メソッドを呼び出します。
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 }>keys、list_complete、cursor属性を含むオブジェクトに解決するPromiseです。keysは、一覧したキーごとのオブジェクトを含む配列です。各オブジェクトにはname、expiration（省略可）、metadata（省略可）属性があります。キーと値のペアに有効期限が設定されている場合、有効期限は絶対値形式で含まれます（TTL 形式で設定した場合も同じです）。キーと値のペアに null でないメタデータが設定されている場合、メタデータが含まれます。list_completeはブール値です。keys配列が空でも、まだ取得するキーがある場合はfalseになります。cursorは、レスポンスをページ分割するために使うstringです。
list() メソッドは Promise を返します。解決すると、次のようなオブジェクトになります。
{
"keys": [
{
"name": "foo",
"expiration": 1234,
"metadata": { "someMetadataKey": "someMetadataValue" }
}
],
"list_complete": false,
"cursor": "6Ck1la0VxJ0djhidm1MdX2FyD"
}keys プロパティには、各キーを表すオブジェクトの配列が含まれます。そのオブジェクトには、キーの name と、省略可能な expiration および metadata の、1〜3 個のキーがあります。
name は string、expiration は数値、metadata は最初に設定した型です。expiration は、キーに有効期限がある場合にだけ返り、TTL 形式で設定しても絶対値形式になります。metadata は、そのキーに null でないメタデータがある場合にだけ返ります。
list_complete が false の場合、keys 配列が空でも、まだ取得するキーがあります。続きのキーを取得するには cursor プロパティを使います。詳細は ページネーション を参照してください。
値が メタデータのサイズ上限 に収まる場合は、値をメタデータに保存することを検討してください。メタデータに値を保存するほうが、list() のあとにキーごとに get() するより効率的です。put() を使うときは、value パラメーターを空にして、代わりにメタデータオブジェクトにプロパティを含めます。
await NAMESPACE.put(key, "", {
metadata: { value: value },
});await self.env.NAMESPACE.put(key, "", metadata={"value": value})このメソッドを KV 名前空間に対して呼び出しているアプリケーションへ反映されるまで、最大 60 秒（または get() / getWithMetadata() メソッドの cacheTtl の値）かかることがあります。
特定のプレフィックスで始まるキーをすべて一覧します。
たとえば、ユーザー、ユーザー ID、キー名をコロンで区切った構造（user:1:<key> など）にしている場合があります。次のコードで、ユーザー 1 のキーを取得できます。
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 も返ります。この場合、cursor の値を渡してもう一度 list() を呼び出すと、次のキーのバッチを取得できます。
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 引数を渡す必要があります。
値が メタデータのサイズ上限 に収まる場合は、値をメタデータに保存することを検討してください。メタデータに値を保存するほうが、list() のあとにキーごとに get() するより効率的です。put() を使うときは、value パラメーターを空にして、代わりにメタデータオブジェクトにプロパティを含めます。
await NAMESPACE.put(key, "", {
metadata: { value: value },
});await self.env.NAMESPACE.put(key, "", metadata={"value": value})Wrangler のコマンドラインからキーを一覧する 方法と、REST API 経由でキーを一覧する 方法もあります。