Ler pares chave-valor

Para obter o valor de uma chave específica, chame o método get() na sua instância KV.

Ver como Markdown

Para obter o valor de uma chave específica, chame o método get() na sua instância KV:

// Ler chave individual
const value = await kv.get(key);
// Ler múltiplas chaves
const values = await kv.get(keys);

O método get() retorna uma promise que você pode usar await para obter o valor.

Se você solicitar uma única chave como string, receberá uma única resposta na promise. Se a chave não for encontrada, a promise resolverá com o valor literal null.

Você também pode solicitar um array de chaves. O valor de retorno será um objeto com pares chave-valor, onde chaves não encontradas têm valores null.

async function handleRequest(request) {
const kv = new Azion.KV();
try {
// Ler chave única, retorna valor ou null
const value = await kv.get("primeira-chave", "text");
// Ler múltiplas chaves, retorna objeto com valores
const values = await kv.get(["primeira-chave", "segunda-chave"], "text");
// Ler chave única com metadados
const valueWithMetadata = await kv.getWithMetadata("primeira-chave", "text");
// Ler múltiplas chaves com metadados
const valuesWithMetadata = await kv.getWithMetadata(["primeira-chave", "segunda-chave"], "text");
return new Response(JSON.stringify({
value: value,
values: values,
valueWithMetadata: valueWithMetadata,
valuesWithMetadata: valuesWithMetadata
}), {
headers: { "Content-Type": "application/json" }
});
} catch (e) {
return new Response(e.message, { status: 500 });
}
}
addEventListener("fetch", (event) => {
event.respondWith(handleRequest(event.request));
});

Os métodos get() e getWithMetadata() podem retornar valores desatualizados. Se uma chave foi lida recentemente em uma determinada localização, gravações ou atualizações na chave feitas em outras localizações podem levar até 60 segundos (ou a duração do cacheTtl) para serem exibidas.

Referência

Os seguintes métodos são fornecidos para ler do KV Store:

Método get()

Use o método get() para obter um único valor, ou múltiplos valores se forem fornecidas múltiplas chaves.

Solicitar uma única chave

Para obter o valor de uma única chave, chame o método get() na sua instância KV:

await kv.get(key, type?, options?);
Parâmetros
ParâmetroTipoDescrição
keystringA chave do par KV.
type"text" | "json" | "arrayBuffer" | "stream"Opcional. O tipo do valor a ser retornado. text é o padrão.
options{ cacheTtl?: number }Opcional. Objeto contendo a propriedade cacheTtl.
Opções
OpçãoTipoDescrição
cacheTtlnumberTempo em segundos para armazenar o resultado em cache localmente. O valor mínimo é 60.
Resposta
RespostaTipoDescrição
responsePromise<string | object | ArrayBuffer | ReadableStream | null>O valor para o par KV solicitado, ou null se não encontrado.

O tipo de resposta depende do parâmetro type:

TipoRetorna
"text"Uma string (padrão)
"json"Um objeto decodificado de uma string JSON
"arrayBuffer"Uma instância de ArrayBuffer
"stream"Um ReadableStream

Solicitar múltiplas chaves

Para obter os valores de múltiplas chaves, chame o método get() com um array:

await kv.get(keys, type?);
Parâmetros
ParâmetroTipoDescrição
keysstring[]As chaves dos pares KV.
type"text" | "json"Opcional. O tipo do valor a ser retornado. text é o padrão.
Resposta
RespostaTipoDescrição
responsePromise<object>Um objeto com pares chave-valor. Chaves não encontradas têm valores null.

Método getWithMetadata()

Use o método getWithMetadata() para obter um único valor junto com seus metadados, ou múltiplos valores com seus metadados.

Solicitar uma única chave com metadados

Para obter o valor de uma chave junto com seus metadados:

await kv.getWithMetadata(key, type?, options?);

Metadados são um valor serializável que você anexa a cada entrada KV ao usar put().

Parâmetros
ParâmetroTipoDescrição
keystringA chave do par KV.
type"text" | "json" | "arrayBuffer" | "stream"Opcional. O tipo do valor a ser retornado. text é o padrão.
options{ cacheTtl?: number }Opcional. Objeto contendo a propriedade cacheTtl.
Resposta
RespostaTipoDescrição
responsePromise<{ value: string | object | ArrayBuffer | ReadableStream | null, metadata: object | null }>Um objeto contendo o valor e os metadados.

Se não houver metadados associados ao par chave-valor solicitado, null será retornado para metadata.

