Upload e download de objetos

Você faz upload, lista, faz download, substitui e exclui os objetos de um bucket do Object Storage pelo Azion Console, pela API da Azion, pela Azion CLI ou por uma function. Um objeto existe assim que o seu upload é concluído, armazenado sob a key que você deu a ele. O bucket então lista essa key com o seu tamanho e a hora da última modificação.

Para criar o próprio bucket, ou para alterar o nível de acesso que ele carrega, consulte Criar um bucket.

Pré-requisitos

Um bucket. Para criar um, consulte Criar um bucket.
Um arquivo na sua máquina para fazer upload.
Acesso ao Azion Console, para os procedimentos pelo Console. Consulte Como acessar o Azion Console.
Um personal token, para os procedimentos pela API.
A Azion CLI instalada e autorizada, para os procedimentos pela CLI.

Faça upload de um objeto pelo Azion Console

Azion Console é o caminho mais curto para um punhado de arquivos. A API e a Azion CLI colocam o mesmo upload dentro de um script ou de um pipeline. Os arquivos chegam à área de arquivos do bucket, descrita como “Browse, upload, and manage objects stored in this bucket”. Para fazer upload deles:

Abra o bucket

Acesse Azion Console > Object Storage > Buckets e selecione o bucket.

Adicione os arquivos

Selecione Upload files para um ou mais arquivos, ou Upload folder para um diretório. Arrastar os arquivos até a área de soltura, que diz “Drag files here to add them to your bucket”, também os adiciona.

Cada arquivo é armazenado como um objeto do bucket e aparece na área de arquivos sob a sua key.

Atenção — Azion Console recusa um arquivo maior que 300 MB: “Files larger than 300 MB cannot be uploaded”. O limite vale para o Console. Para mais informações, consulte Limites do Object Storage.

Faça upload de um objeto pela API

O nome do bucket e a key do objeto vão no path e o arquivo vai no corpo da requisição. Para fazer upload do objeto:

Envie a requisição de upload

Substitua [TOKEN VALUE] pelo seu personal token, my-bucket pelo seu bucket e folder/file.csv pela key que você quer:

Shell

01curl --location --request POST 'https://api.azion.com/v4/workspace/storage/buckets/my-bucket/objects/folder/file.csv' \

02--header 'Accept: application/json' \

03--header 'Authorization: Token [TOKEN VALUE]' \

04--header 'Content-Type: text/csv' \

05--data-binary '@./path/file.csv'

Leia a resposta

A API responde com HTTP 201, ou 202 quando processa a requisição de forma assíncrona, e nomeia a key sob a qual armazenou o objeto:

JSON

01{

02 "state": "executed",

03 "data": {

04 "object_key": "folder/file.csv"

05 }

06}

O objeto é armazenado sob folder/file.csv. O segmento folder/ faz parte da key: Object Storage cria o prefix junto com o upload e nenhuma requisição o cria antes.

nota — O content type armazenado vem do header Content-Type do upload. Uma requisição que não carrega Content-Type deixa a Azion detectar o tipo. Uma key de objeto tem de 1 a 1.024 caracteres. Para mais informações, consulte Buckets e objetos.

Faça upload de um objeto pela Azion CLI

O comando lê o arquivo nomeado em --source e o armazena sob --object-key. Para fazer upload do objeto:

azion create storage object --bucket-name my-bucket --object-key folder/file.csv --source ./path/file.csv

O comando imprime uma linha:

Object created successfully

O objeto é armazenado no bucket, sob a key que você passou em --object-key.

Atenção — --source recebe um caminho relativo ao diretório em que você executa o comando. Um caminho absoluto falha, porque a Azion CLI antepõe o diretório de trabalho a ele.

Liste os objetos de um bucket

Toda interface retorna as keys que o bucket guarda e a API restringe a lista a um prefix.

Azion Console

Acesse Azion Console > Object Storage > Buckets e selecione o bucket. A sua área de arquivos lista os objetos que ele guarda.

A API

Envie uma requisição GET para o endpoint de objetos:

Shell

01curl --location 'https://api.azion.com/v4/workspace/storage/buckets/my-bucket/objects' \

02--header 'Accept: application/json' \

03--header 'Authorization: Token [TOKEN VALUE]'

A resposta carrega uma entrada por objeto: a sua key, a hora da última modificação, o seu tamanho em bytes e se a entrada é um prefix.

JSON

