Implemente upload de arquivos com Functions

Construa um endpoint Hono que verifica o arquivo enviado e o grava em um bucket do Object Storage a partir de uma função.

Última atualização

Ver como Markdown Configurar agente

Neste tutorial, você vai construir um endpoint de upload que armazena cada arquivo recebido em um bucket do Object Storage. Você vai criar um projeto Hono, escrever o handler de upload, criar um bucket com acesso de escrita, fazer o deploy do projeto e enviar um arquivo para ele.

O código completo deste exemplo está no pacote file-upload do repositório de exemplos de functions.

Pré-requisitos

1. Crie o projeto

Azion CLI cria um projeto a partir de um preset de framework. Para o passo a passo completo com Hono, consulte Deploy de aplicação Jamstack com Hono.

Para criar o projeto:

Autentique Azion CLI

Execute o comando de login:

azion login

Sem as flags de credencial, a CLI abre um fluxo pelo navegador. Ela armazena as credenciais localmente, e todo comando seguinte é autorizado na sua conta.

Inicialize o projeto

Execute Azion CLI no diretório que guarda seus projetos:

azion init
Nomeie o projeto

Digite um nome ou pressione enter para aceitar a sugestão:

? Your applications name: (black-thor)
Selecione o preset Hono

Azion CLI lista um preset por framework:

Shell
01? Choose a preset: [Use arrows to move, type to filter]
02 Angular
03 Astro
04 Docusaurus
05 Eleventy
06 Emscripten
07 Gatsby
08 Hexo
09> Hono
10 Hugo
11 Javascript
12 ...
Selecione um dos templates disponíveis
Responda N ao prompt do servidor de desenvolvimento local

Os estágios seguintes fazem o deploy do projeto em vez de executá-lo localmente:

Do you want to start a local development server? (y/N)
Acesse a pasta do projeto

Azion CLI nomeia a pasta com o nome do projeto:

cd <your-project-name>

A pasta contém o código-fonte da aplicação Hono que o template fornece.

2. Escreva o handler de upload

O handler responde a uma requisição POST em /upload. Ele faz o parse do formulário multipart, verifica o arquivo e o grava em um bucket. A gravação passa pelo método createObject da Biblioteca Storage da Azion.

O campo entry do azion.config.js indica o arquivo de entrada do projeto. Abra esse arquivo e substitua o conteúdo dele por este código:

TypeScript
01import type { AzionBucketObject, AzionStorageResponse } from "azion/storage";
02import { createObject } from "azion/storage";
03import { Hono } from "hono";
04
05const app = new Hono();
06
07app.post("/upload", async (c) => {
08 const body = await c.req.parseBody();
09 const file = body["file"];
10
11 if (
12 !file ||
13 typeof file !== "object" ||
14 typeof file.arrayBuffer !== "function"
15 ) {
16 return c.json({ message: "Invalid file" }, 400);
17 }
18
19 const maxSize = 2 * 1024 * 1024; // 2 MB, em bytes.
20 if (file.size > maxSize) {
21 return c.json({ message: "File size exceeds 2MB limit" }, 413);
22 }
23
24 try {
25 const { data: newObject, error }: AzionStorageResponse<AzionBucketObject> =
26 await createObject({
27 bucket: Azion.env.get("BUCKET_NAME")!,
28 key: file.name,
29 // @ts-expect-error content is wrongly typed
30 content: await file.arrayBuffer(),
31 });
32
33 if (error) {
34 throw new Error(error.message);
35 }
36
37 if (newObject) {
38 console.log(`Object created with key: ${newObject.key}`);
39 } else {
40 console.error("Failed to create object", error);
41 }
42
43 // @ts-expect-error content is wrongly typed
44 const content = new Uint8Array(newObject.content);
45
46 return c.body(content, {
47 status: 200,
48 headers: {
49 "Content-Type": file.type,
50 "Content-Disposition": `attachment; filename="${newObject?.key}"`,
51 "Content-Length": newObject?.size?.toString() ?? "0",
52 },
53 });
54 } catch (error) {
55 console.error("Error uploading file:", error);
56 return c.json({ message: "Error uploading file" }, 500);
57 }
58});
59
60export default app;

