Primeiros passos com KV Store

Crie o seu primeiro namespace com a API da Azion, depois armazene e leia uma key em uma function executada em uma aplicação.

Última atualização

Ver como Markdown Configurar agente

Este guia orienta você a armazenar e ler a sua primeira key no 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.
  • 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.
  • 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.
  • Uma aplicação. Para criar uma, consulte Primeiros passos com Applications.
  • Um personal token 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.
  • 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.

Envie a requisição de criação

Substitua [TOKEN VALUE] pelo seu personal token, e my-namespace por um nome seu:

Shell
01curl --request POST \
02 --url https://api.azion.com/v4/workspace/kv/namespaces \
03 --header 'Accept: application/json' \
04 --header 'Authorization: Token [TOKEN VALUE]' \
05 --header 'Content-Type: application/json' \
06 --data {
07 "name": "my-namespace"
08}
Leia a resposta

Um 201 carrega o namespace inteiro:

JSON
01{
02 "name": "my-namespace",
03 "created_at": "2026-01-01T12:14:07.563343",
04 "last_modified": "2026-01-01T12:14:07.563343"
05}

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.

Crie a function

Azion.KV é um global do Azion Runtime, então uma function 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.

Para criar a function pelo Azion Console:

Abra a página Functions

Acesse Azion Console > Products Menu > Libraries > Functions.

Selecione + Function
Nomeie a function

Insira um nome para a function. Por exemplo: kv-quickstart.

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
01export default {
02 async fetch(request, env, ctx) {
03 const kv = await Azion.KV.open('my-namespace');
04
05 await kv.put('user-42', 'active');
06 const value = await kv.get('user-42', 'text');
07
08 return new Response(value ?? 'No value for that key');
09 },
10};
Selecione Save

A function é salva e guarda o código que alcança o namespace.

A CLI lê o código de um arquivo local. Para criar a function:

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
01export default {
02 async fetch(request, env, ctx) {
03 const kv = await Azion.KV.open('my-namespace');
04
05 await kv.put('user-42', 'active');
06 const value = await kv.get('user-42', 'text');
07
08 return new Response(value ?? 'No value for that key');
09 },
10};
Execute o comando de criação
azion create function --name kv-quickstart --code ./kv-quickstart.js --active true
Leia a saída

O comando imprime o id da nova function:

Created function with ID 12346

Registre o id. A instância referencia a function por ele.

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.

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
01{
02 "name": "kv-quickstart",
03 "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};"
04}
Envie a requisição de criação
Shell
01curl --request POST \
02 --url https://api.azion.com/v4/workspace/functions \
03 --header 'Accept: application/json' \
04 --header 'Authorization: Token [TOKEN VALUE]' \
05 --header 'Content-Type: application/json' \
06 --data @function.json
Leia a resposta

Um 202 carrega a function:

JSON
01{
02 "state": "pending",
03 "data": {
04 "id": 12345,
05 "name": "kv-quickstart",
06 "last_editor": "user@example.com",
07 "last_modified": "2026-01-01T12:00:00.385220Z",
08 "product_version": "2.0",
09 "active": true,
10 "runtime": "azion_js",
11 "execution_environment": "application",
12 "reference_count": 0
13 }
14}

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.

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.

Para configurar as duas pelo Azion Console:

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.

Na aba Main Settings, ative o módulo Functions
Selecione Save
Vá para a aba Functions Instances
Selecione + Function Instance
Nomeie a instância

Insira um nome para a instância. Por exemplo: kv-quickstart instance.

Selecione a function kv-quickstart
Selecione Save
Vá para a aba Rules Engine
Selecione + Rule
Nomeie a regra

Insira um nome para a regra. Por exemplo: Run kv-quickstart.

Selecione Request Phase
Defina os critérios

Na seção Criteria, selecione a variável ${uri} e o operador is equal, e insira /kv-quickstart como argumento.

Na seção Behaviors, selecione Run Function
Selecione a instância que você criou
Selecione Save

A regra executa a instância em toda requisição cuja URI é /kv-quickstart.

Para configurar as duas com a Azion CLI, substitua o id da aplicação e o id da function pelos seus:

Ative o módulo Functions
azion update application --application-id <application_id> --functions true
Crie a instância
azion create function-instance --application-id <application_id> --function-id <function_id> --name "kv-quickstart instance"

O comando imprime o id da nova instância:

Created Function Instance with ID 12348
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
01{
02 "name": "Run kv-quickstart",
03 "description": "Run the function on /kv-quickstart",
04 "active": true,
05 "criteria": [
06 [
07 {
08 "conditional": "if",
09 "variable": "${uri}",
10 "operator": "is_equal",
11 "argument": "/kv-quickstart"
12 }
13 ]
14 ],
15 "behaviors": [
16 {
17 "type": "run_function",
18 "attributes": { "value": 12348 }
19 }
20 ]
21}
Crie a regra
azion create rules-engine --application-id <application_id> --phase request --file rule.json

O comando imprime o id da nova regra:

Created Rules Engine with ID 234568

A regra executa a instância em toda requisição cuja URI é /kv-quickstart.

Três requisições ativam o módulo, criam a instância e adicionam a regra.

Ative o módulo Functions

Substitua <application_id> pelo ID da sua aplicação:

Shell
01curl --request PATCH \
02 --url https://api.azion.com/v4/workspace/applications/<application_id> \
03 --header 'Accept: application/json' \
04 --header 'Authorization: Token [TOKEN VALUE]' \
05 --header 'Content-Type: application/json' \
06 --data {
07 "modules": {
08 "functions": {
09 "enabled": true
10 }
11 }
12}
Crie a instância

Substitua <function_id> pelo id que a criação da function retornou:

Shell
01curl --request POST \
02 --url https://api.azion.com/v4/workspace/applications/<application_id>/functions \
03 --header 'Accept: application/json' \
04 --header 'Authorization: Token [TOKEN VALUE]' \
05 --header 'Content-Type: application/json' \
06 --data {
07 "name": "kv-quickstart instance",
08 "function": <function_id>,
09 "args": {},
10 "active": true
11}

Um 202 carrega a instância, e data.id é o valor que a regra seleciona.

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
01{
02 "name": "Run kv-quickstart",
03 "description": "Run the function on /kv-quickstart",
04 "active": true,
05 "criteria": [
06 [
07 {
08 "conditional": "if",
09 "variable": "${uri}",
10 "operator": "is_equal",
11 "argument": "/kv-quickstart"
12 }
13 ]
14 ],
15 "behaviors": [
16 {
17 "type": "run_function",
18 "attributes": { "value": 12347 }
19 }
20 ]
21}
Crie a regra
Shell
01curl --request POST \
02 --url https://api.azion.com/v4/workspace/applications/<application_id>/request_rules \
03 --header 'Accept: application/json' \
04 --header 'Authorization: Token [TOKEN VALUE]' \
05 --header 'Content-Type: application/json' \
06 --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.

Requisite a URI

A sua aplicação responde no domínio dela. Para alcançar a function, requisite a URI correspondente à regra:

curl https://<your-azion-domain>/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 KVTodos os métodos que uma function chama contra um namespace, com os tipos de retorno e as opções que cada um aceita.NamespacesOs 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 funcionaOnde uma escrita chega, e de onde uma leitura é atendida.Boas práticasComo modelar uma key, e a convenção de nomes por trás de um nome que não pode ser alterado.