01{

02 "continuation_token": null,

03 "results": [

04 {

05 "key": "folder/file.csv",

06 "last_modified": "2026-01-01T12:00:00.000000Z",

07 "size": 12,

08 "is_folder": false

09 }

10 ]

11}

Quatro query parameters moldam a listagem:

Parâmetro	O que faz
`prefix`	Retorna as keys que começam com o valor. O padrão é vazio, o que retorna todas as keys
`all_levels`	Tem `true` como padrão e retorna as keys em todos os níveis abaixo do prefix
`max_object_count`	Define quantas entradas uma resposta carrega, até 1.000
`continuation_token`	Retorna as entradas que vêm depois do token que a resposta anterior carregou

Com all_levels=false, um prefix é retornado como uma entrada, em vez das keys abaixo dele:

{"key": "folder/", "last_modified": null, "size": 0, "is_folder": true}

A Azion CLI

Nomeie o bucket com --bucket-name:

azion list storage object --bucket-name my-bucket --page-size 5

O comando imprime uma tabela com uma coluna KEY e uma coluna LAST MODIFIED. --details adiciona uma coluna SIZE e --next-page avança para a página seguinte.

A listagem nomeia todas as keys que o bucket guarda, que é como você confirma que um upload chegou.

Faça download de um objeto

Um download retorna os bytes de um objeto, endereçado pela sua key.

A API

Envie uma requisição GET para a key:

Shell

01curl --location 'https://api.azion.com/v4/workspace/storage/buckets/my-bucket/objects/folder/file.csv' \

02--header 'Authorization: Token [TOKEN VALUE]'

A API responde com HTTP 200 e com o objeto como application/octet-stream, então o terminal imprime o conteúdo do objeto. Uma key que não existe responde com HTTP 404 e o erro 17013, Object Does Not Exist.

Para escrever o objeto em um arquivo local, adicione as opções -O e -J do curl. Elas pegam o nome do objeto nos headers da resposta e escrevem a saída em um arquivo:

Shell

01curl --location 'https://api.azion.com/v4/workspace/storage/buckets/my-bucket/objects/folder/file.csv' \

02--header 'Authorization: Token [TOKEN VALUE]' \

03-O -J

nota — Uma key que carrega um prefix, como folder/file.csv, não cria nenhum diretório. O arquivo é escrito no diretório em que você executou o comando.

A Azion CLI

Nomeie o bucket e a key:

azion describe storage object --bucket-name my-bucket --object-key folder/file.csv

O comando imprime o conteúdo do objeto.

Agora você tem os bytes do objeto, no terminal ou em um arquivo local.

Substitua um objeto

Dois métodos escrevem sobre o objeto armazenado sob uma key e eles diferem no que fazem com uma key que ainda não existe. POST armazena o objeto nos dois casos e responde com HTTP 201. PUT apenas substitui: um PUT para uma key que não existe responde com HTTP 404 e o erro 17013, Object Does Not Exist.

A API

Envie uma requisição PUT para a key, com o novo arquivo como corpo:

Shell

01curl --location --request PUT 'https://api.azion.com/v4/workspace/storage/buckets/my-bucket/objects/folder/file.csv' \

02--header 'Accept: application/json' \

03--header 'Authorization: Token [TOKEN VALUE]' \

04--header 'Content-Type: text/csv' \

05--data-binary '@./path/file.csv'

A API responde com HTTP 200, ou 202 quando processa a requisição de forma assíncrona, e nomeia a key que substituiu:

JSON

01{

02 "state": "executed",

03 "data": {

04 "object_key": "folder/file.csv"

05 }

06}

A Azion CLI

Nomeie o novo arquivo em --source:

azion update storage object --bucket-name my-bucket --object-key folder/file.csv --source ./path/file.csv

O comando imprime uma linha:

Object updated successfully

azion update storage object -h lista todas as flags que ele aceita.

A key agora endereça o novo conteúdo e o conteúdo que ela guardava não existe mais.

nota — Uma key não pode ser renomeada. Azion Console carrega um diálogo Move, que pede o caminho da pasta de destino e usa a raiz do bucket quando o caminho está vazio. A movimentação copia o objeto para o destino e exclui o original, então a própria key continua imutável.

Exclua um objeto

Uma exclusão é assíncrona. A Azion aceita a requisição, a key sai da listagem imediatamente e o objeto é removido permanentemente após um período de carência de 24 horas.

Azion Console

Para excluir os objetos:

Abra o bucket

Acesse Azion Console > Object Storage > Buckets e selecione o bucket.

