构建 Node.js RESTful API 并将它部署到 Azure 中的 API 应用

本快速入门介绍如何使用 Swagger 定义创建以 Node.js Express 编写的 REST API,并在 Azure 上部署它。 使用命令行工具创建应用,使用 Azure CLI 配置资源,并使用 Git 部署该应用。 完成后,即可拥有一个在 Azure 上运行的有效示例 REST API。

先决条件

Note

如果没有 Azure 订阅,可在开始前创建一个试用帐户

如果选择在本地安装并使用 CLI,本主题要求运行 Azure CLI 2.0 版或更高版本。 运行 az --version 即可查找版本。 如果需要进行安装或升级,请参阅安装 Azure CLI 2.0

准备环境

  1. 在终端窗口中,运行以下命令,将示例克隆到本地计算机。

    git clone https://github.com/Azure-Samples/app-service-api-node-contact-list
    
  2. 切换到包含示例代码的目录。

    cd app-service-api-node-contact-list
    
  3. 在本地计算机上安装 Swaggerize。 Swaggerize 是一种工具,用于从 Swagger 定义生成用于 REST API 的 Node.js 代码。

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

生成 Node.js 代码

本教程部分为 API 开发工作流建模,将在其中先创建 Swagger 元数据,然后以此创建(自动生成)API 服务器代码基架。

将目录更改为 start 文件夹,然后运行 yo swaggerize。 Swaggerize 从 api.json 中的 Swagger 定义创建用于 API 的 Node.js 项目。

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

当 Swaggerize 请求提供项目名称时,请使用 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

自定义项目代码

  1. lib 文件夹复制到 yo swaggerize 创建的 ContactList 文件夹,然后将目录更改为 ContactList

    cp -r lib/ ContactList/
    cd ContactList
    
  2. 安装 jsonpathswaggerize-ui NPM 模块。

    npm install --save jsonpath swaggerize-ui
    
  3. handlers/contacts.js 中的代码替换为以下代码:

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

    此代码使用 lib/contactRepository.js 提供的 lib/contacts.json 中存储的 JSON 数据。 新的 contacts.js 代码将存储库中的所有联系人返回为 JSON 有效负载形式。

  4. handlers/contacts/{id}.js 文件中的代码替换为以下代码:

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

    此代码允许使用路径变量仅返回具有给定 ID 的联系人。

  5. server.js 中的代码替换为以下代码:

    '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 () { 
    });
    

    此代码进行了一些小的更改,可与 Azure 应用服务配合使用,并公开一个用于 API 的交互式 Web 界面。

