Costruisci un accorciatore di URL con Neon e Azure Serverless Functions

Neon è ora disponibile nel marketplace di Azure. La nuova integrazione tra Neon e Azure ti consente di gestire il tuo abbonamento e la fatturazione di Neon tramite il portale di Azure come se Neon fosse un prodotto di Azure. Azure serverless e Neon sono una combinazione naturale: Azure serverless ti libera dalla gestione della tua infrastruttura di server web. Neon fa lo stesso per i database, offrendo funzionalità aggiuntive come il branching dei dati e le estensioni per database vettoriali.

Detto ciò, proviamo questa nuova integrazione costruendo un’API per accorciare URL utilizzando Neon, Azure serverless e Node.js.

Nota: Dovresti avere accesso a un terminale, a un editor come VS Code e a Node v22 o successivo installato.

Impostazione dell’infrastruttura

Dovremo fare le cose un po’ al contrario oggi. Invece di scrivere il codice, prima imposteremo la nostra funzione serverless e il database.

Passo 1. Apri il portale web di Azure. Se non ne hai già uno, dovrai creare un account Microsoft.

Passo 2. Dovrai anche creare un abbonamento se non ne hai già uno, il che puoi fare in Azure.

Passo 3. Ora possiamo creare un gruppo di risorse per memorizzare la nostra funzione serverless e il database. Vai alla nuova pagina del gruppo di risorse di Azure e compila il modulo in questo modo:

• Questa è la pagina di creazione del gruppo di risorse di Azure con il gruppo di risorse impostato su “AzureNeonURLShortener” e la posizione impostata su West US 3.
• In generale, utilizza la posizione più vicina a te e ai tuoi utenti, poiché la posizione determinerà la posizione predefinita delle funzioni serverless e quali aree hanno la latenza più bassa. Non è essenziale in questo esempio, ma puoi cercare tramite il menu a discesa se desideri utilizzarne un’altra. Tuttavia, nota che Neon non ha ancora sedi in tutte queste regioni, il che significa che dovresti posizionare il tuo database in una regione più distante dalla tua funzione serverless.

Passo 4. Clicca su “Rivedi e Crea” in basso per accedere a una pagina di revisione della configurazione. Quindi clicca nuovamente su “Crea”.

Passo 5. Ora possiamo creare una funzione serverless. Purtroppo, include un altro modulo. Vai alla pagina di creazione dell’app serverless Azure Flex Consumption e completa il modulo. Utilizza il gruppo di risorse creato in precedenza, scegli un nome univoco per la funzione serverless, posiziona la funzione nella regione del tuo gruppo di risorse e utilizza Node v20.

Passaggio 6. Il nome che scegli per la tua app serverless sarà il sottodominio che Azure ti fornisce per accedere alla tua API, quindi scegli saggiamente. Dopo aver completato tutto, fai clic su “Revisiona e Crea” e infine su “Crea”. Azure dovrebbe reindirizzarti alla pagina della nuova app. Ora possiamo configurare Neon. Apri la nuova pagina delle risorse di Neon sul portale di Azure e, indovina un po’, compila il modulo.

Come Creare un Database Neon su Azure

Passaggio 1. Crea una nuova pagina delle risorse di Neon con “AzureURLNeonShortener” come gruppo di risorse, “URLShortenerDB” come nome della risorsa e “West US 3” come posizione. Se l’area che hai scelto non è disponibile, scegli la regione più vicina successiva. Una volta completato tutto, fai clic su “Revisiona e Crea” e poi su “Crea”, come hai fatto per le risorse precedenti.

Passaggio 2. Potresti dover attendere un po’ affinché il database Neon si istanzi. Una volta fatto ciò, apri la sua pagina di configurazione e fai clic su “Vai a Neon.”

Passaggio 3. Sarai reindirizzato a una pagina di accesso. Consenti a Neon di accedere alle tue informazioni di Azure e quindi ti troverai su una pagina di creazione del progetto. Compila il modulo qui sotto:

Il nome del progetto e del database non è significativo, ma assicurati di posizionare il database in Azure West US 3 (o in qualsiasi altra regione tu scelga). Ciò eviterà che le query al database lascino il data center, riducendo la latenza.

Passo 4. Fare clic su “Crea” in fondo alla pagina, mantenendo la configurazione predefinita dell’autoscaling. Ora dovresti essere reindirizzato a una pagina del database Neon. Questa pagina contiene la nostra stringa di connessione, di cui avremo bisogno per connetterci al nostro database dal nostro codice. Fare clic su “Copia frammento” per copiare la stringa di connessione.

