Crie uma API RESTful de tarefas com Functions e SQL Database

Crie um banco de dados em SQL Database, escreva rotas CRUD com Hono e faça o deploy de uma API de tarefas que roda como uma função.

Última atualização

Ver como Markdown Configurar agente

Neste tutorial, você vai construir uma API RESTful de tarefas que roda como uma função e mantém seus registros em SQL Database. Você vai criar o banco de dados e sua tabela, escrever a camada de dados e as rotas Hono, fazer o deploy do projeto com Azion CLI e chamar cada endpoint.

O projeto finalizado é o exemplo restful-tasks no GitHub.

Pré-requisitos

1. Crie o banco de dados

A camada de dados acessa o banco de dados pelo nome e usa tasks como valor padrão quando nenhum nome está configurado. Nomeie o banco de dados como tasks para que esse valor padrão funcione.

Envie uma requisição POST para o endpoint de bancos de dados, substituindo [TOKEN VALUE] pelo seu personal token:

Shell
01curl --location 'https://api.azion.com/v4/workspace/sql/databases' \
02--header 'Authorization: Token [TOKEN VALUE]' \
03--header 'Content-Type: application/json' \
04--data {
05 "name": "tasks"
06}

A resposta traz o identificador do banco de dados e seu status:

JSON
01{
02 "state": "pending",
03 "data": {
04 "id": 118,
05 "name": "tasks",
06 "client_id": "6832h",
07 "status": "creating",
08 "created_at": "2024-04-18T11:22:59.468536Z",
09 "updated_at": "2024-04-18T11:22:59.468586Z",
10 "deleted_at": null
11 }
12}

Guarde o id. Todas as requisições seguintes acessam o banco de dados por esse valor.

nota — A criação não é instantânea. Envie requisições GET para o mesmo endpoint até que status mostre created. Para o conjunto completo de operações de banco de dados, consulte Como gerenciar um banco de dados SQL Database.

2. Crie a tabela tasks

A API armazena uma linha por tarefa, com um título, um indicador de conclusão e dois timestamps.

As duas requisições enviam um POST para o endpoint de query. Substitua <your-database-id> pelo id do seu banco de dados:

Crie a tabela
Shell
01curl --location 'https://api.azion.com/v4/workspace/sql/databases/<your-database-id>/query' \
02--header 'Authorization: Token [TOKEN VALUE]' \
03--header 'Content-Type: application/json' \
04--data {
05 "statements": [
06 "CREATE TABLE IF NOT EXISTS tasks (id INTEGER PRIMARY KEY AUTOINCREMENT, title TEXT NOT NULL, completed BOOLEAN DEFAULT FALSE, created_at DATETIME DEFAULT CURRENT_TIMESTAMP, updated_at DATETIME DEFAULT CURRENT_TIMESTAMP);"
07 ]
08}

A resposta informa um objeto de resultado por statement:

JSON
01{
02 "state": "executed",
03 "data": [
04 {
05 "results": {
06 "columns": [],
07 "rows": []
08 }
09 }
10 ]
11}
Insira três linhas

Os endpoints precisam de linhas para retornar:

Shell
01curl --location 'https://api.azion.com/v4/workspace/sql/databases/<your-database-id>/query' \
02--header 'Authorization: Token [TOKEN VALUE]' \
03--header 'Content-Type: application/json' \
04--data {
05 "statements": [
06 "INSERT INTO tasks (title, completed) VALUES ('\''Complete API documentation'\'', FALSE);",
07 "INSERT INTO tasks (title, completed) VALUES ('\''Test function deployment'\'', FALSE);",
08 "INSERT INTO tasks (title, completed) VALUES ('\''Review security configurations'\'', TRUE);"
09 ]
10}

Três statements retornam três objetos de resultado:

JSON
01{
02 "state": "executed",
03 "data": [
04 {
05 "results": {
06 "columns": [],
07 "rows": []
08 }
09 },
10 {
11 "results": {
12 "columns": [],
13 "rows": []
14 }
15 },
16 {
17 "results": {
18 "columns": [],
19 "rows": []
20 }
21 }
22 ]
23}

O banco de dados contém a tabela tasks e três linhas.

3. Crie o projeto

Azion CLI monta o projeto a partir de um template Hono.

Autentique a CLI

Execute o comando de login e siga os prompts:

azion login

A CLI armazena as credenciais localmente e autoriza todos os comandos seguintes na sua conta.

Inicie o projeto

Execute o comando init:

azion init
Nomeie o projeto

Aceite o nome sugerido ou digite o seu:

? Your applications name: (black-thor)
Selecione o preset Hono
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 o template Hono Boilerplate
Responda N ao servidor de desenvolvimento local
? Do you want to start a local development server? (y/N)
Responda N ao prompt de deploy
? Do you want to deploy your project? (y/N)
Acesse o diretório do projeto
cd <your-project-name>