Solicitar múltiplas chaves com metadados

Para obter os valores de múltiplas chaves junto com seus metadados:

await kv.getWithMetadata(keys, type?);
Parâmetros
ParâmetroTipoDescrição
keysstring[]As chaves dos pares KV.
type"text" | "json"Opcional. O tipo do valor a ser retornado. text é o padrão.
Resposta
RespostaTipoDescrição
responsePromise<object>Um objeto com chaves mapeadas para objetos { value, metadata }.

Orientações

Parâmetro type

Para valores simples, use o tipo padrão text que fornece seu valor como uma string. Por conveniência, um tipo json também é especificado que converterá um valor JSON em um objeto antes de retorná-lo. Para valores grandes, use stream para solicitar um ReadableStream. Para valores binários, use arrayBuffer para solicitar um ArrayBuffer.

Para valores grandes, a escolha do type pode ter um efeito notável na latência e uso de CPU. Para referência, o type pode ser ordenado do mais rápido ao mais lento como stream, arrayBuffer, text e json.

async function handleRequest(request) {
const kv = new Azion.KV();
// Obter como texto (padrão)
const textValue = await kv.get("minha-chave", "text");
// Obter como JSON (automaticamente parseado)
const jsonValue = await kv.get("minha-chave", "json");
console.log(jsonValue.someProperty);
// Obter como ArrayBuffer
const bufferValue = await kv.get("minha-chave", "arrayBuffer");
const decoder = new TextDecoder("utf-8");
const decodedString = decoder.decode(bufferValue);
// Obter como ReadableStream
const streamValue = await kv.get("minha-chave", "stream");
return new Response(textValue);
}
addEventListener("fetch", (event) => {
event.respondWith(handleRequest(event.request));
});

Parâmetro cacheTtl

cacheTtl é um parâmetro que define o tempo em segundos que um resultado KV é armazenado em cache na localização da rede global onde é acessado.

Definir o tempo em segundos é útil para reduzir a latência de leitura fria em chaves que são lidas com pouca frequência. cacheTtl é útil se seus dados são escritos uma vez ou raramente.

Leituras quentes e frias — Uma leitura quente significa que os dados estão em cache localmente. Uma leitura fria significa que os dados não estão em cache, então devem ser buscados dos armazenamentos centrais. Tanto pares chave-valor existentes quanto pares chave-valor inexistentes (lookups negativos) são armazenados em cache.

cacheTtl não é recomendado se seus dados são atualizados frequentemente e você precisa ver as atualizações logo após serem escritas, porque gravações de outras localizações da rede global não serão visíveis até que o valor em cache expire.

O valor mínimo para cacheTtl é 60 segundos.

// Armazenar o resultado em cache por 5 minutos
const value = await kv.get("chave-config", "json", { cacheTtl: 300 });

Tratando chaves inexistentes

Quando uma chave não existe, get() retorna null:

async function handleRequest(request) {
const kv = new Azion.KV();
const value = await kv.get("chave-inexistente", "text");
if (value === null) {
return new Response("Chave não encontrada", { status: 404 });
}
return new Response(value);
}
addEventListener("fetch", (event) => {
event.respondWith(handleRequest(event.request));
});

Lendo streams

Para valores grandes armazenados como streams, processe os dados incrementalmente:

async function handleRequest(request) {
const kv = new Azion.KV();
const stream = await kv.get("arquivo-grande", "stream");
if (stream instanceof ReadableStream) {
const decoder = new TextDecoder();
let text = "";
for await (const chunk of stream) {
text += decoder.decode(chunk, { stream: true });
}
text += decoder.decode();
console.log(`Recuperados ${text.length} caracteres`);
}
// Ou retorne o stream diretamente na resposta
return new Response(stream);
}
addEventListener("fetch", (event) => {
event.respondWith(handleRequest(event.request));
});

Trabalhando com metadados

Recupere tanto o valor quanto os metadados em uma única chamada:

async function handleRequest(request) {
const kv = new Azion.KV();
const result = await kv.getWithMetadata("perfil-usuario", "json");
console.log("Valor:", result.value);
console.log("Metadados:", result.metadata);
if (result.metadata && result.metadata.version) {
console.log("Versão:", result.metadata.version);
}
return new Response(JSON.stringify(result), {
headers: { "Content-Type": "application/json" }
});
}
addEventListener("fetch", (event) => {
event.respondWith(handleRequest(event.request));
});

Relacionados