export default app é o padrão de handler ES Modules, que Azion recomenda em vez do padrão Service Worker. O código toma quatro decisões:

  • Um campo file que não contém um arquivo retorna 400 com o corpo {"message":"Invalid file"}.
  • Um arquivo acima da constante maxSize de 2 MB retorna 413 com o corpo {"message":"File size exceeds 2MB limit"}.
  • createObject grava o arquivo no bucket nomeado pela variável de ambiente BUCKET_NAME. A chave do objeto é o nome do arquivo.
  • Uma falha dentro de createObject retorna 500 com o corpo {"message":"Error uploading file"} e a exceção chega aos logs da função.

3. Configure as permissões de armazenamento

O nível de acesso de um bucket decide o que Azion Runtime faz com ele. Uma função grava objetos apenas em um bucket cujo acesso é read_write. Um bucket definido como read_only responde a leituras e rejeita gravações. Azion Runtime não alcança nenhum conteúdo em um bucket definido como restricted.

O nome de um bucket é único entre todas as contas Azion. Ele tem de 6 a 63 caracteres, aceita letras, números e o hífen (-) e nunca começa com azion.

O handler lê o nome do bucket na variável de ambiente BUCKET_NAME. Para criar o bucket e armazenar seu nome:

Crie o bucket em que o handler grava
azion create storage bucket --name "<your-bucket-name>" --workloads-access 'read_write'

O bucket existe na sua conta e Azion Runtime grava objetos nele.

Armazene o nome do bucket na sua conta

Insira o mesmo nome que você deu ao bucket:

azion create variables --key "BUCKET_NAME" --value "<your-bucket-name>" --secret false

A variável fica armazenada na conta e a função a lê com Azion.env.get('BUCKET_NAME'). Uma variável cuja chave contém password, pwd, secret, key, hash, encrypted, passcode, auth ou token é enviada como secret por padrão. A chave BUCKET_NAME não contém nenhuma dessas substrings. A flag --secret tem true como valor padrão, então --secret false armazena o nome do bucket como um valor comum. Um novo valor alcança a função apenas depois de um novo deploy.

4. Faça o deploy do projeto

Para enviar o projeto para Azion:

Confirme qual conta Azion CLI usa

Imprima a conta autenticada:

azion whoami

O terminal imprime o endereço de e-mail da conta em que os comandos são executados.

Faça o deploy do projeto

Na pasta do projeto, execute:

azion deploy

O deploy envia o código da função e configura a aplicação. Ele também cria as regras de roteamento, aplica as permissões de armazenamento e retorna um domínio. O domínio tem o formato https://xxxxxxx.map.azionedge.net. A propagação leva alguns minutos, então aguarde antes de fazer a requisição ao endpoint.

nota — Azion CLI abre o navegador na página de Azion Console que contém os logs do deploy. Quando o navegador não abre, use o link que o terminal imprime.

5. Verifique o upload

Para armazenar um arquivo pelo endpoint:

Crie um arquivo de texto

Escreva uma linha em um arquivo local:

echo "Azion file upload test" > upload-test.txt

O arquivo upload-test.txt existe no diretório atual.

Envie o arquivo para a rota de upload

Envie o arquivo em um formulário multipart, no campo file:

curl -F "file=@upload-test.txt" https://<your-azion-domain>/upload

O corpo da resposta carrega o objeto armazenado:

Azion file upload test
Liste os objetos do bucket

Leia as chaves que o bucket contém:

azion list storage object --bucket-name "<your-bucket-name>"

A chave upload-test.txt aparece na lista.

O endpoint passa a armazenar todo arquivo que aceita. Uma requisição cujo campo file não contém um arquivo responde 400 e um arquivo acima de 2 MB responde 413. Quando uma requisição responde 500, leia os logs da função para encontrar a exceção.

Próximos passos

Object StoragePermissões de bucket, chaves de objeto, prefixos e as classes de operação que são cobradas.Biblioteca Storage da AzionTodos os métodos de azion/storage, incluindo getObjectByKey, updateObject e deleteObject.Variáveis de ambienteArmazene configurações e segredos fora do código da função e leia cada valor por chave em tempo de execução.Solução de problemas de execução e logs de funçõesAs correções para uma função que nunca executa, para antes de responder ou não escreve nada nos logs.Boas práticas de FunctionsO que cada parte do handler faz e as escolhas de design que mantêm uma invocação dentro dos limites.Limites de FunctionsO tamanho de corpo que uma função processa por plano e todos os outros limites de Functions.