Selecione os arquivos a excluir

Confirme a exclusão

Azion Console pergunta “Are you sure you want to delete the selected files?” antes de removê-los.

Os objetos saem da área de arquivos do bucket.

A API

Envie uma requisição DELETE para a key:

Shell

curl --location --request DELETE 'https://api.azion.com/v4/workspace/storage/buckets/my-bucket/objects/folder/file.csv' \

02--header 'Accept: application/json' \

03--header 'Authorization: Token [TOKEN VALUE]'

A API responde com HTTP 202 e reporta a exclusão como pendente:

{"state": "pending"}

A key sai da listagem e uma requisição por ela responde com HTTP 404 imediatamente.

A Azion CLI

Nomeie o bucket e a key:

azion delete storage object --bucket-name my-bucket --object-key folder/file.csv

O comando nomeia a key que removeu:

Object folder/file.csv was deleted successfully

O objeto não responde a nenhuma requisição e uma segunda exclusão da mesma key retorna o erro 17013, Object Does Not Exist.

Atenção — A Azion remove permanentemente um objeto excluído após um período de carência de 24 horas e recusa excluir o bucket durante esse período. Para mais informações, consulte Criar um bucket.

Leia e escreva objetos a partir de uma function

Uma function alcança o mesmo bucket pelo módulo azion:storage, então uma aplicação armazena o que uma requisição carrega e retorna o que o bucket guarda. Para colocar o bucket atrás de uma function:

Crie a function

Crie uma function em Functions com este código. Ele roteia por método. Um POST escreve o corpo da requisição sob a key retirada do path da requisição. Um GET lê o objeto de volta e responde com o content type com que ele foi armazenado.

JavaScript

01import Storage from "azion:storage";

03async function doGet(path, bucket_name) {

04 const storage = new Storage(bucket_name);

05 const asset = await storage.get(path);

06 return new Response(await asset.arrayBuffer(), {

07 headers: {

08 "Content-Type": asset.contentType

09 },

10 });

11}

13async function doPost(path, content_type, value, bucket_name) {

14 let options = {

15 "content-type": content_type

16 }

17 const storage = new Storage(bucket_name);

18 await storage.put(path, value, options);

19 return new Response("Object added.");

20}

22async function router(event) {

23 const request = event.request;

24 const method = request.method;

25 const path = decodeURI(new URL(request.url).pathname);

26 const bucket_name = event.args.bucket;

27 if (method === "POST") {

28 let content_type = request.headers.get("Content-Type");

29 let content = await request.arrayBuffer();

30 return doPost(path, content_type, content, bucket_name);

31 } else if (method === "GET") {

32 return doGet(path, bucket_name);

33 } else {

34 throw new Error(`Invalid method: ${method}. Expected POST or GET.`);

35 }

36}

38addEventListener("fetch", (event) => {

39 event.respondWith(

40 router(event)

41 );

42});

Os valores que ele carrega:

Variável	Descrição
`path`	O caminho até o objeto. Exemplo: `./path/file.csv`
`bucket_name`	O nome do bucket. Exemplo: `my-bucket`
`content_type`	O MIME type do objeto. Exemplo: `text/csv`
`value`	O conteúdo do objeto, como dados binários

Defina o argumento do bucket

A function lê o nome do bucket dos seus próprios argumentos, então adicione a propriedade bucket com o nome do seu bucket como string:

JSON

01{

02 "bucket": "my-bucket"

03}

Instancie a function em uma aplicação

Uma function responde a uma requisição somente quando uma aplicação a executa, então instancie a function na aplicação que recebe os uploads.

Um POST para a aplicação armazena o corpo da requisição no bucket. Um GET para o mesmo path retorna o objeto com o content type com que ele foi armazenado.

nota — storage.put e storage.get são dois dos métodos que o módulo carrega e storage.list e storage.delete cobrem as outras duas operações desta página. Para cada método, os seus parâmetros e o que ele retorna, consulte Storage runtime API.

Próximos passos

Usar um bucket como origem de uma aplicaçãoAponte uma aplicação para o bucket, para que esses objetos respondam a requisições vindas da internet.Buckets e objetosTodos os campos, parâmetros e erros dos endpoints de bucket e de objeto.Usar ferramentas compatíveis com S3 com Object StorageGerencie os mesmos objetos com um cliente S3 e uma credencial.Solução de problemasO que significa cada recusa quando um upload, um download ou uma exclusão falha.