ContatoSign in

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:

Terminal window
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