Gerencie dados de chave-valor em uma função

Armazene, leia e exclua keys em um namespace do KV Store a partir de uma função, com metadata, valores binários, streams e vários namespaces.

Última atualização

Ver como Markdown Configurar agente

Você armazena, lê e exclui keys em um namespace do KV Store a partir de uma função, com o cliente Azion.KV. Todos os exemplos desta página abrem o namespace com await Azion.KV.open(name): o construtor é privado e não existe namespace padrão.

Criar o namespace em si é uma tarefa da Azion API, e uma função não faz isso. Para mais informações, consulte Namespaces.

Pré-requisitos

Crie a função

O cliente é um global do Azion Runtime, portanto o código o alcança sem linha de import e sem credencial. Para criar a função que contém um dos exemplos abaixo:

Abra a página Functions

Acesse Azion Console > Products Menu > Libraries > Functions.

Selecione + Function
Nomeie a função

Insira um nome para a função. Por exemplo: kv-store-handler.

Cole o código na aba Code

Na aba Code, substitua o código de exemplo por um dos exemplos desta página e substitua my-namespace pelo seu namespace.

Selecione Save

A função é salva. Ela responde a uma requisição assim que uma regra do Rules Engine executa sua instância na aplicação.

Armazene um valor

put cria uma key e substitui o value de uma key que já existe, portanto uma única chamada cobre os dois casos. Uma string é armazenada como está, um objeto é serializado em JSON e um terceiro argumento carrega metadata e um prazo de expiração. Para armazenar três keys em uma invocação:

JavaScript
01export default {
02 async fetch(request, env, ctx) {
03 const kv = await Azion.KV.open('my-namespace');
04
05 await kv.put('greeting', 'Hello, World!');
06
07 // Um objeto é serializado em JSON, portanto não precisa de chamada stringify.
08 await kv.put('user-preferences', {
09 theme: 'dark',
10 language: 'en',
11 notifications: true,
12 });
13
14 // metadata viaja junto do value; expirationTtl expira a key após 3600 segundos.
15 await kv.put('session-token', 'abc123xyz', {
16 metadata: { userId: 'user-42' },
17 expirationTtl: 3600,
18 });
19
20 return new Response('Values stored', { status: 201 });
21 },
22};

O handler grava três keys e responde 201. Para todas as opções que put aceita, consulte Cliente KV.

Leia um valor

get lê uma key e retorna o value no tipo que seu segundo argumento nomeia, que por padrão é text. Uma key que o namespace não contém retorna null, portanto o handler verifica esse caso em vez de capturar um erro. Para ler uma string, um objeto e uma key que pode estar ausente:

JavaScript
01export default {
02 async fetch(request, env, ctx) {
03 const kv = await Azion.KV.open('my-namespace');
04
05 const greeting = await kv.get('greeting', 'text');
06 const preferences = await kv.get('user-preferences', 'json');
07
08 if (greeting === null) {
09 return new Response('Key not found', { status: 404 });
10 }
11
12 return new Response(JSON.stringify({ greeting, preferences }), {
13 headers: { 'Content-Type': 'application/json' },
14 status: 200,
15 });
16 },
17};

O handler responde 404 quando greeting está ausente e, caso contrário, retorna os dois valores em um único corpo JSON. Uma key que o namespace não guarda cai no ramo do null em vez de lançar um erro, e é por isso que a verificação é um teste de igualdade e não um try.

Leia várias keys de uma vez

Um array como primeiro argumento de get lê várias keys em uma chamada e retorna um objeto simples indexado pelo nome da key. Uma key que o namespace não contém aparece nesse objeto com o value null. Para gravar três keys e ler quatro:

JavaScript
01export default {
02 async fetch(request, env, ctx) {
03 const kv = await Azion.KV.open('my-namespace');
04
05 await kv.put('user-1', 'Alice');
06 await kv.put('user-2', 'Bob');
07 await kv.put('user-3', 'Charlie');
08
09 const users = await kv.get(['user-1', 'user-2', 'user-3', 'user-4'], 'text');
10
11 // { "user-1": "Alice", "user-2": "Bob", "user-3": "Charlie", "user-4": null }
12
13 return new Response(JSON.stringify(users), {
14 headers: { 'Content-Type': 'application/json' },
15 status: 200,
16 });
17 },
18};

As três gravações endereçam três keys diferentes, e user-4 retorna como null porque o namespace não guarda nenhuma key com esse nome. A forma de array aceita somente text e json: qualquer outro tipo de retorno lança INVALID_MULTIPLE_GET_RETURN_TYPE.

Leia um valor com seu metadata

getWithMetadata retorna um objeto que carrega value e metadata, portanto uma única chamada lê os dois. O metadata é o que a gravação passou na opção metadata. Para armazenar uma key com metadata e ler o par de volta:

