练习 - 在 Visual Studio Code 中创建 Node.js 应用

  • 10 分钟

在本单元中，使用 Visual Studio Code 针对包含资源的 Azure 沙盒生成并运行 Node.js 应用程序。

  • 安装 npm 包，使你能够以编程方式处理 Cosmos DB Core (SQL) 数据库。
  • 编写 JavaScript 代码，将 Contoso 产品数据集上传到容器。

注意

本练习假设已在台式计算机上安装了 Node.js 和 npm，在 Visual Studio Code 中启动了 Learn 沙盒并连接到它。

创建 Node.js 项目

  1. 在需要 Node.js 应用程序的文件夹位置处使用终端。 输入以下命令以在该位置打开 Visual Studio Code。

    code .

  2. 在“终端”菜单上，选择“新终端”，或使用键盘快捷方式 Ctrl + Shift + `。

  3. 在“终端”窗口中，运行以下命令，为 Node 应用程序新建名为 contoso-retail 的文件夹并更改到该文件夹中。

    mkdir contoso-retail && cd contoso-retail

  4. 输入以下命令以转为初始化新的 Node 应用程序。

    npm init -y

    npm init 命令创建 package.json 文件并显示其内容。 此文件包含应用程序的初始元数据，其中包含默认名称、说明和入口点。

  5. 在 Visual Studio Code 的“文件”菜单中，选择“打开文件夹”，然后打开 contoso-retail 文件夹。

  6. 在资源管理器窗口中，选择 package.json 文件。

  7. 在编辑器窗格中，为 package.json 文件更改以下内容：

    属性 值
    type module - 模块的 JavaScript 代码使用 ES6 语法

    该文件应如下所示。 示例代码使用 ES6 语法，因此需要将应用程序的类型设置为 module。

    {
    "name": "contoso-retail",
    "version": "1.0.0",
    "description": "Student and course grades maintenance",
    "main": "index.js",
    "type": "module",
    "scripts": {
        "test": "echo \"Error: no test specified\" && exit 1"
    },
    "keywords": [],
    "author": "",
    "license": "MIT"
}

  8. 在“文件”菜单中，选择“保存”。

配置 Visual Studio Code 以自动保存文件更改

  1. 使用“文件”>“首选项”>“设置”、Ctrl + , 打开自动保存。
  2. 搜索“文件自动保存”。
  3. 为 afterDelay 选择 1000。

创建 .gitignore 文件

.gitignore 文件会防止你将不应添加的文件签入到源代码管理中。

创建名为 .gitignore 的文件 (Ctrl + N)，并向它添加以下内容。

node_modules
.env

创建机密环境文件

  1. 在 Visual Studio Code 的“文件”菜单中，选择“新建文本文件”。

  2. 在“文件”菜单中，选择“另存为”。 保存新文件并将其命名为 .env。

  3. 将以下变量添加到该文件：

    COSMOS_CONNECTION_STRING=
COSMOS_DATABASE_NAME=ContosoRetail
COSMOS_CONTAINER_NAME=Products
COSMOS_CONTAINER_PARTITION_KEY=categoryName

  4. 在 Azure 资源管理器中，Shift + Alt + A，选择订阅，然后选择“Azure Cosmos DB”节点以查看资源。

  5. 右键单击 Cosmos DB 帐户，然后选择“复制连接字符串”。

    Screenshot of the Visual Studio Code with Cosmos D B account name selected and the submenu to Copy Connection String highlighted.

  6. 将连接字符串粘贴到 .env 文件的 COSMOS_CONNECTION_STRING 变量中。

安装 Cosmos DB 包

  1. 在集成终端中，添加 Cosmos DB SDK。

    npm install @azure/cosmos

  2. 在集成终端中，添加 npm 包以将 .env 文件用于环境变量。 此包会读取 .env 文件并将这些值添加到 process.env 运行时对象中。

    npm install dotenv

产品形状

了解文档 JSON 将帮助你了解操作、其输入和响应。

此数据集中的产品具有以下形状：

{
      "id": "FEEFEE3B-6CB9-4A75-B896-5182531F661B",
      "categoryId": "AE48F0AA-4F65-4734-A4CF-D48B8F82267F",
      "categoryName": "Bikes, Road Bikes",
      "sku": "BK-R19B-52",
      "name": "Road-750 Black, 52",
      "description": "The product called \"Road-750 Black, 52\"",
      "price": 539.99,
      "tags": [
        { "id": "461ADE06-0903-4BAF-97AB-CC713E5B1DD4", "name": "Tag-174" },
        ...
      ],
      "inventory": [
        { "location": "Dallas", "inventory": 91 },
        ...
      ]
    }
属性 说明
id Cosmos DB 使用自定义标识符 id 来唯一地标识每个项。 ID 可以是任何数据类型（例如数字、字符串等）。如果你未提供 ID，则 Cosmos DB 会为你创建一个。
categoryName 为此数据集专门选择了此属性作为分区键。 产品类别名称可使数据进行某种程度的均匀分布，这十分适合于分区键。 categoryName 也不会经常更改，这对于分区键也十分重要。
标记和清单 这些表示可用于通过 JOIN 关键字查找和重塑查询结果的子属性。

创建脚本以将产品添加到容器

  1. 在 Visual Studio Code 的“文件”菜单中，选择“新建文本文件”。

  2. 在“文件”菜单中，选择“另存为”。 使用名称 1-contoso-products-upload-data.js 保存新文件。

  3. 复制以下 JavaScript 并将其粘贴到该文件中。

    import * as path from "path";
import { promises as fs } from "fs";
import { fileURLToPath } from "url";
const __dirname = path.dirname(fileURLToPath(import.meta.url));

// Get environment variables from .env
import * as dotenv from "dotenv";
dotenv.config();

// Get Cosmos Client
import { CosmosClient } from "@azure/cosmos";

// Provide required connection from environment variables
const cosmosSecret = process.env.COSMOS_CONNECTION_STRING;

// Authenticate to Azure Cosmos DB
const cosmosClient = new CosmosClient(cosmosSecret);

// Set Database name and container name
const databaseName = process.env.COSMOS_DATABASE_NAME;
const containerName = process.env.COSMOS_CONTAINER_NAME;
const partitionKeyPath = [`/${process.env.COSMOS_CONTAINER_PARTITION_KEY}`];

// Create DB if it doesn't exist
const { database } = await cosmosClient.databases.createIfNotExists({
  id: databaseName,
});

// Create container if it doesn't exist
const { container } = await database.containers.createIfNotExists({
  id: containerName,
  partitionKey: {
    paths: partitionKeyPath,
  },
});

// Get product data
const fileAndPathToJson = "products.json";
const items = JSON.parse(await fs.readFile(path.join(__dirname, fileAndPathToJson), "utf-8"));

let i = 0;

// Insert products into container
for (const item of items) {
  const { resource, activityId, statusCode } = await container.items.create(item);
  console.log(`[${i++}] activityId: ${activityId}, statusCode: ${statusCode}, ${resource.name} inserted`);
}

// Show container name - copy/paste into .env
console.log(`\n\ncontainerName: ${containerName}`);// 

// Run script with 
// node 1-contoso-products-upload-data.js

  4. 创建名为 products.json 的新文件，并将示例数据文件 products.json 的内容复制到其中。

    这是 JSON 对象的数组。

  5. 在 Visual Studio Code 终端中，执行 JavaScript 文件以将数据上传到 Cosmos DB 容器中：

    node 1-contoso-products-upload-data.js

    终端会显示项计数、activityId、statusCode 和项名称。

操作的结果对象

从操作返回的结果对象会记录在 Cosmos DB SQL 参考文档中。 虽然结果可以包含特定于操作的信息，不过每个结果会具有一些始终返回并且有助于确定所发生的情况的属性。

结果属性 描述
activityId 与特定操作关联的唯一事件 ID。 如果操作失败，并且需要联系支持人员，则此 ID 以及资源名称和订阅有助于快速找到问题。
statusCode 指示操作成功或失败的 HTTP 状态代码。
resource 这是最终对象的 JSON 对象，例如容器中的 JSON 文档。

在 Visual Studio Code 中查看 Cosmos DB 文档

  1. 在 Visual Studio Code 中，打开 Azure 资源管理器，或使用键盘快捷方式 Shift + Alt + A。

  2. 找到并展开 Concierge 订阅节点，然后选择“Azure Cosmos DB”资源节点。

  3. 找到并展开 ContosoRetail 数据库及其 Products 容器。

  4. 展开“文档”节点以查看 Node.js 脚本添加的产品。 每个文档的节点名称是 name 属性。

  5. 选择第一个产品以查看整个 JSON。

    Screenshot of the Visual Studio Code showing a newly added Cosmos DB Core document.

检查你的工作

  • 在 Visual Studio Code 的 Azure 数据库扩展中，可以看到 Cosmos DB 帐户、数据库和容器。
  • 展开容器时，可在“文档”节点下看到许多项。