--- name: azion-use-kv-store-com-cliente-compativel-com-redis description: >- 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. --- # Use KV Store com cliente compatível com Redis A biblioteca `azion` expõe um cliente similar a Redis para o [KV Store](/pt-br/documentacao/plataforma/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. > **Atenção** > > O export `azion/kv` que este guia usa não está presente no pacote `azion` publicado, então o import desta página não resolve hoje. A interface que funciona é o `Azion.KV`, um global do runtime alcançado de dentro de uma função sem linha de import. Para ela, consulte [Cliente KV](/pt-br/documentacao/devtools/runtime/api-reference/kv-store/). --- ## Pré-requisitos - Uma conta Azion. Para criar uma, consulte [Como criar uma conta na Azion](/pt-br/documentacao/fundamentos/criar-uma-conta/). - Um namespace do KV Store. Ele é criado pela API da Azion; consulte [Namespaces](/pt-br/documentacao/plataforma/kv-store/namespaces/). - Node.js 18 ou posterior, ou um runtime JavaScript compatível. --- ## Instale a biblioteca ```bash 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 import { createClient } from 'azion/kv'; const client = await createClient() .on('error', (err) => console.error('KV Client Error:', err)) .connect(); ``` ### Opções do cliente ```typescript const client = await createClient({ namespace: 'my-namespace', apiToken: 'my-token', }) .on('error', (err) => console.error('KV Error:', err)) .connect(); ``` | Opção | Tipo | Descrição | | ----------- | ------ | ------------------------------------------------------ | | `namespace` | string | O namespace do KV Store que o cliente endereça | | `apiToken` | string | Um token de API da Azion, exigido pelo provider de API | --- ## Armazene um value `set` grava um value, com expiração e metadata opcionais: ```typescript // Um value simples await client.set('user:123', 'John Doe'); // Com expiração de 10 segundos await client.set('session:abc', 'session-data', { expiration: { type: 'EX', value: 10, }, }); // Com metadata await client.set('config:theme', 'dark', { metadata: { updatedBy: 'admin', version: 1 }, }); // Com os dois 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 | Tipo | Descrição | | ------ | ----------------------------------- | | `EX` | Tempo de expiração em segundos | | `PX` | Tempo de expiração em milissegundos | | `EXAT` | Timestamp Unix em segundos | | `PXAT` | Timestamp Unix em milissegundos | --- ## Leia um value `get` retorna o value, ou `null` quando o namespace não guarda essa key: ```typescript const value = await client.get('user:123'); console.log(value); // 'John Doe' // Uma key que não existe retorna null const missing = await client.get('non-existent'); console.log(missing); // null ``` ### Leia um value com o metadata dele `getWithMetadata` retorna o value e o metadata gravado junto com ele: ```typescript const result = await client.getWithMetadata('config:theme'); console.log(result.value); // 'dark' console.log(result.metadata); // { updatedBy: 'admin', version: 1 } ``` --- ## Exclua uma key `delete` remove uma key, e `del` é um alias dele: ```typescript await client.delete('user:123'); // ou await 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 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'); // O alias em maiúsculas await client.HSET('user:profile:123', 'status', 'active'); ``` ### hGetAll Retorna todos os campos e values de um hash: ```typescript const profile = await client.hGetAll('user:profile:123'); console.log(profile); // { name: 'John Doe', email: 'john@example.com', role: 'admin', status: 'active' } const data = await client.HGETALL('user:profile:123'); ``` ### hVals Retorna todos os values de um hash, sem os nomes dos campos: ```typescript const values = await client.hVals('user:profile:123'); console.log(values); // ['John Doe', 'john@example.com', 'admin', 'active'] const 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 const providerType = client.getProviderType(); console.log(providerType); // 'native' ou 'api' ``` --- ## Trate os erros O cliente informa falhas por um evento `error`: ```typescript const client = await createClient() .on('error', (err) => { console.error('KV Error:', err.message); // Repita, use um fallback ou exponha a falha }) .connect(); ``` Uma operação isolada também é envolvida em `try`/`catch`: ```typescript try { await client.set('key', 'value'); } catch (error) { console.error('Failed to set value:', error); } ``` --- ## Feche a conexão Feche o cliente quando o trabalho terminar: ```typescript await client.disconnect(); // ou await client.quit(); ``` --- ## Exemplo completo As operações acima, compostas em uma execução: ```typescript import { createClient } from 'azion/kv'; async function main() { const client = await createClient({ namespace: 'my-app', }) .on('error', (err) => console.error('KV Error:', err)) .connect(); try { // Armazena os 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() }, }); // Armazena um perfil como hash await client.hSet('profile:1', 'theme', 'dark'); await client.hSet('profile:1', 'language', 'en'); await client.hSet('profile:1', 'notifications', 'true'); // Lê os dados do usuário de volta const userData = await client.get('user:1'); console.log('User:', JSON.parse(userData)); // Lê com o metadata const result = await client.getWithMetadata('user:1'); console.log('Created at:', result.metadata.created); // Lê todos os campos do perfil const profile = await client.hGetAll('profile:1'); console.log('Profile:', profile); // Remove a key await client.delete('user:1'); } finally { await client.disconnect(); } } main().catch(console.error); ``` --- ## Correspondência com os métodos do Redis | Comando Redis | Método do cliente | Descrição | | ------------- | --------------------------------------- | -------------------------- | | `GET` | `get(key)` | Lê um value | | `SET` | `set(key, value, options?)` | Grava um value | | `DEL` | `delete(key)` / `del(key)` | Remove uma key | | `HSET` | `hSet(key, field, value)` / `HSET(...)` | Grava um campo de hash | | `HGETALL` | `hGetAll(key)` / `HGETALL(key)` | Lê todos os campos de hash | | `HVALS` | `hVals(key)` / `HVALS(key)` | Lê todos os values de hash | --- ## Próximos passos - [Cliente KV](/pt-br/documentacao/devtools/runtime/api-reference/kv-store.md): A interface Azion.KV que uma função usa, com cada método e opção. - [Gerencie dados de chave-valor em uma função](/pt-br/documentacao/guias/desenvolvimento-de-aplicacoes/dados/gerenciar-com-funcoes.md): Armazene, leia e exclua dados de dentro de uma função. - [Namespaces](/pt-br/documentacao/plataforma/kv-store/namespaces.md): Crie o namespace que este cliente endereça, pela API da Azion. - [KV Store](/pt-br/documentacao/plataforma/kv-store.md): O que o produto é, suas duas interfaces e onde ele para.