JavaScript
01export default {
02 async fetch(request, env, ctx) {
03 const kv = await Azion.KV.open('my-namespace');
04
05 await kv.put('session', 'active-session-data', {
06 metadata: {
07 createdAt: new Date().toISOString(),
08 userId: 'user-42',
09 },
10 });
11
12 const result = await kv.getWithMetadata('session', 'text');
13
14 return new Response(JSON.stringify(result), {
15 headers: { 'Content-Type': 'application/json' },
16 status: 200,
17 });
18 },
19};

O handler retorna result.value e result.metadata no mesmo corpo da resposta.

Exclua uma key

delete remove uma key e não aceita a forma de array, portanto várias keys são removidas com uma chamada cada. Uma leitura antes da exclusão informa ao handler quais das keys o namespace contém. Para excluir duas keys e responder 404 quando ele não contém nenhuma das duas:

JavaScript
01export default {
02 async fetch(request, env, ctx) {
03 const kv = await Azion.KV.open('my-namespace');
04 const keys = ['session-token', 'session-token-2'];
05
06 try {
07 const found = await kv.get(keys, 'text');
08 const present = keys.filter((key) => found[key] !== null);
09
10 if (present.length === 0) {
11 return new Response('Key not found', { status: 404 });
12 }
13
14 await Promise.all(present.map((key) => kv.delete(key)));
15
16 return new Response(`Deleted ${present.length} keys`, { status: 200 });
17 } catch (error) {
18 return new Response(error.message, { status: 500 });
19 }
20 },
21};

O handler responde 200 com o número de keys que removeu, 404 quando o namespace não contém nenhuma das duas keys e 500 carregando a mensagem de uma chamada que foi rejeitada.

Armazene e leia dados binários

put aceita um ArrayBuffer, e arrayBuffer como tipo de retorno de get lê os bytes de volta. TextEncoder e TextDecoder convertem entre uma string e esse buffer. Para armazenar uma string como bytes e decodificá-la na saída:

JavaScript
01export default {
02 async fetch(request, env, ctx) {
03 const kv = await Azion.KV.open('my-namespace');
04
05 const binaryData = new TextEncoder().encode('Binary content here').buffer;
06 await kv.put('binary-key', binaryData);
07
08 const retrieved = await kv.get('binary-key', 'arrayBuffer');
09 const decoded = new TextDecoder('utf-8').decode(retrieved);
10
11 return new Response(decoded, {
12 headers: { 'Content-Type': 'text/plain' },
13 status: 200,
14 });
15 },
16};

O handler retorna a string decodificada, que é o texto que a gravação codificou.

Leia um valor como stream

stream como tipo de retorno devolve um ReadableStream em vez do value montado, portanto um value grande chega à resposta sem que o handler o retenha. Uma key ausente ainda retorna null, portanto o handler verifica antes de construir a resposta. Para passar um value diretamente para o corpo da resposta:

JavaScript
01export default {
02 async fetch(request, env, ctx) {
03 const kv = await Azion.KV.open('my-namespace');
04
05 const stream = await kv.get('large-content', 'stream');
06
07 if (stream === null) {
08 return new Response('Key not found', { status: 404 });
09 }
10
11 return new Response(stream, {
12 headers: { 'Content-Type': 'application/octet-stream' },
13 status: 200,
14 });
15 },
16};

O handler responde 404 quando a key está ausente e, caso contrário, transmite o value como corpo da resposta.

Use um namespace específico

Azion.KV.open vincula um cliente ao namespace que ele nomeia, portanto uma função que alcança dois namespaces abre dois clientes. O mesmo nome de key em dois namespaces endereça dois valores separados. Para gravar e ler uma key em cada um de dois namespaces:

JavaScript
01export default {
02 async fetch(request, env, ctx) {
03 const productionKv = await Azion.KV.open('production-data');
04 const stagingKv = await Azion.KV.open('staging-data');
05
06 await productionKv.put('config', 'production-value');
07 await stagingKv.put('config', 'staging-value');
08
09 const production = await productionKv.get('config', 'text');
10 const staging = await stagingKv.get('config', 'text');
11
12 return new Response(JSON.stringify({ production, staging }), {
13 headers: { 'Content-Type': 'application/json' },
14 status: 200,
15 });
16 },
17};

Cada key config pertence ao seu próprio namespace, portanto nenhuma das gravações sobrescreve a outra. Um nome que não pertence a nenhum namespace da conta lança NotFound: KV namespace "staging-data" does not exist.

Próximos passos

Cliente KVTodos os métodos, opções, tipos de retorno e erros do cliente Azion.KV.NamespacesCrie, liste e recupere um namespace pela Azion API.Boas práticasAs recomendações a seguir antes da primeira key entrar.Solução de problemasO que uma chamada do KV Store reporta quando falha e o que fazer a respeito.