# Buckets e objetos Um bucket é o container em que [Object Storage](/pt-br/documentacao/plataforma/object-storage/) guarda objetos. Um objeto é um arquivo, a chave sob a qual ele é armazenado e o content type com que ele é servido. Buckets não são aninhados, e um bucket guarda objetos diretamente. Esta página lista os campos de ambos, as operações que a API da Azion v4 expõe e os erros que elas retornam. Para o protocolo S3 e suas credenciais, consulte [Compatibilidade com S3](/pt-br/documentacao/plataforma/object-storage/compatibilidade-s3/). --- ## Nomes de bucket O nome de um bucket é escolhido na criação e não pode ser alterado depois. | Regra | Valor | | ----------------- | ------------------------------------------------------------------------- | | Comprimento | 6 a 63 caracteres | | Caracteres | Letras, números e o hífen (`-`) | | Prefixo reservado | Um nome não pode começar com `azion` | | Unicidade | Um nome é único entre todas as contas Azion, e nunca apenas dentro da sua | Um nome já em uso retorna `17000`, e um nome que começa com `azion` retorna `17001`. Como os nomes são globais, um nome curto e genérico provavelmente já está em uso. Nomear um bucket pelo conteúdo que ele guarda e pelo acesso de que ele precisa mantém os nomes disponíveis e legíveis, como em `media-assets-ro`. --- ## Campos do bucket | Campo | Tipo | Obrigatório | Padrão | Descrição | | ------------------ | ----------------------------------------- | ----------- | ------ | ------------------------------------------------------------- | | `name` | string, 6 a 63 caracteres | Sim | — | O nome do bucket. Somente leitura após a criação | | `workloads_access` | `read_only`, `read_write` ou `restricted` | Sim | — | O que a plataforma da Azion pode fazer com o bucket | | `last_editor` | string | — | — | A conta que alterou o bucket pela última vez. Somente leitura | | `last_modified` | date-time | — | — | Quando o bucket foi alterado pela última vez. Somente leitura | | `product_version` | string | — | `1.0` | A versão do schema do bucket. Somente leitura | `workloads_access` é o único campo que um `PATCH` aceita. Enviar `name` no corpo de um `PATCH` retorna `17004`. --- ## Níveis de acesso `workloads_access` decide o que a plataforma da Azion pode fazer com o bucket quando uma aplicação o serve. Ele não restringe a API da Azion nem o protocolo S3: uma credencial que carrega `writeFiles` grava em um bucket definido como `read_only`. | Valor | A plataforma pode | A API e o protocolo S3 podem | | ------------ | ----------------------------------------------------------------------- | ----------------------------------- | | `read_only` | Ler objetos | Ler e gravar, conforme a credencial | | `read_write` | Ler e gravar objetos | Ler e gravar, conforme a credencial | | `restricted` | Nem ler nem gravar, e o bucket não pode estar por trás de uma aplicação | Ler e gravar, conforme a credencial | Azion Console apresenta os mesmos três níveis em **Workloads Access**. Para o controle e onde ele fica, consulte [Criar um bucket](/pt-br/documentacao/guias/desenvolvimento-de-aplicacoes/dados/criar-e-modificar-um-bucket/). Defina `read_only` para conteúdo que uma aplicação serve e que nada regrava. Defina `read_write` apenas onde uma function grava objetos durante uma requisição, e proteja o caminho na function: qualquer requisição que alcança um bucket `read_write` por meio de uma aplicação pode modificá-lo. Defina `restricted` para dados que nenhuma aplicação serve. --- ## Chaves de objeto e prefixos Uma chave de objeto identifica um objeto dentro de um bucket. Ela tem de 1 a 1.024 caracteres e não precisa corresponder ao nome do arquivo de onde veio. Uma chave pode conter a barra (`/`), e as interfaces leem um segmento inicial compartilhado como um prefixo. Prefixos não são pastas e não são criados de antemão: fazer upload para a chave `src/assets/logo.svg` em um bucket vazio cria o objeto e o prefixo em uma única requisição. ```text README.md src/index.js src/assets/logo.svg ``` Nesse bucket, `README.md` fica na raiz, `src` é um prefixo que guarda um objeto e um prefixo aninhado, e `src/assets` guarda `logo.svg`. Uma listagem com `prefix=src/assets/` retorna apenas `logo.svg`. Um Connector que aponta para o prefixo `src/assets` serve esse objeto na raiz do caminho da aplicação. Uma chave não pode ser renomeada. Fazer upload para uma chave que já guarda um objeto substitui esse objeto, e o conteúdo anterior não pode ser recuperado. --- ## Content type O content type armazenado com um objeto é o que o header `Content-Type` da requisição de upload carrega. Quando a requisição não carrega `Content-Type`, Azion detecta o tipo a partir do objeto. A API também aceita um header `Storage-Content-Type`. Ele não tem efeito sobre o content type armazenado: um upload que envia `Storage-Content-Type: image/png` e nenhum `Content-Type` armazena o tipo que Azion detectou. Defina `Content-Type` na requisição de upload. --- ## Operações Todas as operações são autenticadas e ficam em `https://api.azion.com/v4/workspace/storage`. | Operação | Método e caminho | | --------------------------- | ------------------------------------------------------------------------ | | Listar buckets | `GET /buckets` | | Criar um bucket | `POST /buckets` | | Recuperar um bucket | `GET /buckets/{bucket_name}` | | Atualizar um bucket | `PATCH /buckets/{bucket_name}` | | Excluir um bucket | `DELETE /buckets/{bucket_name}` | | Listar objetos | `GET /buckets/{bucket_name}/objects` | | Fazer download de um objeto | `GET /buckets/{bucket_name}/objects/{object_key}` | | Criar um objeto | `POST /buckets/{bucket_name}/objects/{object_key}` | | Substituir um objeto | `PUT /buckets/{bucket_name}/objects/{object_key}` | | Excluir um objeto | `DELETE /buckets/{bucket_name}/objects/{object_key}` | | Copiar um objeto | `POST /buckets/{bucket_name}/objects/{object_key}/copy/{new_object_key}` | `POST` em uma chave de objeto cria o objeto e o substitui quando a chave já está em uso. `PUT` substitui um objeto que existe e retorna `17013` para uma chave que não existe, então ele nunca cria um objeto. ### Criar um bucket ```bash curl --request POST \ --url https://api.azion.com/v4/workspace/storage/buckets \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' \ --header 'Content-Type: application/json' \ --data '{ "name": "my-bucket-ro", "workloads_access": "read_only" }' ``` A resposta carrega `201` e o bucket criado: ```json { "state": "executed", "data": { "name": "my-bucket-ro", "workloads_access": "read_only", "last_editor": "user@example.com", "last_modified": "2026-01-01T12:00:00.442763+00:00", "product_version": "1.0" } } ``` Recuperar um bucket retorna o mesmo objeto em `data`, sem a chave `state`. Criar, atualizar e excluir retornam `state`. ### Listar buckets ```bash curl --request GET \ --url 'https://api.azion.com/v4/workspace/storage/buckets?page_size=10' \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' ``` ```json { "count": 1, "total_pages": 1, "page": 1, "page_size": 10, "next": null, "previous": null, "results": [ { "name": "my-bucket-ro", "workloads_access": "read_only", "last_editor": "user@example.com", "last_modified": "2026-01-01T12:00:00.442763+00:00", "product_version": "1.0" } ] } ``` | Parâmetro de consulta | Efeito | | ----------------------------------------- | ---------------------------------------------------------------------------------- | | `page`, `page_size` | Pagina a lista. `page_size` aceita até 100 | | `search` | Corresponde a parte de um nome de bucket | | `name` | Corresponde a um nome de bucket exatamente | | `workloads_access` | Filtra pelo nível de acesso. Aceita valores separados por vírgula | | `ordering` | Ordena os resultados por um campo | | `fields` | Retorna apenas os campos indicados, separados por vírgula | | `last_editor`, `created`, `last_modified` | Filtra por editor ou data. Os filtros de data aceitam os sufixos `__gte` e `__lte` | Use `search` para corresponder a parte de um nome. O parâmetro `name` corresponde ao nome inteiro, então um valor parcial não retorna nada. ### Listar objetos ```bash curl --request GET \ --url 'https://api.azion.com/v4/workspace/storage/buckets/my-bucket-ro/objects' \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' ``` ```json { "continuation_token": null, "results": [ { "key": "src/assets/logo.svg", "last_modified": "2026-01-01T12:00:47.054000Z", "size": 12, "is_folder": false } ] } ``` | Parâmetro de consulta | Padrão | Efeito | | --------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `prefix` | vazio | Lista apenas as chaves sob um prefixo | | `all_levels` | `true` | Lista todas as chaves. Com `false`, um prefixo é retornado como uma entrada com `is_folder` definido como `true`, `size` igual a `0` e sem `last_modified` | | `max_object_count` | — | Número de chaves por resposta, limitado a 1.000 | | `continuation_token` | — | Retorna a próxima página, usando o token que a resposta anterior carregou | Uma resposta com mais chaves do que `max_object_count` carrega um `continuation_token`. Envie-o de volta na próxima requisição para ler o restante. ### Fazer upload de um objeto ```bash curl --request POST \ --url https://api.azion.com/v4/workspace/storage/buckets/my-bucket-ro/objects/src/assets/logo.svg \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' \ --header 'Content-Type: image/svg+xml' \ --data-binary '@./src/assets/logo.svg' ``` ```json { "state": "executed", "data": { "object_key": "src/assets/logo.svg" } } ``` ### Excluir um objeto ```bash curl --request DELETE \ --url https://api.azion.com/v4/workspace/storage/buckets/my-bucket-ro/objects/src/assets/logo.svg \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' ``` A resposta carrega `202` e `{"state": "pending"}`. A chave deixa de ser listada e deixa de ser servida imediatamente, e o objeto é removido permanentemente após um período de carência de 24 horas. ### Excluir um bucket Um bucket só é excluído enquanto não guarda objetos, e não dentro de 24 horas após a remoção do último objeto, por causa desse período de carência. Os dois casos retornam `17006`. Um bucket que nunca guardou um objeto é excluído de imediato. --- ## Autenticação Toda requisição carrega um [personal token](/pt-br/documentacao/guias/plataforma/conta-e-billing/personal-tokens/): ```http Authorization: Token [TOKEN VALUE] ``` A conta também precisa das permissões de storage para a operação. As seis permissões são View, Edit e Delete para Storage Bucket, e View, Edit e Delete para Storage Object. Para mais informações, consulte [Teams permissions](/pt-br/documentacao/fundamentos/teams-permissions/). --- ## Erros O corpo da resposta carrega um array `errors`. Cada entrada nomeia o `code`, o `title`, um `detail`, o `status` e o campo ao qual ela se aplica, em `source.pointer`. ```json { "errors": [ { "code": "17000", "title": "Bucket Already Exists", "detail": "Bucket name 'my-bucket-ro' is already in use.", "status": "400", "source": { "pointer": "/data/name" }, "meta": { "name": "my-bucket-ro" } } ] } ``` | Código | Título | Status | Causa | | ------- | -------------------------------- | ------ | ---------------------------------------------------------------------------- | | `10039` | `Invalid Choice` | 400 | `workloads_access` carrega um valor fora dos três que o campo aceita | | `10048` | `Min Length` | 400 | O nome do bucket tem menos de 6 caracteres | | `10059` | `Required Field` | 400 | `name` ou `workloads_access` está ausente em uma requisição de criação | | `17000` | `Bucket Already Exists` | 400 | O nome do bucket está em uso, na sua conta ou em outra | | `17001` | `Bucket Name Not Available` | 400 | O nome do bucket começa com `azion` | | `17004` | `Name Cannot Be Changed` | 400 | Uma requisição `PATCH` carrega `name` | | `17005` | `Bucket Does Not Exist` | 404 | O bucket nomeado no caminho não existe | | `17006` | `Cannot Delete Non Empty Bucket` | 400 | O bucket guarda objetos, ou um objeto foi removido dele nas últimas 24 horas | | `17013` | `Object Does Not Exist` | 404 | A chave de objeto não existe, em um download, um `PUT` ou uma exclusão | --- ## A runtime API As operações acima são chamadas HTTP, endereçadas a `api.azion.com` e autenticadas com um personal token. Uma function executada no Azion Runtime alcança os mesmos buckets por um segundo caminho: ela importa o módulo `azion:storage` e chama `put`, `get`, `delete` e `list` em um bucket que nomeia, sem token: o construtor recebe o nome do bucket e nada mais. Esse módulo pertence ao runtime, e não ao Object Storage, então seus métodos, o formato do `StorageObject` e as versões do runtime em que ele existe são documentados junto com os outros bindings do runtime, em [Storage runtime API](/pt-br/documentacao/devtools/runtime/api-reference/storage/). --- ## Recursos relacionados - [Como Object Storage funciona](/pt-br/documentacao/plataforma/object-storage/como-funciona.md): Como uma requisição chega a um objeto, e o que cada nível de acesso muda nisso. - [Compatibilidade com S3](/pt-br/documentacao/plataforma/object-storage/compatibilidade-s3.md): A credencial, o endpoint e as operações S3 que alcançam os mesmos buckets. - [Limites do Object Storage](/pt-br/documentacao/plataforma/object-storage/limites.md): Todos os limites desta página em uma tabela, com o uso que cada plano inclui. - [Criar um bucket](/pt-br/documentacao/guias/desenvolvimento-de-aplicacoes/dados/criar-e-modificar-um-bucket.md): O procedimento por trás das operações de bucket, pelo Azion Console, pela API e pela Azion CLI. - [Upload e download de objetos](/pt-br/documentacao/guias/desenvolvimento-de-aplicacoes/dados/upload-e-download-de-objetos-do-bucket.md): O procedimento por trás das operações de objeto, com a saída que cada uma retorna. - [API de storage do Azion Runtime](/pt-br/documentacao/devtools/runtime/api-reference/storage.md): Ler e gravar os mesmos objetos a partir de uma function, com `azion:storage`.