# Namespaces Um namespace é o contêiner em que [KV Store](/pt-br/documentacao/plataforma/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](/pt-br/documentacao/plataforma/functions/) 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](/pt-br/documentacao/devtools/runtime/api-reference/kv-store/). 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](/pt-br/documentacao/plataforma/kv-store/boas-praticas/). --- ## 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 ```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" }' ``` A resposta traz `201` e o namespace inteiro: ```json { "name": "my-namespace", "created_at": "2026-01-01T12:00:00.577829", "last_modified": "2026-01-01T12:00:00.577829" } ``` 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 ```bash curl --request GET \ --url https://api.azion.com/v4/workspace/kv/namespaces \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' ``` A resposta traz `200`, um namespace por entrada em `results` e um objeto `pagination` ao lado deles: ```json { "results": [ { "name": "my-namespace", "created_at": "2026-01-01T12:00:01+00:00", "last_modified": "2026-01-01T12:00:01+00:00" } ], "pagination": { "page": 1, "page_size": 50, "total_count": 1, "total_pages": 1, "has_next": false, "has_previous": false } } ``` 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 ```bash curl --request GET \ --url https://api.azion.com/v4/workspace/kv/namespaces/my-namespace \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' ``` A resposta traz `200`: ```json { "name": "my-namespace", "created_at": "2026-01-01T12:00:01+00:00", "last_modified": "2026-01-01T12:00:01+00:00" } ``` O segmento do caminho é o nome do namespace, e não um identificador. Um nome que a conta não tem retorna `404`: ```json { "state": "error", "error": { "code": "namespace_not_found", "message": "Namespace not found", "details": { "name": "no-such-namespace", "account_id": "[ACCOUNT ID]" } } } ``` 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](/pt-br/documentacao/devtools/runtime/api-reference/kv-store/). --- ## 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: ```json { "errors": [ { "code": "10007", "title": "Method Not Allowed", "detail": "Method \"DELETE\" not allowed.", "status": "405", "source": { "pointer": "/data" }, "meta": { "method": "DELETE" } } ] } ``` O envelope do serviço KV: ```json { "state": "error", "error": { "code": "validation_error", "message": "Name must be at least 3 characters long", "details": { "field": "name" } } } ``` | 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](/pt-br/documentacao/plataforma/kv-store/solucao-de-problemas/). --- ## Autenticação Toda requisição leva um personal token no header `Authorization`, sob o esquema `Token`, e pede JSON: ```http Authorization: Token [TOKEN VALUE] Accept: application/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](/pt-br/documentacao/plataforma/kv-store/limites/). --- ## Recursos relacionados - [KV Store API](/pt-br/documentacao/devtools/runtime/api-reference/kv-store.md): Os métodos que uma função chama sobre as keys dentro de um namespace. - [Como o KV Store funciona](/pt-br/documentacao/plataforma/kv-store/como-funciona.md): Onde um value é escrito, e de onde uma leitura é servida. - [Limites do KV Store](/pt-br/documentacao/plataforma/kv-store/limites.md): Todo limite desta página em uma tabela, com o uso que cada plano inclui. - [Boas práticas](/pt-br/documentacao/plataforma/kv-store/boas-praticas.md): A convenção de nomes por trás de um nome que não pode ser alterado. - [Solução de problemas](/pt-br/documentacao/plataforma/kv-store/solucao-de-problemas.md): O que fazer com o erro que uma requisição rejeitada retorna.