A CLI cria o diretório do projeto com o código do template. Os comandos build, dev e deploy rodam de dentro dele.

4. Escreva a camada de dados

A camada de dados chama useQuery e useExecute da biblioteca azion/sql. As duas recebem o nome do banco de dados como primeiro argumento e um array de statements SQL como segundo. Para a superfície completa da biblioteca, consulte Biblioteca SQL da Azion.

Substitua o conteúdo de src/db.ts:

TypeScript
01import { useExecute, useQuery } from "azion/sql";
02
03const DATABASE_NAME = Azion.env.get("DATABASE_NAME") || "tasks";
04
05export interface Task {
06 id: number;
07 title: string;
08 completed: boolean;
09}
10
11export const getTasks = async (): Promise<Task[]> => {
12 const { data, error } = await useQuery(DATABASE_NAME, [
13 "SELECT * FROM tasks",
14 ]);
15 if (error) {
16 throw error;
17 }
18 return (
19 data?.results?.[0]?.rows?.map(
20 (row) =>
21 ({
22 id: row[0],
23 title: row[1],
24 completed: row[2] === 1,
25 } as Task)
26 ) || []
27 );
28};
29
30export const getTask = async (id: number): Promise<Task | null> => {
31 const { data, error } = await useQuery(DATABASE_NAME, [
32 `SELECT * FROM tasks WHERE id = ${id}`,
33 ]);
34 if (error) {
35 throw error;
36 }
37 return (
38 (data?.results?.[0]?.rows?.[0] &&
39 ({
40 id: data?.results?.[0]?.rows?.[0][0],
41 title: data?.results?.[0]?.rows?.[0][1],
42 completed: data?.results?.[0]?.rows?.[0][2] === 1,
43 } as Task)) ||
44 null
45 );
46};
47
48export const createTask = async (task: Omit<Task, "id">): Promise<Task> => {
49 const { data, error } = await useExecute(DATABASE_NAME, [
50 `INSERT INTO tasks (title, completed) VALUES ('${task.title}', ${task.completed}) RETURNING id`,
51 ]);
52 if (error) {
53 throw error;
54 }
55 const newId = data?.results?.[0]?.rows?.[0]?.[0] || "";
56 return { ...task, id: Number(newId) };
57};
58
59export const updateTask = async (
60 id: number,
61 task: Partial<Omit<Task, "id">>
62): Promise<Task | null> => {
63 const existingTask = await getTask(id);
64 if (!existingTask) {
65 return null;
66 }
67
68 const updatedTitle =
69 task.title !== undefined ? task.title : existingTask.title;
70 const updatedCompleted =
71 task.completed !== undefined ? task.completed : existingTask.completed;
72
73 const { data, error } = await useExecute(DATABASE_NAME, [
74 `UPDATE tasks SET title = '${updatedTitle}', completed = ${updatedCompleted} WHERE id = ${id}`,
75 ]);
76 if (error) {
77 throw error;
78 }
79 return { ...existingTask, title: updatedTitle, completed: updatedCompleted };
80};
81
82export const deleteTask = async (id: number): Promise<boolean> => {
83 const { data, error } = await useExecute(DATABASE_NAME, [
84 `DELETE FROM tasks WHERE id = ${id}`,
85 ]);
86
87 if (error) {
88 throw error;
89 }
90
91 return data?.state === "executed" || data?.state === "pending";
92};

O arquivo exporta uma função por operação: getTasks, getTask, createTask, updateTask e deleteTask. DATABASE_NAME usa tasks como valor padrão. Para ler um banco de dados com outro nome, defina DATABASE_NAME no arquivo .env do projeto.

5. Escreva as rotas da API

Hono vincula cada método HTTP e caminho a um handler. Cada handler envolve sua chamada de dados em um bloco try e retorna 500 com um erro JSON quando a chamada falha.

Substitua o conteúdo de src/app.ts:

