# Primeiros passos com KV Store Este guia orienta você a armazenar e ler a sua primeira key no [KV Store](/pt-br/documentacao/plataforma/kv-store/). No fim, você vai ter: - O seu primeiro namespace, criado pela API da Azion. - Uma function que abre o namespace, grava uma key e a lê de volta. - Uma instância da function e uma regra do Rules Engine que executam essa function. - Uma URI na sua própria aplicação que responde com o valor armazenado. O **namespace** é o container em que KV Store guarda keys e values, e ele é permanente: não pode ser renomeado, esvaziado nem excluído depois, então vale escolher o nome antes da primeira requisição. A **function** guarda o código que abre o namespace e chama o cliente. A **instância da function** liga a function a uma aplicação, e a regra do **Rules Engine** seleciona essa instância e define quais requisições a executam. Criar uma function não a executa, e uma instância sem regra nunca é executada. --- Selecione a interface que você vai usar. Os pré-requisitos e todas as etapas abaixo seguem essa escolha. ## Pré-requisitos - Uma conta Azion. Para criar uma, consulte [Como criar uma conta na Azion](/pt-br/documentacao/fundamentos/criar-uma-conta/). - Acesso ao Preview do KV Store na conta. O produto está em Preview, e o acesso é solicitado ao time de suporte técnico. Para solicitá-lo, consulte [Technical Support](/pt-br/documentacao/suporte/). - As permissões **Edit Functions** e **Edit Applications** na conta. Elas concedem permissão para criar a function e para alterar a aplicação que a executa. Para mais informações, consulte [Teams Permissions](/pt-br/documentacao/fundamentos/teams-permissions/). - Uma aplicação. Para criar uma, consulte [Primeiros passos com Applications](/pt-br/documentacao/plataforma/applications/primeiros-passos/). - Um [personal token](/pt-br/documentacao/guias/plataforma/conta-e-billing/personal-tokens/) e o `curl`. Você cria o namespace pela Azion API qualquer que seja a interface escolhida, e a requisição envia o token no cabeçalho `Authorization`. **Console** - Acesso ao Azion Console. Para entrar, consulte [Como acessar o Azion Console](/pt-br/documentacao/guias/plataforma/conta-e-billing/como-acessar-o-azion-console/). **CLI** - A [Azion CLI](/pt-br/documentacao/devtools/cli/) instalada e autorizada. **API** - Nada além do personal token e do `curl` acima. --- ## Crie um namespace Um namespace é criado pela API da Azion, porque KV Store não tem tela no Azion Console nem comando na Azion CLI. Todo leitor segue este único procedimento, qualquer que seja a interface usada nas etapas seguintes. O nome tem de 3 a 63 caracteres, e usa letras, números, o hífen e o underscore. Os nomes diferenciam maiúsculas de minúsculas, e nada remove um namespace depois que ele existe, então um nome criado na caixa errada é permanente. 1. **Envie a requisição de criação** Substitua `[TOKEN VALUE]` pelo seu personal token, e `my-namespace` por um nome seu: ```bash curl --request POST \ --url https://api.azion.com/v4/workspace/kv/namespaces \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' \ --header 'Content-Type: application/json' \ --data '{ "name": "my-namespace" }' ``` 2. **Leia a resposta** Um `201` carrega o namespace inteiro: ```json { "name": "my-namespace", "created_at": "2026-01-01T12:14:07.563343", "last_modified": "2026-01-01T12:14:07.563343" } ``` Um `400` com a mensagem `Namespace already exists` significa que a conta já tem esse nome. Escolha um nome diferente e envie a requisição de novo. A requisição é síncrona, e não há estado de provisionamento a consultar. O `name` que a resposta carrega é o identificador que toda chamada seguinte usa, inclusive a function que você escreve a seguir. Para todos os campos, operações e erros desse endpoint, consulte [Namespaces](/pt-br/documentacao/plataforma/kv-store/namespaces/). --- ## Crie a function `Azion.KV` é um global do Azion Runtime, então uma [function](/pt-br/documentacao/plataforma/functions/) o alcança sem linha de import e sem credencial. A function abaixo abre o namespace, grava uma key, a lê de volta e retorna o valor. > **Atenção** > > Uma chamada a `Azion.KV.open()` pode responder `NotFound: KV namespace "my-namespace" does not exist` para um namespace que existe e que a API da Azion lista. Isso pode acontecer em uma conta com acesso ao Preview do KV Store. Se a sua function retornar esse erro, entre em contato com o time de [Technical Support](/pt-br/documentacao/suporte/) com o nome do namespace e a conta a que ele pertence. **Console** Para criar a function pelo Azion Console: 1. **Abra a página Functions** Acesse [Azion Console](https://console.azion.com/) > **Products Menu** > **Libraries** > **Functions**. 2. **Selecione + Function** 3. **Nomeie a function** Insira um nome para a function. Por exemplo: `kv-quickstart`. 4. **Cole o código na aba Code** Na aba **Code**, cole o código a seguir, com o nome do namespace que você criou: ```javascript export default { async fetch(request, env, ctx) { const kv = await Azion.KV.open('my-namespace'); await kv.put('user-42', 'active'); const value = await kv.get('user-42', 'text'); return new Response(value ?? 'No value for that key'); }, }; ``` 5. **Selecione Save** A function é salva e guarda o código que alcança o namespace. **CLI** A CLI lê o código de um arquivo local. Para criar a function: 1. **Salve o código em um arquivo** Escreva o código a seguir em `kv-quickstart.js`, com o nome do namespace que você criou: ```javascript export default { async fetch(request, env, ctx) { const kv = await Azion.KV.open('my-namespace'); await kv.put('user-42', 'active'); const value = await kv.get('user-42', 'text'); return new Response(value ?? 'No value for that key'); }, }; ``` 2. **Execute o comando de criação** ```bash azion create function --name kv-quickstart --code ./kv-quickstart.js --active true ``` 3. **Leia a saída** O comando imprime o id da nova function: ```text Created function with ID 12346 ``` Registre o id. A instância referencia a function por ele. **API** O body da requisição carrega o código como uma string JSON. O código usa aspas simples, então o body é enviado a partir de um arquivo. 1. **Escreva o body da requisição em um arquivo** Salve o conteúdo a seguir como `function.json`, com o nome do namespace que você criou: ```json { "name": "kv-quickstart", "code": "export default {\n async fetch(request, env, ctx) {\n const kv = await Azion.KV.open('my-namespace');\n\n await kv.put('user-42', 'active');\n const value = await kv.get('user-42', 'text');\n\n return new Response(value ?? 'No value for that key');\n },\n};" } ``` 2. **Envie a requisição de criação** ```bash curl --request POST \ --url https://api.azion.com/v4/workspace/functions \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' \ --header 'Content-Type: application/json' \ --data @function.json ``` 3. **Leia a resposta** Um `202` carrega a function: ```json { "state": "pending", "data": { "id": 12345, "name": "kv-quickstart", "last_editor": "user@example.com", "last_modified": "2026-01-01T12:00:00.385220Z", "product_version": "2.0", "active": true, "runtime": "azion_js", "execution_environment": "application", "reference_count": 0 } } ``` Registre o `id`. A instância referencia a function por ele. A function ainda não é executada: a etapa seguinte a liga a uma aplicação e adiciona a regra que a aciona. Para todos os métodos que o cliente carrega, consulte [Cliente KV](/pt-br/documentacao/devtools/runtime/api-reference/kv-store/). --- ## Instancie a function e adicione a regra Uma instância liga a function a uma aplicação, e uma regra decide quais requisições executam a instância. Esta regra a executa em requisições para `/kv-quickstart`. **Console** Para configurar as duas pelo Azion Console: 1. **Abra a aplicação que executa a function** Ainda no Azion Console, vá para **Products Menu** > **Build** > **Applications**, e então selecione a sua aplicação. 2. **Na aba Main Settings, ative o módulo Functions** 3. **Selecione Save** 4. **Vá para a aba Functions Instances** 5. **Selecione + Function Instance** 6. **Nomeie a instância** Insira um nome para a instância. Por exemplo: `kv-quickstart instance`. 7. **Selecione a function kv-quickstart** 8. **Selecione Save** 9. **Vá para a aba Rules Engine** 10. **Selecione + Rule** 11. **Nomeie a regra** Insira um nome para a regra. Por exemplo: `Run kv-quickstart`. 12. **Selecione Request Phase** 13. **Defina os critérios** Na seção **Criteria**, selecione a variável `${uri}` e o operador *is equal*, e insira `/kv-quickstart` como argumento. 14. **Na seção Behaviors, selecione Run Function** 15. **Selecione a instância que você criou** 16. **Selecione Save** A regra executa a instância em toda requisição cuja URI é `/kv-quickstart`. **CLI** Para configurar as duas com a Azion CLI, substitua o id da aplicação e o id da function pelos seus: 1. **Ative o módulo Functions** ```bash azion update application --application-id --functions true ``` 2. **Crie a instância** ```bash azion create function-instance --application-id --function-id --name "kv-quickstart instance" ``` O comando imprime o id da nova instância: ```text Created Function Instance with ID 12348 ``` 3. **Escreva a regra em um arquivo** Salve o conteúdo a seguir como `rule.json`, com o id da sua instância em `attributes.value`: ```json { "name": "Run kv-quickstart", "description": "Run the function on /kv-quickstart", "active": true, "criteria": [ [ { "conditional": "if", "variable": "${uri}", "operator": "is_equal", "argument": "/kv-quickstart" } ] ], "behaviors": [ { "type": "run_function", "attributes": { "value": 12348 } } ] } ``` 4. **Crie a regra** ```bash azion create rules-engine --application-id --phase request --file rule.json ``` O comando imprime o id da nova regra: ```text Created Rules Engine with ID 234568 ``` A regra executa a instância em toda requisição cuja URI é `/kv-quickstart`. **API** Três requisições ativam o módulo, criam a instância e adicionam a regra. 1. **Ative o módulo Functions** Substitua `` pelo [ID da sua aplicação](/pt-br/documentacao/guias/desenvolvimento-de-aplicacoes/primeiros-passos/definir-configuracoes-principais/): ```bash curl --request PATCH \ --url https://api.azion.com/v4/workspace/applications/ \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' \ --header 'Content-Type: application/json' \ --data '{ "modules": { "functions": { "enabled": true } } }' ``` 2. **Crie a instância** Substitua `` pelo `id` que a criação da function retornou: ```bash curl --request POST \ --url https://api.azion.com/v4/workspace/applications//functions \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' \ --header 'Content-Type: application/json' \ --data '{ "name": "kv-quickstart instance", "function": , "args": {}, "active": true }' ``` Um `202` carrega a instância, e `data.id` é o valor que a regra seleciona. 3. **Escreva a regra em um arquivo** Os critérios carregam `${uri}`, que um shell expande, então o body é enviado a partir de um arquivo. Salve o conteúdo a seguir como `rule.json`, com o id da sua instância em `attributes.value`: ```json { "name": "Run kv-quickstart", "description": "Run the function on /kv-quickstart", "active": true, "criteria": [ [ { "conditional": "if", "variable": "${uri}", "operator": "is_equal", "argument": "/kv-quickstart" } ] ], "behaviors": [ { "type": "run_function", "attributes": { "value": 12347 } } ] } ``` 4. **Crie a regra** ```bash curl --request POST \ --url https://api.azion.com/v4/workspace/applications//request_rules \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' \ --header 'Content-Type: application/json' \ --data @rule.json ``` Um `202` carrega a regra e o `order` que ela ocupa entre as regras da aplicação. A regra executa a instância em toda requisição cuja URI é `/kv-quickstart`. Regras novas podem levar alguns minutos para propagar. Espere antes de requisitar a URI. Para cada campo de instância e de regra que este guia não detalha, consulte [Primeiros passos com Functions](/pt-br/documentacao/plataforma/functions/primeiros-passos/). --- ## Requisite a URI A sua aplicação responde no domínio dela. Para alcançar a function, requisite a URI correspondente à regra: ```bash curl https:///kv-quickstart ``` Uma resposta bem-sucedida carrega o corpo que a function retorna, que é o valor que ela armazenou sob `user-42` e leu de volta: a string `active`. Uma resposta que carrega `No value for that key` significa que a leitura retornou `null`, ou seja, a key não foi encontrada sob esse nome. O seu primeiro namespace guarda uma key, e uma function a grava e a lê em toda requisição correspondente à regra. --- ## Próximos passos - [Cliente KV](/pt-br/documentacao/devtools/runtime/api-reference/kv-store.md): Todos os métodos que uma function chama contra um namespace, com os tipos de retorno e as opções que cada um aceita. - [Namespaces](/pt-br/documentacao/plataforma/kv-store/namespaces.md): Os campos que um namespace carrega, as três operações de API sobre ele e o erro que cada recusa retorna. - [Como o KV Store funciona](/pt-br/documentacao/plataforma/kv-store/como-funciona.md): Onde uma escrita chega, e de onde uma leitura é atendida. - [Boas práticas](/pt-br/documentacao/plataforma/kv-store/boas-praticas.md): Como modelar uma key, e a convenção de nomes por trás de um nome que não pode ser alterado.