Sirva uma API REST de uma function apoiada no SQL Database

Implante uma function que serve todos os endpoints de uma API REST, lê o SQL Database por uma réplica e guarda a resposta de lista em cache.

Última atualização

Ver como Markdown Configurar agente

Você implanta, com a Azion CLI, uma function que serve todos os endpoints de uma API REST sob /api/tasks: ela lê as linhas do SQL Database por uma read replica, grava-as pela Azion API e mantém a resposta de lista em cache por 60 segundos. Para adicionar gravações a uma function que você já executa, consulte Grave linhas no SQL Database a partir de uma function.

Pré-requisitos

  • SQL Database habilitado na sua conta e a permissão Edit SQL Database. O produto está em Preview, então solicite acesso pelo Technical Support.
  • Um banco de dados chamado tasks-api, o seu identificador e a tabela tasks com duas linhas. O identificador é o id que a resposta de criação retorna. Para criá-los, consulte Crie um banco de dados usando a API e Crie tabelas e consulte dados.
  • O identificador do banco de dados e um personal token armazenados como as variáveis de ambiente TASKS_DB_ID e TASKS_SQL_TOKEN, como Armazene o identificador do banco de dados e o token mostra. Uma variável só chega à function depois de um deploy, então crie as duas antes do deploy.
  • A Azion CLI instalada, com o seu personal token salvo. Para configurá-la, consulte Primeiros passos com a Azion CLI.
  • Node.js e um gerenciador de pacotes, que a CLI usa para construir o projeto.

A function lê uma tabela criada com CREATE TABLE IF NOT EXISTS tasks (id INTEGER PRIMARY KEY AUTOINCREMENT, title TEXT NOT NULL, completed INTEGER NOT NULL DEFAULT 0);, com as linhas que INSERT INTO tasks (title, completed) VALUES ('Write the API spec', 0); e INSERT INTO tasks (title, completed) VALUES ('Deploy the API', 1); adicionam. completed é uma coluna inteira, 0 ou 1, porque a function a lê como número. Os exemplos chamam a API em api.example.com. Substitua esse domínio pelo que o deploy exibe, e os nomes pelos seus.

Escreva a function da API

A function é um handler ES Modules que implementa todos os endpoints sob /api/tasks. Ela lê com a classe Database do global Azion.Sql, envia cada gravação ao endpoint de query da Azion API com TASKS_DB_ID e TASKS_SQL_TOKEN e guarda a resposta de lista no cache tasks-api sob max-age=60. Todo POST e todo DELETE apaga essa lista guardada depois da gravação.

Para criar o projeto e adicionar a function:

Crie o projeto

Execute azion init, insira tasks-api como nome e selecione o preset Javascript e o template Hello World, como Faça o deploy de uma function com a Azion CLI mostra. Depois, vá para o diretório do projeto.

Substitua o handler

Substitua o conteúdo de index.js, o entrypoint que o build lê, pelo código abaixo.

JavaScript
01const { Database } = Azion.Sql;
02
03const DATABASE_NAME = 'tasks-api';
04const CACHE_NAME = 'tasks-api';
05const LIST_MAX_AGE = 60;
06
07function json(body, status = 200, headers = {}) {
08 return new Response(JSON.stringify(body), {
09 status,
10 headers: { 'content-type': 'application/json', ...headers },
11 });
12}
13
14// Reads come from a read replica. Integer parameters bind; string parameters are refused.
15async function readTasks(id) {
16 const connection = await Database.open(DATABASE_NAME);
17 const rows = id === undefined
18 ? await connection.query('SELECT id, title, completed FROM tasks ORDER BY id')
19 : await connection.query('SELECT id, title, completed FROM tasks WHERE id = ?', [id]);
20 const tasks = [];
21 let row = await rows.next();
22 while (row) {
23 tasks.push({ id: row.getValue(0), title: row.getValue(1), completed: row.getValue(2) === 1 });
24 row = await rows.next();
25 }
26 return tasks;
27}
28
29// Writes go to the main instance through the Azion API. A failed statement still answers 200.
30async function writeTasks(statement) {
31 const response = await fetch(
32 `https://api.azion.com/v4/workspace/sql/databases/${Azion.env.get('TASKS_DB_ID')}/query`,
33 {
34 method: 'POST',
35 headers: {
36 Accept: 'application/json',
37 Authorization: `Token ${Azion.env.get('TASKS_SQL_TOKEN')}`,
38 'Content-Type': 'application/json',
39 },
40 body: JSON.stringify({ statements: [statement] }),
41 },
42 );
43 if (!response.ok) {
44 throw new Error(`Azion API answered ${response.status}`);
45 }
46 const entry = (await response.json()).data[0];
47 if (entry.error) {
48 throw new Error(entry.error);
49 }
50 return entry.results;
51}
52
53// The query endpoint takes SQL strings, so a text value is quoted and its quotes doubled.
54function sqlText(value) {
55 return `'${String(value).replaceAll("'", "''")}'`;
56}
57
58export default {
59 async fetch(request) {
60 const url = new URL(request.url);
61 const match = url.pathname.match(/^\/api\/tasks(?:\/(\d+))?$/);
62 if (!match) {
63 return json({ error: 'Not found' }, 404);
64 }
65 const id = match[1] === undefined ? undefined : Number(match[1]);
66 const cache = await caches.open(CACHE_NAME);
67 const listKey = `${url.origin}/api/tasks`;
68
69 try {
70 if (request.method === 'GET' && id === undefined) {
71 const cached = await cache.match(listKey);
72 if (cached) {
73 return cached;
74 }
75 const list = json(await readTasks(), 200, {
76 'cache-control': `max-age=${LIST_MAX_AGE}`,
77 'x-tasks-cached-at': new Date().toISOString(),
78 });
79 await cache.put(listKey, list.clone());
80 return list;
81 }
82 if (request.method === 'GET') {
83 const [task] = await readTasks(id);
84 return task ? json(task) : json({ error: 'Task not found' }, 404);
85 }
86 if (request.method === 'POST' && id === undefined) {
87 const { title, completed = false } = await request.json();
88 if (typeof title !== 'string' || title.length === 0) {
89 return json({ error: 'title is required' }, 400);
90 }
91 const results = await writeTasks(
92 `INSERT INTO tasks (title, completed) VALUES (${sqlText(title)}, ${completed ? 1 : 0}) RETURNING id`,
93 );
94 await cache.delete(listKey);
95 return json({ id: results.rows[0][0], title, completed: Boolean(completed) }, 201);
96 }
97 if (request.method === 'DELETE' && id !== undefined) {
98 const results = await writeTasks(`DELETE FROM tasks WHERE id = ${id}`);
99 await cache.delete(listKey);
100 return results.rows_written > 0
101 ? json({ message: 'Task deleted' })
102 : json({ error: 'Task not found' }, 404);
103 }
104 return json({ error: 'Method not allowed' }, 405);
105 } catch (error) {
106 console.log(error.message);
107 return json({ error: 'Internal error' }, 500);
108 }
109 },
110};