Assicurati di non perderla, poiché ne avremo bisogno più avanti, ma per ora dobbiamo strutturare il nostro database. 

Passo 5. Fare clic su “SQL Editor” nella navigazione laterale e incollare il seguente SQL:

CREATE TABLE IF NOT EXISTS urls(id char(12) PRIMARY KEY, url TEXT NOT NULL);

Quindi fare clic su “Esegui”. Questo creerà la tabella che utilizzeremo per memorizzare gli URL. La tabella è piuttosto semplice: La chiave primaria ID è una stringa casuale di 12 caratteri che useremo per fare riferimento agli URL, e l’URL è una stringa di lunghezza variabile che memorizzerà lo stesso URL.

Passo 6. Se guardi la vista della tabella nella navigazione laterale, dovresti vedere una tabella “urls”. Infine, dobbiamo ottenere la nostra stringa di connessione. Fare clic su “Dashboard” nella barra laterale, trovare la stringa di connessione e fare clic su “Copia frammento”.

Ora possiamo iniziare a scrivere il codice.

Costruire l’API

Passo 1. Prima di tutto, dobbiamo installare la CLI serverless di Azure, che ci aiuterà a creare un progetto e alla fine testarlo/pubblicarlo. Aprire un terminale e eseguire:

npm install -g azure-functions-core-tools --unsafe-perm true

Passo 2. Se si desidera utilizzare altri gestori di pacchetti come Yarn o pnpm, sostituire semplicemente npm con il gestore di pacchetti preferito. Ora possiamo iniziare sul nostro progetto effettivo. Aprire la cartella in cui si desidera che il progetto sia e eseguire i seguenti tre comandi:

func init --javascript

func new --name submit --template "HTTP trigger"

func new --name url --template "HTTP trigger"

npm install nanoid @neondatabase/serverless

Ora dovresti vedere un nuovo progetto Azure in quella cartella. Il primo comando crea il progetto, i due comandi successivi creano le nostre route API serverless, e il comando finale installa il driver serverless Neon per interfacciarsi con il nostro database e Nano ID per generare ID. Potremmo utilizzare un driver standard di Postgres invece del driver Neon, ma il driver di Neon utilizza query HTTP stateless per ridurre la latenza per query singole. Poiché stiamo eseguendo una funzione serverless che potrebbe elaborare solo una richiesta e inviare una sola query, la latenza per query singole è importante.

Dovresti concentrarti sul codice in src/functions, poiché è lì che si trovano le nostre route. Dovresti vedere due file lì: submit.js e redirect.js.

submit.js

submit.js conterrà il codice che useremo per inviare URL. Per prima cosa, apri submit.js e sostituisci il suo codice con il seguente:

import { app } from "@azure/functions";

import { neon } from "@neondatabase/serverless";

import { nanoid } from "nanoid";

​

const sql = neon("[YOUR_POSTGRES_CONNECTION_STRING]");

app.http("submit", {

  methods: ["GET"],

  authLevel: "anonymous",

  route: "submit",

  handler: async (request, context) => {

    if (!request.query.get("url"))

      return {

        body: "No url provided",

        status: 400,

      };

    if (!URL.canParse(request.query.get("url")))

      return {

        body: "Error parsing url",

        status: 400,

      };

    const id = nanoid(12);

    await sql`INSERT INTO urls(id,url) VALUES (${id},${request.query.get(

      "url"

    )})`;

    return new Response(`Shortened url created with id ${id}`);

  },

});

Analizziamo questo passo per passo. Prima importiamo l’API delle funzioni Azure, il driver serverless di Neon e Nano ID. Qui stiamo utilizzando ESM (ES Modules) anziché CommonJS. Dovremo apportare alcune modifiche in seguito per supportare questo.

Successivamente, creiamo la connessione al nostro database. Sostituisci [YOUR_POSTGRES_CONNECTION_STRING] con la stringa che hai copiato dalla dashboard di Neon. Per motivi di sicurezza, probabilmente vorresti utilizzare un servizio come Azure Key Vault per gestire le tue chiavi in un ambiente di produzione, ma per ora, inserirle nello script andrà bene.

Ora siamo sulla rotta effettiva. Le prime proprietà definiscono quando il nostro gestore di route dovrebbe essere attivato: vogliamo che questa rotta venga attivata da una richiesta GET a submit.

