教學：將 Node.js 網頁應用程式與 Azure DocumentDB 連接

在這個教學中，你會建立一個 Node.js 的網頁應用程式，連接到 Azure DocumentDB。 MongoDB、Express、React.js、Node.js（MERN）堆疊是一個受歡迎的技術集合，用於建構許多現代網頁應用程式。使用 Azure DocumentDB，你可以建立新的網頁應用程式，或使用你已經熟悉的 MongoDB 驅動程式遷移現有應用程式。在本教學課程中，您會：

設定您的環境
用本地的 MongoDB 容器測試 MERN 應用程式
用叢集測試 MERN 應用程式
將 MERN 應用程式部署到 Azure App Service

先決條件

若要完成本教學課程，您需要下列資源：

Azure 訂用帳戶
- 如果您沒有 Azure 訂用帳戶，請建立免費帳戶

一個現有的 Azure DocumentDB 叢集
- 如果你沒有叢集，就建立一個新的叢集

一個擁有 GitHub Codespaces 權限的 GitHub 帳號

設定開發環境

開發容器環境提供，包含完成本專案每項練習所需的所有依賴。你可以在 GitHub Codespaces 或本地使用 Visual Studio Code 執行開發容器。

GitHub 代碼空間
Visual Studio 程式碼

GitHub Codespaces 運行由 GitHub 管理的開發容器，使用者介面為 Visual Studio Code for the Web。若要取得最直接的開發環境，建議使用 GitHub Codespaces，這樣你就已經預先安裝了正確的開發工具和相依套件，才能完成這個訓練模組。

這很重要

所有 GitHub 帳戶每月都可以免費使用 Codespaces 長達 60 小時，並使用兩個核心實例。

開始在 azure-samples/msdocs-azure-cosmos-db-mongodb-mern-web-app GitHub 存放庫分的 main 分支上建立新 GitHub Codespace 的流程。

中開啟
在 [ 建立 codespace ] 頁面上，檢閱 codespace 組態設定，然後選取 [ 建立新的 codespace ]
等候程式空間啟動。此啟動程序可能需要幾分鐘的時間。
在程式碼空間中開啟一個新的終端機。

小提示

你可以使用主選單進入終端機選單，然後選擇 新終端 機選項。
請檢查你在這教學中使用的工具版本。
```
docker --version

node --version

npm --version

az --version
```
備註

本教學需要以下版本的每個工具，這些版本已預先安裝在您的環境中：

Tool 版本

Docker ≥ 20.10.0

Node.js ≥ 18.0150

npm ≥ 9.5.0

Azure CLI ≥ 2.46.0
關閉終端機。
本教學的剩餘步驟則在這個開發容器的背景下進行。

Tool	版本
Docker	≥ 20.10.0
Node.js	≥ 18.0150
npm	≥ 9.5.0
Azure CLI	≥ 2.46.0

適用於 Visual Studio Code 的 開發容器擴充功能 需要在本機電腦上安裝 Docker。擴充套件以 Docker 主機本地架設開發容器，並預裝正確的開發工具與相依套件以完成此訓練模組。

在空目錄的情境中開啟 Visual Studio Code 。
請確定已在 Visual Studio Code 中安裝 開發容器延伸模組。
在編輯器中開啟新的終端機。

小提示

你可以使用主選單進入終端機選單，然後選擇 新終端 機選項。

開啟新終端機的功能表選項的螢幕擷取畫面。
將 azure-samples/msdocs-azure-cosmos-db-mongodb-mern-web-app GitHub 倉庫複製到目前的目錄中。
```
git clone https://github.com/azure-samples/msdocs-azure-cosmos-db-mongodb-mern-web-app.git .
```
開啟 [命令選擇區]，搜尋 [開發容器] 命令，然後選取 [開發容器: 在容器中重新開啟]。

小提示

