Como usar KV Store com SDK compatível com Redis

Aprenda como usar o SDK Azion KV com uma interface similar ao Redis para integração simplificada com suas aplicações.

Ver como Markdown

O SDK Azion KV fornece uma interface de cliente similar ao Redis para interagir com o KV Store. Isso facilita a migração de aplicações existentes que usam padrões Redis e proporciona uma experiência familiar para desenvolvedores.

Ir para referência do KV Store

Requisitos

Antes de começar, certifique-se de ter:

  • Uma conta Azion.
  • Um namespace do KV Store criado via Console ou API.
  • Node.js 18+ ou um runtime JavaScript compatível.

Instalando o SDK

Instale o SDK da Azion usando npm:

npm install azion

Criando um cliente

O SDK usa um padrão de cliente similar ao Redis com métodos encadeáveis:

import { createClient } from 'azion/kv';
// Criar e conectar um cliente
const client = await createClient()
.on('error', (err) => console.error('Erro do Cliente KV:', err))
.connect();

Opções do cliente

Você pode personalizar o cliente com opções:

const client = await createClient({
namespace: 'meu-namespace',
apiToken: 'meu-token',
})
.on('error', (err) => console.error('Erro KV:', err))
.connect();
OpçãoTipoDescrição
namespacestringO namespace do KV Store a ser usado
apiTokenstringSeu token da API Azion (obrigatório para provider API)

Armazenando dados

Use o método set para armazenar valores:

// Set simples
await client.set('user:123', 'John Doe');
// Set com expiração (10 segundos)
await client.set('session:abc', 'dados-sessao', {
expiration: {
type: 'EX',
value: 10,
},
});
// Set com metadados
await client.set('config:theme', 'dark', {
metadata: {
updatedBy: 'admin',
version: 1
},
});
// Set com expiração e metadados
await client.set('cache:api-response', JSON.stringify(data), {
expiration: {
type: 'EX',
value: 300, // 5 minutos
},
metadata: {
source: 'external-api',
cached_at: Date.now()
},
});

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

Recuperando dados

Use o método get para recuperar valores:

// Get simples
const value = await client.get('user:123');
console.log(value); // 'John Doe'
// Retorna null se a chave não existir
const missing = await client.get('inexistente');
console.log(missing); // null

Recuperando com metadados

Use getWithMetadata para obter tanto o valor quanto seus metadados:

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

Excluindo dados

Use delete ou del para remover chaves:

await client.delete('user:123');
// ou
await client.del('user:123');

Operações de hash

O SDK fornece operações de hash compatíveis com Redis para trabalhar com pares campo-valor:

hSet / HSET

Armazena um par campo-valor:

await client.hSet('user:profile:123', 'name', 'John Doe');
await client.hSet('user:profile:123', 'email', 'john@example.com');
await client.hSet('user:profile:123', 'role', 'admin');
// Alias em maiúsculas também disponível
await client.HSET('user:profile:123', 'status', 'active');

hGetAll / HGETALL

Obtém todos os campos e valores:

const profile = await client.hGetAll('user:profile:123');
console.log(profile);
// { name: 'John Doe', email: 'john@example.com', role: 'admin', status: 'active' }
// Alias em maiúsculas
const data = await client.HGETALL('user:profile:123');

hVals / HVALS

Obtém todos os valores (sem os nomes dos campos):

const values = await client.hVals('user:profile:123');
console.log(values);
// ['John Doe', 'john@example.com', 'admin', 'active']
// Alias em maiúsculas
const vals = await client.HVALS('user:profile:123');

Detecção de provider

O SDK detecta automaticamente o ambiente de execução e seleciona o provider apropriado:

  • Provider nativo: Usado quando executando dentro do runtime de Functions da Azion
  • Provider API: Usado quando executando fora da Azion (desenvolvimento local, servidores externos)

Você pode verificar qual provider está sendo usado:

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

Tratamento de erros

O SDK usa um padrão de tratamento de erros baseado em eventos:

const client = await createClient()
.on('error', (err) => {
console.error('Erro KV:', err.message);
// Tratar erro (retry, fallback, etc.)
})
.connect();

Você também pode usar try-catch para operações individuais:

try {
await client.set('key', 'value');
} catch (error) {
console.error('Falha ao definir valor:', error);
}

Desconectando

Sempre desconecte quando terminar:

await client.disconnect();
// ou
await client.quit();

Exemplo completo

Aqui está um exemplo completo mostrando operações comuns:

import { createClient } from 'azion/kv';
async function main() {
// Criar e conectar cliente
const client = await createClient({
namespace: 'minha-app',
})
.on('error', (err) => console.error('Erro KV:', err))
.connect();
try {
// Armazenar dados do usuário
await client.set('user:1', JSON.stringify({ name: 'Alice', age: 30 }), {
expiration: { type: 'EX', value: 3600 }, // 1 hora
metadata: { created: Date.now() },
});
// Armazenar perfil do usuário usando operações de hash
await client.hSet('profile:1', 'theme', 'dark');
await client.hSet('profile:1', 'language', 'pt-br');
await client.hSet('profile:1', 'notifications', 'true');
// Recuperar dados do usuário
const userData = await client.get('user:1');
console.log('Usuário:', JSON.parse(userData));
// Recuperar com metadados
const result = await client.getWithMetadata('user:1');
console.log('Criado em:', result.metadata.created);
// Obter todas as configurações do perfil
const profile = await client.hGetAll('profile:1');
console.log('Perfil:', profile);
// Limpar
await client.delete('user:1');
} finally {
await client.disconnect();
}
}
main().catch(console.error);

Mapeamento de métodos Redis

Comando RedisMétodo SDKDescrição
GETget(key)Obtém um valor
SETset(key, value, options?)Define um valor
DELdelete(key) / del(key)Exclui uma chave
HSEThSet(key, field, value) / HSET(...)Define campo de hash
HGETALLhGetAll(key) / HGETALL(key)Obtém todos os campos do hash
HVALShVals(key) / HVALS(key)Obtém todos os valores do hash

Próximos passos