Il nostro gestore è piuttosto semplice. Controlliamo prima se un URL è stato passato tramite il parametro di query dell’URL (ad es., /submit?url=https://google.com), poi verifichiamo se è un URL valido tramite la nuova API URL.canParse. Successivamente, generiamo l’ID con Nano ID. Poiché i nostri ID sono lunghi 12 caratteri, dobbiamo passare 12 al generatore di Nano ID. Infine, inseriamo una nuova riga con il nuovo ID e URL nel nostro database. Il driver serverless Neon parametrizza automaticamente le query, quindi non dobbiamo preoccuparci di utenti malevoli che passano dichiarazioni SQL nell’URL.

redirect.js

redirect.js è dove avverranno i nostri effettivi reindirizzamenti URL. Sostituisci il suo codice con il seguente:

import { app } from "@azure/functions";

import { neon } from "@neondatabase/serverless";

​

const sql = neon("[YOUR_POSTGRES_CONNECTION_STRING]");

app.http("redirect", {

  methods: ["GET"],

  authLevel: "anonymous",

  route: "{id:length(12)}",

  handler: async (request, context) => {

    const url =

      await sql`SELECT * FROM urls WHERE urls.id=${request.params.id}`;

    if (!url[0]) return new Response("No redirect found", { status: 404 });

    return Response.redirect(url[0].url, 308);

  },

});

La prima sezione dello script è la stessa di submit.js. Ancora una volta, sostituisci \[YOUR\_POSTGRES\_CONNECTION\_STRING\] con la stringa che hai copiato dalla dashboard di Neon.

La rotta è dove le cose diventano più interessanti. Dobbiamo accettare qualsiasi percorso che potrebbe essere un ID di reindirizzamento, quindi utilizziamo un parametro con la restrizione di 12 caratteri. Nota che questo potrebbe sovrapporsi se mai avessi un’altra rotta di 12 caratteri. Se lo fa, puoi rinominare la rotta di reindirizzamento per iniziare con una Z o un altro carattere alfanumerico maggiore per far sì che Azure serverless carichi la rotta di reindirizzamento dopo.

Finalmente, abbiamo il nostro codice di gestione effettivo. Tutto ciò che dobbiamo fare qui è interrogare un URL corrispondente all’ID fornito e reindirizzare ad esso se esiste. Utilizziamo il codice di stato 308 nel nostro reindirizzamento per indicare ai browser e ai motori di ricerca di ignorare l’URL abbreviato originale.

File di configurazione

Ci sono altre due modifiche che dobbiamo apportare. Innanzitutto, non vogliamo un prefisso /api su tutte le nostre funzioni. Per rimuovere questo, apri host.json, che dovrebbe trovarsi nella directory del tuo progetto, e aggiungi il seguente:

"extensions": {

    "http": {

      "routePrefix": ""

    }

  }

Questo consente alle tue route di operare senza nessun prefisso. L’unica altra cosa che dobbiamo fare è passare il progetto a moduli ES. Apri package.json e inserisci il seguente alla fine del file:

"type": "module"

E questo è tutto!

Test e Distribuzione

Ora puoi provare il test localmente eseguendo func start. Puoi navigare su http://localhost:7071/submit?url=https://example.com, quindi utilizza l’ID che ti viene fornito e vai su http://localhost:7071/[YOUR_ID]. Dovresti essere reindirizzato su example.com.

Certo, non possiamo solo eseguire questo localmente. Per distribuire, dobbiamo installare Azure CLI, che puoi fare con uno dei seguenti comandi, a seconda del tuo sistema operativo:

macOS (Homebrew)

brew install azure-cli

Windows (WPM)

winget install -e --id Microsoft.AzureCLI

Linux

curl -L <https://aka.ms/InstallAzureCli> | bash

Ora, riavvia il terminale, accedi eseguendo az login, e esegui quanto segue nella directory del progetto:

func azure functionapp publish [FunctionAppName]

Sostituisci [FunctionAppName] con qualsiasi nome tu abbia dato alla tua funzione in precedenza.

Ora, dovresti essere in grado di accedere alla tua API su [FunctionAppName].azurewebsites.net.

Conclusione

Dovresti ora avere un accorciatore di URL completamente funzionante. Puoi accedere al codice qui e lavorare per aggiungere un front end. Se vuoi continuare a leggere sulle funzionalità di Neon e Azure, ti consigliamo di dare un’occhiata a Branching. In ogni caso, spero che tu abbia imparato qualcosa di utile da questa guida.