在本地测试 API

  1. 启动 Node.js 应用

    npm start
    
  2. 浏览到 http://localhost:8000/contacts,查看整个联系人列表的 JSON。

     {
         "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. 浏览到 http://localhost:8000/contacts/2,查看具有两个 id 中其中一个的联系人。

    { 
        "id": 2,
        "name": "Lacy Barrera",
        "email": "lacy@contoso.com"
    }
    
  4. http://localhost:8000/docs 使用 Swagger Web 界面测试 API。

    Swagger Web 界面

创建 API 应用

本部分将使用 Azure CLI 2.0 创建在 Azure 应用服务上托管 API 的资源。

  1. 使用 az login 命令登录到 Azure 订阅,并按照屏幕上的说明进行操作。

    az login
    
  2. 如果有多个 Azure 订阅,则可将默认订阅更改为所需订阅。

    az account set --subscription <name or id>
    
  3. 使用 az group create 命令创建资源组。

    资源组是在其中部署和管理 Azure 资源(例如 Web 应用、数据库和存储帐户)的逻辑容器。

    以下示例在“chinanorth”位置创建名为“myResourceGroup”的资源组。

    az group create --name myResourceGroup --location chinanorth
    

    若要查看可用位置,请运行 az appservice list-locations 命令。 通常在附近的区域中创建资源。

  4. 使用 az appservice plan create 命令创建应用服务计划。

    Note

    应用服务计划表示用于托管应用的物理资源集合。 分配到应用服务计划的所有应用程序将共享该计划定义的资源。 托管多个应用时,此共享可让你节省资金。

    应用服务计划定义:

    • 区域(中国东部和中国北部)。
    • 实例大小(小、中、大)
    • 规模计数(默认情况为 1 到 20 个实例)
    • SKU(免费、共享、基本、标准、高级)

    以下示例在免费定价层中创建名为 myAppServicePlan 的应用服务计划:

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

    创建应用服务计划后,Azure CLI 将显示类似于以下示例的信息:

    { 
      "adminSiteName": null,
      "appServicePlanName": "myAppServicePlan",
      "geoRegion": "China North",
      "hostingEnvironmentProfile": null,
      "id": "/subscriptions/0000-0000/resourceGroups/myResourceGroup/providers/Microsoft.Web/serverfarms/myAppServicePlan",
      "kind": "app",
      "location": "China North",
      "maximumNumberOfWorkers": 1,
      "name": "myAppServicePlan",
      < JSON data removed for brevity. >
      "targetWorkerSizeId": 0,
      "type": "Microsoft.Web/serverfarms",
      "workerTierName": null
    } 
    
  5. 使用 az webapp create 命令在 myAppServicePlan 应用服务计划中创建应用。

    该 Web 应用为 API 提供托管空间,并提供一个 URL 用于查看已部署的应用。

    在以下命令中,将 <app_name> 替换为唯一名称。 如果 <app_name> 不是唯一名称,将收到错误消息“具有给定名称 <app_name> 的网站已存在”。 Web 应用的默认 URL 为 https://<app_name>.chinacloudsites.cn

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

    创建 Web 应用后,Azure CLI 将显示类似于以下示例的信息:

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

使用 Git 部署 API

通过将提交内容从本地 Git 存储库推送到 Azure 应用服务,将代码部署到 API 应用。

  1. 使用 az webapp deployment user set 命令创建部署凭据。

    在 Web 应用中进行 FTP 和本地 Git 部署时需要一个部署用户。 用户名和密码都为帐户级别。 它们与 Azure 订阅凭据不同。

    在以下命令中,将 <user-name> 和 <password> 替换为新的用户名和密码。 用户名必须唯一。 密码长度必须至少为 8 个字符,其中包含以下 3 种元素中的两种:字母、数字、符号。

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

    如果收到 'Conflict'. Details: 409 错误,请更改用户名。 如果收到 'Bad Request'. Details: 400 错误,请使用更强的密码。

    只创建此部署用户一次;可对所有 Azure 部署使用此用户。

    Note

    记录用户名和密码。 稍后需要使用它们来部署 Web 应用。

  2. 初始化 ContactList 目录中的一个新存储库。

    git init .
    
  3. 从 Git 中排除在教程前面步骤中由 npm 创建的 node_modules 目录。 在当前目录中创建新的 .gitignore 文件,并在文件的任何位置添加新的以下文本行。

    node_modules/
    

    确认已通过 git status 忽略 node_modules 文件夹。

  4. 提交存储库更改。

    git add .
    git commit -m "initial version"
    
  5. 使用 Azure CLI 获取 API 应用的远程部署 URL。 在以下命令中,将 <app_name> 替换为 Web 应用的名称。

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

    配置本地 Git 部署,使之能够推送到远程目标。

    git remote add azure <URI from previous step>
    

    推送到 Azure 远程功能以部署应用。 系统将提示你输入之前创建部署用户时创建的密码。 请确保输入之前在快速入门中创建的密码,而不是用于登录 Azure 门户的密码。

    git push azure master
    

在 Azure 中测试 API

  1. 在浏览器中打开 http://app_name.chinacloudsites.cn/contacts。 返回的 JSON 与本教程之前在本地提发出请求时返回的内容相同。

    {
        "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. 在浏览器中转到 http://app_name.chinacloudsites.cn/docs 终结点,试用在 Azure 中运行的 Swagger UI。

    Swagger Ii

    现在可通过将提交内容推送到 Azure Git 存储库,将示例 API 的更新部署到 Azure。

清理

若要清除此快速入门中创建的资源,请运行以下 Azure CLI 命令:

az group delete --name myResourceGroup

后续步骤