# Primeiros passos com Object Storage Este guia orienta você a armazenar o seu primeiro objeto no [Object Storage](/pt-br/documentacao/plataforma/object-storage/). No fim, você vai ter: - O seu primeiro bucket, que a Azion Platform lê sem modificar. - Um objeto armazenado nesse bucket, endereçado pela sua key. - O objeto listado no bucket, o que confirma o upload. Um bucket não é uma pasta pública: um objeto do qual você faz upload não responde a nenhuma requisição vinda da internet enquanto uma aplicação não apontar para ele. O resultado se apoia em três objetos, nesta ordem. O **bucket** é o container de nível mais alto para objetos e buckets não são aninhados. Cada **objeto** dentro dele é um arquivo, a sua key e o seu content type. A key endereça o objeto: uma `/` em uma key faz parte da key, não é uma pasta. Um **connector** do tipo Object Storage, combinado com uma regra do Rules Engine em uma [aplicação](/pt-br/documentacao/plataforma/applications/), é o que envia uma requisição ao bucket. Este guia cria os dois primeiros e para por aí. --- Selecione a interface que você vai usar. Os pré-requisitos e todas as etapas abaixo seguem essa escolha. ## Pré-requisitos - Um arquivo na sua máquina para fazer upload, como uma imagem. - Permissão para criar buckets e objetos na sua conta. Para mais informações, consulte [Como gerenciar permissões de times](/pt-br/documentacao/fundamentos/teams-permissions/). **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** - Um [personal token](/pt-br/documentacao/guias/plataforma/conta-e-billing/personal-tokens/) e o `curl`. --- ## Crie um bucket Um bucket guarda os objetos dos quais você faz upload. Este dá à Azion Platform acesso somente de leitura, o nível para conteúdo que a plataforma entrega sem modificar. Um nome de bucket tem de 6 a 63 caracteres, usa letras, números e o hífen e nunca começa com `azion`. Ele é único em todas as contas Azion, então um nome curto e genérico provavelmente já está reservado. **Console** Para criar o bucket pelo Azion Console: 1. **Abra a lista de buckets** Acesse [Azion Console](https://console.azion.com/) > **Object Storage** > **Buckets**. 2. **Abra o formulário de criação** Inicie um novo bucket a partir da lista de **Buckets**. Uma conta que ainda não tem buckets oferece **Bucket** na lista vazia. 3. **Nomeie o bucket** Em **General**, em **Name**, insira um nome seu. 4. **Mantenha o nível de acesso** Em **Settings**, mantenha **Workloads Access** como *Read Only*, o padrão, para que a plataforma leia os objetos, mas não possa modificá-los. 5. **Selecione Create Bucket** O bucket aparece em **Buckets**, que lista o seu **Name**, **Size**, **Last Editor** e **Last Modified**. **CLI** Para criar o bucket com a Azion CLI, substitua `my-first-bucket` por um nome seu: 1. **Execute o comando de criação** ```bash azion create storage bucket --name my-first-bucket --workloads-access read_only ``` 2. **Leia a saída** O comando confirma o bucket: ```text Bucket created successfully ``` Um nome que outra conta já tem é recusado. Escolha um nome diferente e execute o comando outra vez. O bucket existe e não guarda nenhum objeto. Para todas as flags que o comando aceita, consulte [Azion CLI create](/pt-br/documentacao/devtools/cli/recursos/). **API** Para criar o bucket com a Azion API, substitua `[TOKEN VALUE]` pelo seu personal token e `my-first-bucket` por um nome seu: 1. **Envie a requisição de criação** ```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-first-bucket", "workloads_access": "read_only" }' ``` 2. **Leia a resposta** Um `201` carrega o bucket: ```json { "state": "executed", "data": { "name": "my-first-bucket", "workloads_access": "read_only", "last_editor": "user@example.com", "last_modified": "2026-01-01T12:14:08.914719+00:00", "product_version": "1.0" } } ``` Um `400` com o código `17000` significa que o nome já está em uso, na sua conta ou em outra. Escolha um nome diferente e envie a requisição outra vez. O bucket existe e não guarda nenhum objeto. > **nota** > > **Workloads Access** decide apenas o que a Azion Platform pode fazer com o bucket. Não restringe a API nem o protocolo S3: uma credencial que carrega capacidade de escrita escreve em um bucket somente de leitura. Para mais informações, consulte [Como o Object Storage funciona](/pt-br/documentacao/plataforma/object-storage/como-funciona/). --- ## Faça upload de um objeto Um objeto é armazenado sob uma key e a key é como toda interface o endereça depois. Uma key tem de 1 a 1.024 caracteres. **Console** Para fazer upload do arquivo pelo Azion Console: 1. **Abra o bucket** Em **Buckets**, selecione o bucket que você criou. 2. **Adicione o arquivo** Selecione **Upload files** ou arraste o arquivo até a área de destino. O nome do arquivo se torna a key do objeto. O Console recusa um arquivo maior que 300 MB. O objeto é armazenado no bucket, sob a key retirada do nome do arquivo. **CLI** Para fazer upload do arquivo com a Azion CLI, substitua o nome do bucket, a key e o caminho do arquivo pelos seus: 1. **Execute o comando de criação** ```bash azion create storage object --bucket-name my-first-bucket --object-key images/logo.png --source ./logo.png ``` 2. **Leia a saída** O comando confirma o objeto: ```text Object created successfully ``` O objeto está armazenado. O segmento `images/` faz parte da key, não é uma pasta que precisava existir antes. > **Atenção** > > Passe para `--source` um caminho relativo ao diretório em que você executa o comando, como `./logo.png`. A Azion CLI 4.23.0 também resolve um caminho absoluto a partir do diretório de trabalho, o que falha com `no such file or directory` e um caminho duplicado. **API** O upload informa o bucket e a key no path e envia o arquivo como o body. Não existe uma sequência de criar e depois escrever: o objeto existe quando a requisição tem sucesso. 1. **Envie a requisição de upload** Substitua a key e o caminho do arquivo pelos seus. Defina `Content-Type` com o tipo do seu arquivo, porque o valor armazenado é o que este header carrega: ```bash curl --request POST \ --url https://api.azion.com/v4/workspace/storage/buckets/my-first-bucket/objects/images/logo.png \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' \ --header 'Content-Type: image/png' \ --data-binary '@./logo.png' ``` 2. **Leia a resposta** Um `201` carrega a key sob a qual o objeto está armazenado: ```json { "state": "executed", "data": { "object_key": "images/logo.png" } } ``` O objeto está armazenado. O segmento `images/` faz parte da key, não é uma pasta que precisava existir antes. --- ## Confirme que o objeto está armazenado O bucket lista o que guarda, então você pode confirmar o upload sem outra interface. **Console** Para encontrar o objeto pelo Azion Console: 1. **Abra a lista de buckets** Acesse [Azion Console](https://console.azion.com/) > **Object Storage** > **Buckets**. 2. **Selecione o bucket** Selecione o bucket que você criou. 3. **Encontre o objeto pela sua key** O objeto é listado sob a sua key. Uma key que carrega uma `/`, como `images/logo.svg`, agrupa sob o segmento anterior: esse segmento é um prefix, não uma pasta. O objeto está listado sob a sua key, o que confirma o upload. **CLI** Para listar o que o bucket guarda com a Azion CLI: 1. **Execute o comando de listagem** ```bash azion list storage object --bucket-name my-first-bucket --details ``` 2. **Leia a saída** A tabela carrega uma linha por objeto, com a sua key, quando foi modificado pela última vez e o seu tamanho em bytes: ```text KEY LAST MODIFIED SIZE images/logo.png 2026-01-01 12:07:27.3 +0000 UTC 408 ``` Sem `--details`, a tabela carrega apenas a key e o horário de modificação. O objeto está listado sob a sua key, o que confirma o upload. **API** Duas requisições confirmam o upload: uma lista o bucket e a outra lê o objeto de volta. 1. **Liste os objetos do bucket** ```bash curl --request GET \ --url https://api.azion.com/v4/workspace/storage/buckets/my-first-bucket/objects \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' ``` A resposta lista a key, quando o objeto foi modificado pela última vez, o seu tamanho em bytes e se a entrada é um prefix: ```json { "continuation_token": null, "results": [ { "key": "images/logo.png", "last_modified": "2026-01-01T12:14:26.303000Z", "size": 408, "is_folder": false } ] } ``` 2. **Faça download do objeto** Leia o objeto de volta para um arquivo local e confirme o content type que a Azion armazenou: ```bash curl --request GET \ --url https://api.azion.com/v4/workspace/storage/buckets/my-first-bucket/objects/images/logo.png \ --header 'Authorization: Token [TOKEN VALUE]' \ --output ./logo-downloaded.png --dump-header - ``` Os headers da resposta carregam `HTTP/2 200` e o `content-type` que o upload definiu, e o arquivo é escrito em `./logo-downloaded.png`. O objeto é lido de volta com o content type que você definiu, o que confirma o upload. O seu primeiro objeto está armazenado no Object Storage e endereçado pela sua key. O bucket é alcançável pelo Azion Console, pela Azion CLI, pela Azion API e pelo protocolo S3. Por enquanto, por mais nada. Para entregar o objeto aos usuários finais, aponte um [connector](/pt-br/documentacao/plataforma/connectors/) do tipo Object Storage para o bucket. Uma regra do Rules Engine na aplicação então envia as requisições que casam para ele. Para mais informações, consulte [Use um bucket do Object Storage como origem](/pt-br/documentacao/guias/desenvolvimento-de-aplicacoes/dados/bucket-como-connector/). --- ## Próximos passos - [Como o Object Storage funciona](/pt-br/documentacao/plataforma/object-storage/como-funciona.md): O que cada nível de acesso permite e como uma requisição chega até um objeto. - [Use um bucket do Object Storage como origem](/pt-br/documentacao/guias/desenvolvimento-de-aplicacoes/dados/bucket-como-connector.md): O connector e a regra que colocam o bucket atrás de uma aplicação. - [Buckets e objetos](/pt-br/documentacao/plataforma/object-storage/buckets-e-objetos.md): Todos os campos que um bucket carrega, todas as operações e o erro que cada recusa retorna. - [Use ferramentas compatíveis com S3 no Object Storage](/pt-br/documentacao/guias/desenvolvimento-de-aplicacoes/dados/protocolo-s3-para-object-storage.md): Crie uma credencial e gerencie os mesmos objetos com um cliente S3.