Use KV Store com cliente compatível com Redis

Alcance o KV Store por uma interface de cliente similar a Redis, com as operações set, get, delete e de hash mapeadas na biblioteca da Azion.

Última atualização

Ver como Markdown Configurar agente

A biblioteca azion expõe um cliente similar a Redis para o KV Store, então uma aplicação já escrita em cima de padrões do Redis mantém a forma das suas chamadas. Este guia cobre o cliente, suas opções, as operações que ele carrega e como cada uma corresponde ao comando Redis que ela substitui.

Pré-requisitos

  • Uma conta Azion. Para criar uma, consulte Como criar uma conta na Azion.
  • Um namespace do KV Store. Ele é criado pela API da Azion; consulte Namespaces.
  • Node.js 18 ou posterior, ou um runtime JavaScript compatível.

Instale a biblioteca

npm install azion

Crie um cliente

O cliente segue um padrão similar a Redis, com métodos encadeáveis e uma etapa de conexão:

TypeScript
01import { createClient } from 'azion/kv';
02
03const client = await createClient()
04 .on('error', (err) => console.error('KV Client Error:', err))
05 .connect();

Opções do cliente

TypeScript
01const client = await createClient({
02 namespace: 'my-namespace',
03 apiToken: 'my-token',
04})
05 .on('error', (err) => console.error('KV Error:', err))
06 .connect();
OpçãoTipoDescrição
namespacestringO namespace do KV Store que o cliente endereça
apiTokenstringUm token de API da Azion, exigido pelo provider de API

Armazene um value

set grava um value, com expiração e metadata opcionais:

TypeScript
01// Um value simples
02await client.set('user:123', 'John Doe');
03
04// Com expiração de 10 segundos
05await client.set('session:abc', 'session-data', {
06 expiration: {
07 type: 'EX',
08 value: 10,
09 },
10});
11
12// Com metadata
13await client.set('config:theme', 'dark', {
14 metadata: {
15 updatedBy: 'admin',
16 version: 1
17 },
18});
19
20// Com os dois
21await client.set('cache:api-response', JSON.stringify(data), {
22 expiration: {
23 type: 'EX',
24 value: 300, // 5 minutos
25 },
26 metadata: {
27 source: 'external-api',
28 cached_at: Date.now()
29 },
30});

Tipos de expiração

TipoDescrição
EXTempo de expiração em segundos
PXTempo de expiração em milissegundos
EXATTimestamp Unix em segundos
PXATTimestamp Unix em milissegundos

Leia um value

get retorna o value, ou null quando o namespace não guarda essa key:

TypeScript
01const value = await client.get('user:123');
02console.log(value); // 'John Doe'
03
04// Uma key que não existe retorna null
05const missing = await client.get('non-existent');
06console.log(missing); // null

Leia um value com o metadata dele

getWithMetadata retorna o value e o metadata gravado junto com ele:

TypeScript
01const result = await client.getWithMetadata('config:theme');
02console.log(result.value); // 'dark'
03console.log(result.metadata); // { updatedBy: 'admin', version: 1 }

Exclua uma key

delete remove uma key, e del é um alias dele:

TypeScript
01await client.delete('user:123');
02// ou
03await client.del('user:123');

Operações de hash

O cliente carrega operações de hash compatíveis com Redis para pares campo-value sob uma mesma key. Cada uma tem um alias em maiúsculas.

hSet

Grava um campo de um hash:

TypeScript
01await client.hSet('user:profile:123', 'name', 'John Doe');
02await client.hSet('user:profile:123', 'email', 'john@example.com');
03await client.hSet('user:profile:123', 'role', 'admin');
04
05// O alias em maiúsculas
06await client.HSET('user:profile:123', 'status', 'active');

hGetAll

Retorna todos os campos e values de um hash:

TypeScript
01const profile = await client.hGetAll('user:profile:123');
02console.log(profile);
03// { name: 'John Doe', email: 'john@example.com', role: 'admin', status: 'active' }
04
05const data = await client.HGETALL('user:profile:123');

hVals

Retorna todos os values de um hash, sem os nomes dos campos:

TypeScript
01const values = await client.hVals('user:profile:123');
02console.log(values);
03// ['John Doe', 'john@example.com', 'admin', 'active']
04
05const vals = await client.HVALS('user:profile:123');

Detecção de provider

O cliente detecta o runtime em que está executando e seleciona um provider:

  • Provider native: selecionado dentro do Azion Runtime, onde uma função executa.
  • Provider API: selecionado fora da Azion, em desenvolvimento local ou em um servidor externo.

getProviderType informa qual dos dois está em uso:

TypeScript
01const providerType = client.getProviderType();
02console.log(providerType); // 'native' ou 'api'

Trate os erros

O cliente informa falhas por um evento error:

TypeScript
01const client = await createClient()
02 .on('error', (err) => {
03 console.error('KV Error:', err.message);
04 // Repita, use um fallback ou exponha a falha
05 })
06 .connect();

Uma operação isolada também é envolvida em try/catch:

TypeScript
01try {
02 await client.set('key', 'value');
03} catch (error) {
04 console.error('Failed to set value:', error);
05}

Feche a conexão

Feche o cliente quando o trabalho terminar:

TypeScript
01await client.disconnect();
02// ou
03await client.quit();

Exemplo completo

As operações acima, compostas em uma execução:

TypeScript
01import { createClient } from 'azion/kv';
02
03async function main() {
04 const client = await createClient({
05 namespace: 'my-app',
06 })
07 .on('error', (err) => console.error('KV Error:', err))
08 .connect();
09
10 try {
11 // Armazena os dados do usuário
12 await client.set('user:1', JSON.stringify({ name: 'Alice', age: 30 }), {
13 expiration: { type: 'EX', value: 3600 }, // 1 hora
14 metadata: { created: Date.now() },
15 });
16
17 // Armazena um perfil como hash
18 await client.hSet('profile:1', 'theme', 'dark');
19 await client.hSet('profile:1', 'language', 'en');
20 await client.hSet('profile:1', 'notifications', 'true');
21
22 // Lê os dados do usuário de volta
23 const userData = await client.get('user:1');
24 console.log('User:', JSON.parse(userData));
25
26 // Lê com o metadata
27 const result = await client.getWithMetadata('user:1');
28 console.log('Created at:', result.metadata.created);
29
30 // Lê todos os campos do perfil
31 const profile = await client.hGetAll('profile:1');
32 console.log('Profile:', profile);
33
34 // Remove a key
35 await client.delete('user:1');
36
37 } finally {
38 await client.disconnect();
39 }
40}
41
42main().catch(console.error);

Correspondência com os métodos do Redis

Comando RedisMétodo do clienteDescrição
GETget(key)Lê um value
SETset(key, value, options?)Grava um value
DELdelete(key) / del(key)Remove uma key
HSEThSet(key, field, value) / HSET(...)Grava um campo de hash
HGETALLhGetAll(key) / HGETALL(key)Lê todos os campos de hash
HVALShVals(key) / HVALS(key)Lê todos os values de hash

Próximos passos

Cliente KVA interface Azion.KV que uma função usa, com cada método e opção.Gerencie dados de chave-valor em uma funçãoArmazene, leia e exclua dados de dentro de uma função.NamespacesCrie o namespace que este cliente endereça, pela API da Azion.KV StoreO que o produto é, suas duas interfaces e onde ele para.