Compilare un'API RESTful Node.js e distribuirla a un'app per le API in Azure

Questa guida introduttiva illustra come creare un'API REST, scritta con Node.js Express, usando una definizione Swagger e distribuirla in Azure come un'app per le API. Si creerà l'app usando gli strumenti da riga di comando, si configureranno le risorse con l'interfaccia della riga di comando di Azure e si distribuirà l'app tramite Git. Al termine, si avrà un'API REST di esempio in esecuzione in Azure.

Prerequisiti

Se non si ha una sottoscrizione di Azure, creare un account gratuito prima di iniziare.

Avviare Azure Cloud Shell

Azure Cloud Shell è una shell Bash gratuita che può essere eseguita direttamente nel portale di Azure. Include l'interfaccia della riga di comando di Azure preinstallata e configurata per l'uso con l'account. Fare clic sul pulsante Cloud Shell nel menu nel riquadro in alto a destra nel portale di Azure.

Cloud Shell

Il pulsante avvia una shell interattiva che è possibile usare per eseguire tutti i passaggi in questo argomento:

Screenshot che mostra la finestra di Cloud Shell nel portale

Se si sceglie di installare e usare l'interfaccia della riga di comando in locale, per questo argomento è necessario eseguire la versione 2.0 o successiva dell'interfaccia della riga di comando di Azure. Eseguire az --version per trovare la versione. Se è necessario eseguire l'installazione o l'aggiornamento, vedere Installare l'interfaccia della riga di comando di Azure 2.0.

Preparare l'ambiente

  1. In una finestra del terminale eseguire il comando seguente per clonare il codice di esempio nel computer locale.

    git clone https://github.com/Azure-Samples/app-service-api-node-contact-list
    
  2. Passare alla directory contenente il codice di esempio.

    cd app-service-api-node-contact-list
    
  3. Installare Swaggerize nel computer locale. Swaggerize è uno strumento che genera codice Node.js per l'API REST da una definizione Swagger.

    npm install -g yo
    npm install -g generator-swaggerize
    

Generare codice Node.js

In questa sezione dell'esercitazione viene modellato un flusso di lavoro di sviluppo di API che crea prima i metadati di Swagger e li usa per lo scaffolding (generazione automatica) del codice server per l'API.

Modificare la directory per impostarla sulla cartella di avvio e quindi eseguire yo swaggerize. Swaggerize crea un progetto Node.js per l'API dalla definizione Swagger in api.json.

cd start
yo swaggerize --apiPath api.json --framework express

Quando Swaggerize chiede un nome di progetto, usare ContactList.

Swaggerize Generator
Tell us a bit about your application
? What would you like to call this project: ContactList
? Your name: Francis Totten
? Your github user name: fabfrank
? Your email: frank@fabrikam.net

Personalizzare il codice del progetto

  1. Copiare la cartella lib nella cartella ContactList creata da yo swaggerize e quindi modificare la directory in ContactList.

    cp -r lib/ ContactList/
    cd ContactList
    
  2. Installare i moduli NPM jsonpath e swaggerize-ui.

    npm install --save jsonpath swaggerize-ui
    
  3. Sostituire il codice nel file handlers/contacts.js con il codice seguente:

    'use strict';
    
    var repository = require('../lib/contactRepository');
    
    module.exports = {
        get: function contacts_get(req, res) {
            res.json(repository.all())
        }
    };
    

    Questo codice usa i dati JSON archiviati nel file lib/contacts.json servito da lib/contactRepository.js. Il nuovo codice contacts.js restituisce tutti i contatti nel repository come un payload JSON.

  4. Sostituire il codice nel file handlers/contacts/{id}.js con il codice seguente:

    'use strict';
    
    var repository = require('../../lib/contactRepository');
    
    module.exports = {
        get: function contacts_get(req, res) {
            res.json(repository.get(req.params['id']));
        }    
    };
    

    Questo codice consente di usare una variabile di percorso per restituire solo il contatto con un ID specifico.

  5. Sostituire il codice nel file server.js con il codice seguente:

    'use strict';
    
    var port = process.env.PORT || 8000; 
    
    var http = require('http');
    var express = require('express');
    var bodyParser = require('body-parser');
    var swaggerize = require('swaggerize-express');
    var swaggerUi = require('swaggerize-ui'); 
    var path = require('path');
    var fs = require("fs");
    
    fs.existsSync = fs.existsSync || require('path').existsSync;
    
    var app = express();
    
    var server = http.createServer(app);
    
    app.use(bodyParser.json());
    
    app.use(swaggerize({
        api: path.resolve('./config/swagger.json'),
        handlers: path.resolve('./handlers'),
        docspath: '/swagger' 
    }));
    
    // change four
    app.use('/docs', swaggerUi({
        docs: '/swagger'  
    }));
    
    server.listen(port, function () { 
    });
    

    Questo codice introduce alcune piccole modifiche che consentono di usarlo con il servizio app di Azure ed espone un'interfaccia Web interattiva per l'API.