O index.js do projeto agora tem a function da API. Um caminho fora de /api/tasks responde 404, um método que a function não trata responde 405, e uma gravação que falha responde 500 e registra a mensagem dela no log.

O caso de uso Criar APIs REST e GraphQL usa os valores deste exemplo.

Implante a API

Uma function serve todos os endpoints, então um deploy publica todos juntos. Para implantar a API, execute azion deploy no diretório do projeto. O comando constrói o projeto, cria a aplicação e a function, instancia a function e exibe o domínio que a serve. Para a saída do comando, consulte Faça o deploy do projeto.

A API responde no domínio que o deploy exibiu, todos os endpoints rodam na function, e a resposta de lista fica em cache por 60 segundos. O primeiro deploy pode levar vários minutos para responder em todas as localidades.

O caso de uso Criar APIs REST e GraphQL usa os valores deste exemplo.

Confirme que a API responde

Cada verificação chama a API no domínio dela. Um primeiro deploy que ainda não responde ainda está se propagando; espere alguns minutos e tente de novo.

  • O endpoint de lista lê o banco de dados. Requisite a lista:

    curl -i https://api.example.com/api/tasks

    A resposta traz 200 e as duas linhas que a tabela guarda:

    [{"id":1,"title":"Write the API spec","completed":false},{"id":2,"title":"Deploy the API","completed":true}]

  • A lista vem da cópia em cache. Repita a requisição em até 60 segundos. O header x-tasks-cached-at traz o mesmo valor da primeira resposta.

  • Uma gravação chega ao banco de dados. Crie uma tarefa:

    Shell
    01curl -i -X POST https://api.example.com/api/tasks \
    02 -H "Content-Type: application/json" \
    03 -d '{"title": "Review the logs"}'

    A resposta traz 201 e o ID que o banco de dados atribuiu:

    {"id":3,"title":"Review the logs","completed":false}

    Um 500 aqui significa que a gravação falhou. Leia a mensagem que a function registrou no log, como Consultar logs de console de uma function mostra: Azion API answered 401 aponta para o valor de TASKS_SQL_TOKEN, e uma mensagem de erro do banco de dados aponta para o statement.

  • Uma gravação atualiza a lista. Requisite a lista de novo. A resposta traz um novo valor de x-tasks-cached-at e três tarefas.

  • Uma tarefa inexistente responde 404. Apague a mesma tarefa duas vezes:

    curl -X DELETE https://api.example.com/api/tasks/3

    A primeira chamada responde {"message":"Task deleted"}, e a segunda responde 404 com {"error":"Task not found"}.

A API lê, grava e apaga tarefas, e serve a lista pela cópia em cache entre uma gravação e outra.

Estas verificações confirmam o caso de uso Criar APIs REST e GraphQL.

Próximos passos

Armazene em cache a resposta de uma function com a Cache APIComo a chave, o max-age e a exclusão depois de uma gravação mantêm a resposta de lista atualizada.Criar APIs REST e GraphQLO design que esta function implementa, com as medições que mostram que ele funciona.