TypeScript
01import { Hono } from 'hono';
02import {
03 createTask,
04 deleteTask,
05 getTask,
06 getTasks,
07 updateTask,
08} from './db';
09
10const app = new Hono();
11
12app.get('/tasks', async (c) => {
13 try {
14 const tasks = await getTasks();
15 return c.json(tasks);
16 } catch (error) {
17 return c.json({ error: 'Failed to fetch tasks' }, 500);
18 }
19});
20
21app.get('/tasks/:id', async (c) => {
22 try {
23 const { id } = c.req.param();
24 const task = await getTask(Number(id));
25 if (!task) {
26 return c.json({ error: 'Task not found' }, 404);
27 }
28 return c.json(task);
29 } catch (error) {
30 return c.json({ error: 'Failed to fetch task' }, 500);
31 }
32});
33
34app.post('/tasks', async (c) => {
35 try {
36 const { title, completed } = await c.req.json();
37 const newTask = await createTask({ title, completed: completed || false });
38 return c.json(newTask, 201);
39 } catch (error) {
40 console.log(error);
41 return c.json({ error: 'Failed to create task' }, 500);
42 }
43});
44
45app.put('/tasks/:id', async (c) => {
46 try {
47 const { id } = c.req.param();
48 const { title, completed } = await c.req.json();
49 const updatedTask = await updateTask(Number(id), { title, completed });
50 if (!updatedTask) {
51 return c.json({ error: 'Task not found' }, 404);
52 }
53 return c.json(updatedTask);
54 } catch (error) {
55 return c.json({ error: 'Failed to update task' }, 500);
56 }
57});
58
59app.delete('/tasks/:id', async (c) => {
60 try {
61 const { id } = c.req.param();
62 const success = await deleteTask(Number(id));
63 if (!success) {
64 return c.json({ error: 'Task not found' }, 404);
65 }
66 return c.json({ message: 'Task deleted' });
67 } catch (error) {
68 return c.json({ error: 'Failed to delete task' }, 500);
69 }
70});
71
72export default app;

O arquivo cobre cinco rotas:

Método e caminhoResultado
GET /tasksRetorna todas as tarefas como um array JSON.
GET /tasks/:idRetorna uma tarefa ou 404 com { "error": "Task not found" }.
POST /tasksCria uma tarefa a partir de title e completed e a retorna com 201.
PUT /tasks/:idAtualiza title e completed e retorna a tarefa armazenada.
DELETE /tasks/:idRemove a tarefa e retorna { "message": "Task deleted" }.

6. Exporte o handler da função

Azion executa o handler ES Modules: um objeto com um método fetch, exportado como default do arquivo de entrada. Hono fornece esse método na instância do app. Para o padrão e a alternativa legada que ele substitui, consulte Migre padrões de handler em Functions.

Substitua o conteúdo de src/index.ts:

TypeScript
01import app from './app';
02
03export default app;

O arquivo de entrada exporta o app, então cada requisição chega ao roteador Hono, que a compara com as cinco rotas.

7. Faça o deploy do projeto

Execute o comando de deploy a partir do diretório do projeto:

azion deploy

Azion abre Azion Console no navegador, onde os logs do deployment rodam até o build terminar. Se o navegador não abrir, siga o link que a CLI imprime.

Azion constrói o projeto e faz o deploy na Azion Web Platform. O deployment retorna um domínio de workload no formato https://xxxxxxx.map.azionedge.net. A propagação leva alguns minutos, então espere antes de enviar a primeira requisição.

8. Verifique os endpoints

Substitua <your-azion-domain> pelo domínio de workload do deployment.

Solicite a lista de tarefas
curl https://<your-azion-domain>/tasks

A resposta traz as três linhas inseridas na tabela:

JSON
01[
02 { "id": 1, "title": "Complete API documentation", "completed": false },
03 { "id": 2, "title": "Test function deployment", "completed": false },
04 { "id": 3, "title": "Review security configurations", "completed": true }
05]
Solicite uma tarefa
curl https://<your-azion-domain>/tasks/1

A resposta traz um único objeto:

{ "id": 1, "title": "Complete API documentation", "completed": false }
Crie uma tarefa
Shell
01curl -X POST https://<your-azion-domain>/tasks \
02 -H "Content-Type: application/json" \
03 -d '{"title": "Write the deployment checklist", "completed": false}'

A resposta retorna 201 com a tarefa armazenada e o identificador que o banco de dados atribuiu:

{ "title": "Write the deployment checklist", "completed": false, "id": 4 }
Atualize a tarefa
Shell
01curl -X PUT https://<your-azion-domain>/tasks/4 \
02 -H "Content-Type: application/json" \
03 -d '{"title": "Write the deployment checklist", "completed": true}'

A resposta traz a tarefa com os novos valores:

{ "id": 4, "title": "Write the deployment checklist", "completed": true }
Exclua a tarefa
curl -X DELETE https://<your-azion-domain>/tasks/4

A resposta confirma a remoção:

{ "message": "Task deleted" }

A API cria, lê, atualiza e exclui tarefas pela função em execução. Cada escrita chega ao banco de dados.

Próximos passos

SQL DatabaseO banco de dados compatível com ACID por trás da API, sua arquitetura e seus limites.FunctionsO que é uma função, como ela é invocada e o que ela alcança durante a execução.Migre padrões de handler em FunctionsO handler ES Modules, o handler Service Worker e os padrões que Azion rejeita.Biblioteca SQL da AzionTodos os métodos de azion/sql, com seus parâmetros e tipos de retorno.Desenvolvimento localRode o projeto na sua própria máquina com o comando azion dev.Solução de problemas de execução e logs de funçõesEncontre a causa quando a função não roda, para antes do tempo ou não escreve logs.