Visual Studio Code 可能會自動提示您在開發容器內重新開啟現有的資料夾。此步驟在功能上等同於使用指令調色盤重新開啟容器中目前的工作區。
請檢查你在這教學中使用的工具版本。
```
docker --version

node --version

npm --version

az --version
```
備註

本教學需要以下版本的每個工具，這些版本已預先安裝在您的環境中：

Tool 版本

Docker ≥ 20.10.0

Node.js ≥ 18.0150

npm ≥ 9.5.0

Azure CLI ≥ 2.46.0
關閉終端機。
本教學的剩餘步驟則在這個開發容器的背景下進行。

Tool	版本
Docker	≥ 20.10.0
Node.js	≥ 18.0150
npm	≥ 9.5.0
Azure CLI	≥ 2.46.0

用 MongoDB 容器測試 MERN 應用程式的 API

首先，透過本地的 MongoDB 容器執行範例應用程式的 API，以驗證應用程式是否可正常運作。

使用 Docker 執行 MongoDB 容器，並發佈典型的 MongoDB 埠27017（）。
```
docker pull mongo:6.0

docker run --detach --publish 27017:27017 mongo:6.0
```
在側邊欄選擇 MongoDB 擴充功能。
新增一個新的連接至 MongoDB 擴充套件，使用連接字串 mongodb://localhost。
連線成功後，打開 data/products.mongodb 的 playground 檔案。
選擇「 全部執行」 圖示來執行腳本。

遊樂場執行應該會產生本機 MongoDB 集合中的文件清單。這裡有一個截斷的輸出範例。

[
  {
    "_id": { "$oid": "640a146e89286b79b6628eef" },
    "name": "Confira Watch",
    "category": "watches",
    "price": 105
  },
  {
    "_id": { "$oid": "640a146e89286b79b6628ef0" },
    "name": "Diannis Watch",
    "category": "watches",
    "price": 98,
    "sale": true
  },
  ...
]

備註

物件識別碼（_id）是隨機產生的，與此截斷範例輸出不同。

在 伺服器/ 目錄中，建立一個新的 .env 檔案。
在 server/.env 檔案中，為此值加入一個環境變數：

環境變數價值觀

CONNECTION_STRING 連接到 Azure DocumentDB 叢集的連接字串。目前先用 mongodb://localhost:27017?directConnection=true。
```
CONNECTION_STRING=mongodb://localhost:27017?directConnection=true
```
將終端機的上下文改成 伺服器/ 資料夾。
```
cd server
```
從節點套件管理員 (npm) 安裝相依性。
```
npm install
```
啟動 Node.js 和 Express 應用程式。
```
npm start
```
API 會自動開啟瀏覽器視窗，以驗證是否回傳產品文件陣列。
關閉多餘的瀏覽器分頁/視窗。
關閉終端機。

環境變數	價值觀
`CONNECTION_STRING`	連接到 Azure DocumentDB 叢集的連接字串。目前先用 `mongodb://localhost:27017?directConnection=true`。

用Azure DocumentDB叢集測試MERN應用程式

現在，讓我們來驗證該應用程式是否能無縫搭配 Azure DocumentDB。為此任務，先用 MongoDB shell 將已存在的叢集填充種子資料，然後更新 API 的連接字串。