Testare l'API in locale

  1. Avviare l'app Node.js

    npm start
    
  2. Accedere a http://localhost:8000/contacts per visualizzare il codice JSON per l'intero elenco di contatti.

     {
         "id": 1,
         "name": "Barney Poland",
         "email": "barney@contoso.com"
     },
     {
         "id": 2,
         "name": "Lacy Barrera",
         "email": "lacy@contoso.com"
     },
     {
         "id": 3,
         "name": "Lora Riggs",
         "email": "lora@contoso.com"
     }
    
  3. Accedere a http://localhost:8000/contacts/2 per visualizzare il contatto con un id su due.

    { 
        "id": 2,
        "name": "Lacy Barrera",
        "email": "lacy@contoso.com"
    }
    
  4. Testare l'API usando l'interfaccia Web di Swagger all'indirizzo http://localhost:8000/docs.

    Interfaccia Web di Swagger

Creare un'app per le API

In questa sezione si usa l'interfaccia della riga di comando di Azure 2.0 per creare le risorse necessarie per ospitare l'API nel servizio app di Azure.

  1. Accedere alla sottoscrizione di Azure con il comando az login e seguire le istruzioni visualizzate.

    az login
    
  2. Se sono presenti più sottoscrizioni di Azure, cambiare la sottoscrizione predefinita specificando quella da usare.

    az account set --subscription <name or id>
    
  3. Creare un gruppo di risorse con il comando az group create.

    Un gruppo di risorse è un contenitore logico in cui vengono distribuite e gestite risorse di Azure come app Web, database e account di archiviazione.

    L'esempio seguente crea un gruppo di risorse denominato myResourceGroup nella località westeurope.

    az group create --name myResourceGroup --location westeurope
    

    Per visualizzare le posizioni disponibili, eseguire il comando az appservice list-locations. In genere si creano risorse in un'area nelle vicinanze.

  4. Creare un piano di servizio app con il comando az appservice plan create.

    Un piano di servizio app specifica la località, le dimensioni e le funzionalità della server farm Web che ospita l'app. Quando si ospitano più app, è possibile limitare i costi configurando le app Web in modo che condividano un singolo piano di servizio app.

    I piani di servizio app definiscono:

    • Area (ad esempio Europa settentrionale, Stati Uniti orientali o Asia sud-orientale)
    • Dimensione dell'istanza (Small, Medium o Large)
    • Numero di scala (da 1 a 20 istanze)
    • SKU (Gratuito, Condiviso, Basic, Standard o Premium)

    L'esempio seguente crea un piano di servizio app denominato myAppServicePlan nel piano tariffario Gratuito:

    az appservice plan create --name myAppServicePlan --resource-group myResourceGroup --sku FREE
    

    Al termine della creazione del piano di servizio app, l'interfaccia della riga di comando di Azure visualizza informazioni simili all'esempio seguente:

    { 
      "adminSiteName": null,
      "appServicePlanName": "myAppServicePlan",
      "geoRegion": "West Europe",
      "hostingEnvironmentProfile": null,
      "id": "/subscriptions/0000-0000/resourceGroups/myResourceGroup/providers/Microsoft.Web/serverfarms/myAppServicePlan",
      "kind": "app",
      "location": "West Europe",
      "maximumNumberOfWorkers": 1,
      "name": "myAppServicePlan",
      < JSON data removed for brevity. >
      "targetWorkerSizeId": 0,
      "type": "Microsoft.Web/serverfarms",
      "workerTierName": null
    } 
    
  5. Creare un'app per le API nel piano di servizio app myAppServicePlan con il comando az webapp create.

    L'app Web fornisce uno spazio host per l'API e un URL per visualizzare l'app distribuita.

    Nel comando seguente sostituire <nome_app> con un nome univoco. Se <app_name> non è univoco, verrà visualizzato il messaggio di errore "Il sito Web con il nome specificato esiste già". L'URL predefinito dell'app Web è https://<app_name>.azurewebsites.net.

    az webapp create --name <app_name> --resource-group myResourceGroup --plan myAppServicePlan
    

    Al termine della creazione dell'app Web, l'interfaccia della riga di comando di Azure visualizza informazioni simili all'esempio seguente:

    {
      "availabilityState": "Normal",
      "clientAffinityEnabled": true,
      "clientCertEnabled": false,
      "cloningInfo": null,
      "containerSize": 0,
      "dailyMemoryTimeQuota": 0,
      "defaultHostName": "<app_name>.azurewebsites.net",
      "enabled": true,
      "enabledHostNames": [
        "<app_name>.azurewebsites.net",
        "<app_name>.scm.azurewebsites.net"
      ],
      "gatewaySiteName": null,
      "hostNameSslStates": [
        {
          "hostType": "Standard",
          "name": "<app_name>.azurewebsites.net",
          "sslState": "Disabled",
          "thumbprint": null,
          "toUpdate": null,
          "virtualIp": null
        }
        < JSON data removed for brevity. >
    }
    

Distribuire l'API con Git

Distribuire il codice nell'app per le API effettuando il push dei commit dal repository Git locale al servizio app di Azure.

  1. Creare credenziali di distribuzione con il comando az webapp deployment user set.

    Un utente della distribuzione è necessario per la distribuzione con FTP e l'istanza Git locale in un'app Web. Nome utente e password sono a livello di account. Sono quindi diversi dalle credenziali della sottoscrizione di Azure.

    Nel comando seguente sostituire <user-name> e <password> con un nuovo nome utente e una nuova password. Il nome utente deve essere univoco. La password deve essere composta da almeno otto caratteri, con due dei tre elementi seguenti: lettere, numeri e simboli.

    az webapp deployment user set --user-name <username> --password <password>
    

    Se viene visualizzato un errore 'Conflict'. Details: 409, modificare il nome utente. Se viene visualizzato un errore 'Bad Request'. Details: 400, usare una password più complessa.

    L'utente di distribuzione viene creato una sola volta e può essere usato per tutte le distribuzioni di Azure.

    Nota

    Registrare il nome utente e la password. Saranno necessari per distribuire l'app Web in un secondo momento.

  2. Inizializzare un nuovo repository nella directory ContactList.

    git init .
    
  3. Escludere la directory node_modules creata da npm in un passaggio precedente dell'esercitazione in Git. Creare un nuovo file .gitignore nella directory corrente e aggiungere il testo seguente in una nuova riga in un punto qualsiasi del file.

    node_modules/
    

    Confermare che la cartella node_modules venga ignorata con git status.

  4. Eseguire il commit delle modifiche nel repository.

    git add .
    git commit -m "initial version"
    
  5. Usare l'interfaccia della riga di comando di Azure per ottenere l'URL della distribuzione remota per l'app per le API. Nel comando seguente sostituire <nome_app> con il nome dell'app Web.

    az webapp deployment source config-local-git --name <app_name> --resource-group myResourceGroup --query url --output tsv
    

    Configurare la distribuzione Git locale per consentire il push nel computer remoto.

    git remote add azure <URI from previous step>
    

    Effettuare il push all'istanza remota di Azure per distribuire l'app. Verrà richiesta la password creata in precedenza quando è stato creato l'utente della distribuzione. Assicurarsi di immettere la password creata in un passaggio precedente della guida introduttiva, anziché quella usata per accedere al portale di Azure.

    git push azure master
    

Testare l'API in Azure

  1. Aprire una finestra del browser all'indirizzo http://app_name.azurewebsites.net/contacts. Verrà visualizzato lo stesso codice JSON restituito quando è stata eseguita la richiesta in locale in un passaggio precedente dell'esercitazione.

    {
        "id": 1,
        "name": "Barney Poland",
        "email": "barney@contoso.com"
    },
    {
        "id": 2,
        "name": "Lacy Barrera",
        "email": "lacy@contoso.com"
    },
    {
        "id": 3,
        "name": "Lora Riggs",
        "email": "lora@contoso.com"
    }
    
  2. In un browser accedere all'endpoint http://app_name.azurewebsites.net/docs per provare l'interfaccia utente di Swagger in esecuzione in Azure.

    Interfaccia utente di Swagger

    È ora possibile distribuire gli aggiornamenti nell'API di esempio in Azure eseguendo il push dei commit nel repository Git di Azure.

Eseguire la pulizia

Per eliminare tutte le risorse create nella presente guida introduttiva, eseguire questo comando dell'interfaccia della riga di comando di Azure:

az group delete --name myResourceGroup

Passaggio successivo