--- name: azion-upload-e-download-de-objetos description: >- Faça upload de objetos para um bucket do Object Storage pelo Azion Console, pela API ou pela Azion CLI, depois liste, baixe, substitua e exclua os objetos. --- # Upload e download de objetos Você faz upload, lista, faz download, substitui e exclui os objetos de um bucket do [Object Storage](/pt-br/documentacao/plataforma/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](/pt-br/documentacao/guias/desenvolvimento-de-aplicacoes/dados/criar-e-modificar-um-bucket/). --- ## Pré-requisitos - Um bucket. Para criar um, consulte [Criar um bucket](/pt-br/documentacao/guias/desenvolvimento-de-aplicacoes/dados/criar-e-modificar-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](/pt-br/documentacao/guias/plataforma/conta-e-billing/como-acessar-o-azion-console/). - Um [personal token](/pt-br/documentacao/guias/plataforma/conta-e-billing/personal-tokens/), para os procedimentos pela API. - A [Azion CLI](/pt-br/documentacao/devtools/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: 1. **Abra o bucket** Acesse [Azion Console](https://console.azion.com/) > **Object Storage** > **Buckets** e selecione o bucket. 2. **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](/pt-br/documentacao/plataforma/object-storage/limites/). --- ## 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: 1. **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: ```bash curl --location --request POST 'https://api.azion.com/v4/workspace/storage/buckets/my-bucket/objects/folder/file.csv' \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' \ --header 'Content-Type: text/csv' \ --data-binary '@./path/file.csv' ``` 2. **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 { "state": "executed", "data": { "object_key": "folder/file.csv" } } ``` 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](/pt-br/documentacao/plataforma/object-storage/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: ```bash azion create storage object --bucket-name my-bucket --object-key folder/file.csv --source ./path/file.csv ``` O comando imprime uma linha: ```text 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](https://console.azion.com/) > **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: ```bash curl --location 'https://api.azion.com/v4/workspace/storage/buckets/my-bucket/objects' \ --header 'Accept: application/json' \ --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 { "continuation_token": null, "results": [ { "key": "folder/file.csv", "last_modified": "2026-01-01T12:00:00.000000Z", "size": 12, "is_folder": false } ] } ``` 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: ```json {"key": "folder/", "last_modified": null, "size": 0, "is_folder": true} ``` ### A Azion CLI Nomeie o bucket com `--bucket-name`: ```bash 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: ```bash curl --location 'https://api.azion.com/v4/workspace/storage/buckets/my-bucket/objects/folder/file.csv' \ --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: ```bash curl --location 'https://api.azion.com/v4/workspace/storage/buckets/my-bucket/objects/folder/file.csv' \ --header 'Authorization: Token [TOKEN VALUE]' \ -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: ```bash 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: ```bash curl --location --request PUT 'https://api.azion.com/v4/workspace/storage/buckets/my-bucket/objects/folder/file.csv' \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' \ --header 'Content-Type: text/csv' \ --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 { "state": "executed", "data": { "object_key": "folder/file.csv" } } ``` ### A Azion CLI Nomeie o novo arquivo em `--source`: ```bash azion update storage object --bucket-name my-bucket --object-key folder/file.csv --source ./path/file.csv ``` O comando imprime uma linha: ```text 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: 1. **Abra o bucket** Acesse [Azion Console](https://console.azion.com/) > **Object Storage** > **Buckets** e selecione o bucket. 2. **Selecione os arquivos a excluir** 3. **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: ```bash curl --location --request DELETE 'https://api.azion.com/v4/workspace/storage/buckets/my-bucket/objects/folder/file.csv' \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' ``` A API responde com HTTP `202` e reporta a exclusão como pendente: ```json {"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: ```bash azion delete storage object --bucket-name my-bucket --object-key folder/file.csv ``` O comando nomeia a key que removeu: ```text 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](/pt-br/documentacao/guias/desenvolvimento-de-aplicacoes/dados/criar-e-modificar-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: 1. **Crie a function** Crie uma function em [Functions](/pt-br/documentacao/plataforma/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. ```js import Storage from "azion:storage"; async function doGet(path, bucket_name) { const storage = new Storage(bucket_name); const asset = await storage.get(path); return new Response(await asset.arrayBuffer(), { headers: { "Content-Type": asset.contentType }, }); } async function doPost(path, content_type, value, bucket_name) { let options = { "content-type": content_type } const storage = new Storage(bucket_name); await storage.put(path, value, options); return new Response("Object added."); } async function router(event) { const request = event.request; const method = request.method; const path = decodeURI(new URL(request.url).pathname); const bucket_name = event.args.bucket; if (method === "POST") { let content_type = request.headers.get("Content-Type"); let content = await request.arrayBuffer(); return doPost(path, content_type, content, bucket_name); } else if (method === "GET") { return doGet(path, bucket_name); } else { throw new Error(`Invalid method: ${method}. Expected POST or GET.`); } } addEventListener("fetch", (event) => { event.respondWith( router(event) ); }); ``` 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 | 2. **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 { "bucket": "my-bucket" } ``` 3. **Instancie a function em uma aplicação** Uma function responde a uma requisição somente quando uma [aplicação](/pt-br/documentacao/plataforma/applications/) 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](/pt-br/documentacao/devtools/runtime/api-reference/storage/). --- ## Próximos passos - [Usar um bucket como origem de uma aplicação](/pt-br/documentacao/guias/desenvolvimento-de-aplicacoes/dados/bucket-como-connector.md): Aponte uma aplicação para o bucket, para que esses objetos respondam a requisições vindas da internet. - [Buckets e objetos](/pt-br/documentacao/plataforma/object-storage/buckets-e-objetos.md): Todos os campos, parâmetros e erros dos endpoints de bucket e de objeto. - [Usar ferramentas compatíveis com S3 com Object Storage](/pt-br/documentacao/guias/desenvolvimento-de-aplicacoes/dados/protocolo-s3-para-object-storage.md): Gerencie os mesmos objetos com um cliente S3 e uma credencial. - [Solução de problemas](/pt-br/documentacao/plataforma/object-storage/solucao-de-problemas.md): O que significa cada recusa quando um upload, um download ou uma exclusão falha.