登入 Azure 入口網站 (https://portal.azure.com)。
前往現有的 Azure DocumentDB 叢集頁面。
在 Azure DocumentDB 叢集頁面，選擇 「連線字串 導航」選單選項。
記錄連線字串欄位的值。

這很重要

入口網站的連線字串沒有包含使用者名稱和密碼的值。你必須用你最初建立叢集時使用的憑證替換 <user> 和 <password> 佔位符。
在你的整合開發環境（IDE）中開啟一個新的終端機。
使用 mongosh 命令和你之前記錄的連接字串啟動 MongoDB Shell。務必將 <user> 和 <password> 佔位符替換成你最初建立叢集時使用的憑證。
```
mongosh "<mongodb-cluster-connection-string>"
```
備註

你可能需要為連接字串編碼特定的值。在此範例中，叢集名稱為 msdocs-azure-documentdb-tutorial，使用者名稱為 clusteradmin，密碼為 P@ssw.rd。在密碼中，@字元需要使用%40進行編碼。此處提供一個連接字串範例及密碼正確編碼。
```
CONNECTION_STRING=mongodb+srv://clusteradmin:P%40ssw.rd@msdocs-azure-documentdb-tutorial.mongocluster.cosmos.azure.com/?tls=true&authMechanism=SCRAM-SHA-256&retrywrites=false&maxIdleTimeMS=120000
```

在 shell 內執行以下指令建立資料庫、建立收藏，並植入初始資料。

use('cosmicworks');

db.products.drop();

db.products.insertMany([
  { name: "Confira Watch", category: "watches", price: 105.00 },
  { name: "Diannis Watch", category: "watches", price: 98.00, sale: true },
  { name: "Sterse Gloves", category: "gloves", price: 42.00 },
  { name: "Peache Sunglasses", category: "eyewear", price: 32.00, sale: false, sizes: [ "S", "M", "L" ] },
  { name: "Icento Pack", category: "bags", price: 58.00 },
  { name: "Iroowl Bracelet", category: "watches", price: 66.00 },
  { name: "Glaark Bag", category: "bags", price: 56.00, sale: true },
  { name: "Windry Mittens", category: "gloves", price: 35.00 },
  { name: "Tuvila Hat", category: "hats", price: 120.00 },
  { name: "Klinto Hat", category: "hats", subcategory: "hats-beanies", price: 65.00 }
]);

db.products.find({});

這些指令應該會產生一份本地 MongoDB 集合中的文件清單。這裡有一個截斷的輸出範例。

[
  {
    "_id": { "$oid": "640a146e89286b79b6628eef" },
    "name": "Confira Watch",
    "category": "watches",
    "price": 105
  },
  {
    "_id": { "$oid": "640a146e89286b79b6628ef0" },
    "name": "Diannis Watch",
    "category": "watches",
    "price": 98,
    "sale": true
  },
  ...
]

備註

物件識別碼（_id）是隨機產生的，與此截斷範例輸出不同。

離開 MongoDB 命令列介面。
```
exit
```
在 client/ 目錄中，建立一個新的 .env 檔案。
在 client/.env 檔案中，為此值加入一個環境變數：

環境變數價值觀

CONNECTION_STRING 連接到 Azure DocumentDB 叢集的連接字串。請使用與在 mongo shell 中使用的相同連接字串。
```
CONNECTION_STRING=<your-connection-string>
```
透過將終端機的上下文改為 伺服器/ 資料夾，安裝 Node Package Manager （npm）的相依關係，然後啟動應用程式，來驗證應用程式是否正在使用資料庫服務。
```
cd server

npm install

npm start
```
API 會自動開啟瀏覽器視窗，以驗證是否回傳產品文件陣列。
關閉多餘的瀏覽器分頁/視窗。然後，關閉航廈。

環境變數	價值觀
`CONNECTION_STRING`	連接到 Azure DocumentDB 叢集的連接字串。請使用與在 mongo shell 中使用的相同連接字串。

將 MERN 應用程式部署到 Azure App Service

透過將服務和用戶端部署到 Azure App Service，證明應用程式能端到端運作。在網頁應用程式中使用秘密來儲存環境變數、憑證和 API 端點。

在你的整合開發環境（IDE）中，開啟一個新的終端機。

為已存在資源群組名稱 resourceGroupName 建立一個 shell 變數。

# Variable for resource group name
resourceGroupName="<existing-resource-group>"

為兩個名為 serverAppName 和 clientAppName 的網頁應用程式建立 shell 變數。

# Variable for randomnly generated suffix
let suffix=$RANDOM*$RANDOM

# Variable for web app names with a randomnly generated suffix
serverAppName="server-app-$suffix"
clientAppName="client-app-$suffix"

如果你還沒登入，請用指令 az login --use-device-code 登入 Azure CLI。
將目前的工作目錄改成 伺服器/ 路徑。
```
cd server
```

為 MERN 應用程式的伺服器元件建立一個新的 az webapp up網頁應用程式。

az webapp up \
    --resource-group $resourceGroupName \
    --name $serverAppName \
    --sku F1 \
    --runtime "NODE|18-lts"

使用 az webapp config connection-string set 為名為 CONNECTION_STRING 的伺服器 Web 應用程式建立新的連接字串設定。使用稍早在本教程中 MongoDB shell 及 .env 檔案中使用過的相同連線字串值。
```
az webapp config connection-string set \
    --resource-group $resourceGroupName \
    --name $serverAppName \
    --connection-string-type custom \
    --settings "CONNECTION_STRING=<mongodb-connection-string>"
```

取得伺服器 az webapp show 網頁應用程式的 URI，並儲存在一個名為 d serverUri 的 shell 變數中。

serverUri=$(az webapp show \
    --resource-group $resourceGroupName \
    --name $serverAppName \
    --query hostNames[0] \
    --output tsv)

使用 open-cli 的 NuGet 套件和命令，配合 npx 使用伺服器網頁應用程式的 URI 來開啟瀏覽器視窗。確認伺服器應用程式是否從叢集回傳你的 JSON 陣列資料。
```
npx open-cli "https://$serverUri/products" --yes
```
小提示

有時部署會非同步完成。若未看到預期的內容，請稍候一分鐘，然後重新整理瀏覽器視窗。
把工作目錄改成 客戶端/ 路徑。
```
cd ../client
```

為 MERN 應用程式的用戶端元件建立一個新的 az webapp up網頁應用程式。

az webapp up \
    --resource-group $resourceGroupName \
    --name $clientAppName \
    --sku F1 \
    --runtime "NODE|18-lts"

為客戶端網頁應用程式建立一個新的應用程式設定，名稱為 REACT_APP_API_ENDPOINTaz webapp config appsettings set。使用儲存在 serverUri shell 變數中的伺服器 API 端點。
```
az webapp config appsettings set \
    --resource-group $resourceGroupName \
    --name $clientAppName \
    --settings "REACT_APP_API_ENDPOINT=https://$serverUri"
```

取得客戶 az webapp show 端網頁應用的 URI，並儲存在一個名為 dclientUri 的 shell 變數中。

clientUri=$(az webapp show \
    --resource-group $resourceGroupName \
    --name $clientAppName \
    --query hostNames[0] \
    --output tsv)

使用來自 NuGet 的 open-cli 套件和 npx 指令，使用 URI 開啟客戶端網頁應用程式的瀏覽器視窗。驗證客戶端應用程式是否從伺服器應用程式的 API 呈現資料。
```
npx open-cli "https://$clientUri" --yes
```
小提示

有時部署會非同步完成。如果你沒有看到預期的結果，請再等一分鐘並重新整理瀏覽器視窗。
關閉終端機。

清理資源

如果您使用自己的訂用帳戶，當專案結束時，建議您移除不再需要的資源。讓資源繼續執行可能會產生費用。您可以個別刪除資源，或刪除資源群組以刪除整組資源。

要刪除整個資源群組，請使用 az group delete。

az group delete \
    --name $resourceGroupName \
    --yes

用 az group list驗證資源群組是否已被刪除。
```
az group list
```

清理開發環境

你也可能想清理開發環境，或讓它恢復到原本的狀態。

GitHub 代碼空間
Visual Studio 程式碼

刪除 GitHub Codespaces 環境，確保您可以最大化帳戶取得的每個核心免費時數權利。

登入 GitHub Codespaces 儀表板 (https://github.com/codespaces)。
找到你目前正在運行的開發容器，來源是 azure-samples/msdocs-azure-cosmos-db-mongodb-mern-web-app GitHub 倉庫。
開啟 codespace 的上下文功能表，然後選取刪除。