ContatoSign in

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));
});

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.

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