Namespaces
Consulte os três campos de um namespace, as três operações da API sobre ele e os erros que cada rejeição retorna.
Um namespace é o contêiner em que KV Store guarda keys e values. O nome dele é o identificador dele, e um namespace não tem id numérico. Azion API v4 endereça um namespace pelo nome, e uma função abre um namespace pelo nome por meio de Azion.KV. Esse cliente pertence ao runtime, e não ao KV Store, então os métodos, as opções e os erros dele estão documentados com os outros bindings do runtime, em KV Store API.
Um namespace é permanente. Ele não pode ser renomeado, desativado, esvaziado nem excluído, em nenhuma interface. Azion API v4 expõe três operações sobre ele — criar, listar e consultar — e uma função também não cria um namespace. Depois que a conta tem um nome, ela tem esse nome dali em diante, então vale escolher o nome antes da primeira requisição. Esta página lista os campos de um namespace, as três operações, o envelope da listagem e os erros que uma requisição rejeitada retorna.
Nomes de namespace
O nome de um namespace é escolhido na criação e não pode ser alterado depois.
| Regra | Valor |
|---|---|
| Comprimento | 3 a 63 caracteres |
| Caracteres | Letras, números, o hífen (-) e o underscore (_), conforme ^[a-zA-Z0-9_-]+$ |
| Caixa | Maiúsculas são aceitas, e os nomes diferenciam maiúsculas de minúsculas. BadNameUpper e badnameupper são dois namespaces diferentes |
| Unicidade | Um nome é único dentro da sua conta |
Um nome com menos de 3 caracteres, com mais de 63 caracteres ou com um caractere fora do padrão retorna 400 com validation_error. Um nome que a conta já tem retorna 400 com a mensagem Namespace already exists, e não 409.
O padrão aceita letras maiúsculas, então Orders-EU é um nome tão válido quanto orders-eu, e os dois são namespaces diferentes: uma consulta a um responde 200 enquanto o mesmo nome em outra caixa responde 404 com namespace_not_found. Minúsculas são uma convenção, e não uma regra, e ela importa porque um namespace não pode ser excluído, então um nome criado na caixa errada é permanente. Para a convenção que Azion recomenda, consulte Boas práticas.
Campos do namespace
| Campo | Tipo | Obrigatório | Padrão | Descrição |
|---|---|---|---|---|
name | string, 3 a 63 caracteres | Sim | — | O nome do namespace, e o identificador dele. Somente leitura após a criação |
created_at | date-time | — | — | Quando o namespace foi criado. Somente leitura |
last_modified | date-time | — | — | Quando o namespace mudou pela última vez. Somente leitura |
Uma requisição de criação aceita name, e nada mais. O recurso tem esses três campos e nenhum outro: não há id, não há description e não há status. Nenhum campo é editável depois.
Os dois campos de timestamp voltam em dois formatos. Uma resposta de criação traz microssegundos e nenhum fuso, como em 2026-01-01T12:00:00.577829. Uma resposta de consulta ou de listagem traz segundos inteiros e um fuso, arredondados para cima, como em 2026-01-01T12:00:01+00:00. Os dois descrevem o mesmo instante, e os exemplos abaixo mostram cada resposta no formato dela.
Operações
Toda operação é autenticada e fica sob https://api.azion.com/v4/workspace/kv.
| Operação | Método e caminho |
|---|---|
| Criar um namespace | POST /namespaces |
| Listar namespaces | GET /namespaces |
| Consultar um namespace | GET /namespaces/{name} |
Criar, listar e consultar são toda a superfície.
Criar um namespace
A resposta traz 201 e o namespace inteiro:
A requisição é síncrona, e não há estado de provisionamento para consultar em loop. O name que a resposta traz é o identificador que toda chamada seguinte usa. Uma função abre o namespace com esse mesmo nome.
Listar namespaces
A resposta traz 200, um namespace por entrada em results e um objeto pagination ao lado deles:
A listagem retorna todos os namespaces que a conta tem, uma página por vez. Esse envelope não é o que o resto de Azion API v4 usa: Paginação descreve esse envelope.
Consultar um namespace
A resposta traz 200:
O segmento do caminho é o nome do namespace, e não um identificador. Um nome que a conta não tem retorna 404:
O objeto details repete o nome que foi pedido e a conta com que a requisição se autenticou. O account_id acima é um placeholder.
Paginação
A resposta da listagem não usa o envelope de coleção de Azion API v4. Toda outra coleção da v4 traz count, total_pages, page, page_size, next, previous e results no nível de cima. KV Store traz results ao lado de um objeto pagination aninhado, então código escrito para outra coleção da v4 lê campos que não estão lá.
| Campo | O que traz |
|---|---|
results | Um namespace por entrada, com os campos listados em Campos do namespace |
pagination.page | A página que esta resposta traz |
pagination.page_size | Namespaces por página |
pagination.total_count | Namespaces que a conta tem |
pagination.total_pages | Páginas em que o resultado se divide, no page_size atual |
pagination.has_next | Se existe uma página depois desta |
pagination.has_previous | Se existe uma página antes desta |
Não existem os campos next e previous. has_next e has_previous são booleanos, e não links, então um cliente que percorre a lista incrementa page por conta própria.
| Parâmetro de query | Efeito |
|---|---|
page | Retorna uma página da listagem |
page_size | Namespaces por página. Padrão 50, e aceita de 1 a 100 |
Um page_size fora de 1 a 100 retorna 400 com invalid_page_size.
Uma requisição HEAD na coleção retorna as mesmas contagens em headers: x-total-count, x-page, x-page-size e x-total-pages.
O endpoint também aceita um parâmetro fields e o ignora. Uma requisição que envia ?fields=name recebe os três campos de todos os namespaces. Essa é a mesma resposta que uma requisição sem o parâmetro recebe, então a resposta não pode ser reduzida.
As operações que não existem
OPTIONS na coleção responde allow: GET, POST, HEAD, OPTIONS. OPTIONS em um namespace responde allow: GET, HEAD, OPTIONS. PUT, PATCH e DELETE respondem 405, cada um no envelope do gateway que Erros descreve.
Não há renomeação, não há desativação, não há esvaziamento e não há exclusão, nem em Azion API v4 nem em qualquer outra interface. É isso que torna um namespace permanente.
Também não há uma coleção de keys. Os caminhos que teriam uma retornam a página HTML Not Found da plataforma: /v4/workspace/kv/namespaces/{name}/keys, e o mesmo caminho terminando em /values, /items ou /entries. Um caminho que o gateway roteia retorna um erro JSON, então a página HTML é o sinal de que esses caminhos não existem. As keys são alcançadas a partir de uma função. Para os métodos que chegam até elas, consulte KV Store API.
Erros
Dois envelopes de erro coexistem neste endpoint, e um cliente que trata um deles perde o outro. O gateway da plataforma emite o envelope de Azion API v4 para um 405, com um code numérico e o texto em detail. O serviço KV emite o envelope próprio dele para 400, 404 e 500, com um code em snake_case e o texto em message.
O envelope do gateway:
O envelope do serviço KV:
| Status | code | message | Causa |
|---|---|---|---|
| 400 | validation_error | Name must be at least 3 characters long | O nome tem menos de 3 caracteres |
| 400 | validation_error | Name must be no more than 63 characters long | O nome tem mais de 63 caracteres |
| 400 | validation_error | Name is required | O corpo não traz name, ou name é uma string vazia |
| 400 | validation_error | Name can only contain alphanumeric characters, hyphens and underscores | O nome tem um caractere fora de ^[a-zA-Z0-9_-]+$ |
| 400 | validation_error | Namespace already exists | A conta já tem um namespace com esse nome |
| 400 | invalid_page_size | Page size must be between 1 and 100 | page_size está fora de 1 a 100 |
| 404 | namespace_not_found | Namespace not found | A conta não tem nenhum namespace com esse nome. details repete name e account_id |
| 405 | 10007 | — | Uma requisição PUT, PATCH ou DELETE. O envelope do gateway traz Method Not Allowed em title |
| 500 | internal_error | Internal server error | O corpo não é JSON válido, ou name tem um tipo diferente de string |
A linha do 500 registra o que o endpoint retorna, e não uma resposta para a qual escrever código. Um corpo que não é JSON válido, e um name que não é uma string, são erros do cliente. Para o sintoma e o que verificar, consulte Solução de problemas.
Autenticação
Toda requisição leva um personal token no header Authorization, sob o esquema Token, e pede JSON:
Uma requisição que leva um corpo também leva Content-Type: application/json.
Limites
O nome de um namespace tem de 3 a 63 caracteres, e uma resposta de listagem retorna no máximo 100 namespaces por página.
Todo outro limite de um namespace, o que a plataforma faz ao passar de cada valor e o uso que cada plano inclui estão em Limites do KV Store.