Руководство по подключению веб-приложения Node.js к Azure Cosmos DB для MongoDB (vCore)

Область применения: Виртуальные ядра MongoDB

В этом руководстве вы создадите веб-приложение Node.js, которое подключается к Azure Cosmos DB для MongoDB в архитектуре виртуальных ядер. Стек MongoDB, Express, React.js, Node.js (MERN) — это популярная коллекция технологий, используемых для создания многих современных веб-приложений. С помощью Azure Cosmos DB для MongoDB (vCore) можно создать новое веб-приложение или перенести существующее приложение с помощью драйверов MongoDB, с которыми вы уже знакомы. Изучив это руководство, вы:

• Настройка среды
• Тестирование приложения MERN с помощью локального контейнера MongoDB
• Тестирование приложения MERN с помощью кластера виртуальных ядер
• Развертывание приложения MERN в службе приложение Azure

Необходимые компоненты

Для работы с этим учебником требуются следующие ресурсы:

• Существующий кластер виртуальных ядер.
• Учетная запись GitHub.
  • GitHub предоставляет бесплатные часы Codespaces для всех пользователей.

Настройка среды разработки

Среда контейнера разработки доступна со всеми зависимостями, необходимыми для выполнения каждого упражнения в этом проекте. Контейнер разработки можно запустить в GitHub Codespaces или локально с помощью Visual Studio Code.

GitHub Codespaces

GitHub Codespaces запускает контейнер разработки, управляемый GitHub, с помощью Visual Studio Code для веба в качестве пользовательского интерфейса. Для наиболее простой среды разработки используйте GitHub Codespaces, чтобы у вас были правильные средства разработчика и зависимости, предварительно установленные для выполнения этого модуля обучения.

Внимание

Все учетные записи GitHub могут использовать Codespaces до 60 часов бесплатно каждый месяц с 2 выделенными ядрами.

1. Запустите процесс создания нового пространства кода GitHub в main ветви azure-samples/msdocs-azure-cosmos-db-mongodb-mern-web-app репозитория GitHub.

   

2. На странице "Создание пространства кода" просмотрите параметры конфигурации пространства кода и выберите "Создать новое пространство кода"

   

3. Дождитесь запуска кодового пространства. Этот процесс запуска может занять несколько минут.

4. Откройте новый терминал в пространстве кода.

   Совет

   Вы можете использовать главное меню для перехода к параметру меню терминала , а затем выберите пункт "Новый терминал ".

   

5. Проверьте версии инструментов, используемых в этом руководстве.

   docker --version
   
   node --version
   
   npm --version
   
   az --version
   

   Примечание.

   В этом руководстве требуются следующие версии каждого средства, предварительно установленного в вашей среде:

   Средство	Версия
   Docker	≥ 20.10.0
   Node.js	≥ 18.0150
   NPM	≥ 9.5.0
   Azure CLI	≥ 2.46.0

6. Закройте терминал.

7. Остальные действия, описанные в этом руководстве, происходят в контексте этого контейнера разработки.

Visual Studio Code

Расширение "Контейнеры разработки" для Visual Studio Code требует установки Docker на локальном компьютере. Расширение размещает контейнер разработки локально с помощью узла Docker с правильными средствами разработчика и предустановленными зависимостями для завершения этого модуля обучения.

1. Откройте Visual Studio Code в контексте пустого каталога.

2. Убедитесь, что у вас есть расширение "Контейнеры разработки" в Visual Studio Code.

3. Откройте новый терминал в редакторе.

   Совет

   Вы можете использовать главное меню для перехода к параметру меню терминала , а затем выберите пункт "Новый терминал ".

   

4. Клонируйте репозиторий 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 .
   

5. Откройте Палитру команд, найдите команды контейнеров разработки, а затем выберите Контейнеры разработки: снова открыть в контейнере.

   

   Совет

   Visual Studio Code может автоматически запрашивать повторно открыть существующую папку в контейнере разработки. Это функционально эквивалентно использованию палитры команд для повторного открытия текущей рабочей области в контейнере.

   

6. Проверьте версии инструментов, используемых в этом руководстве.

   docker --version
   
   node --version
   
   npm --version
   
   az --version
   

   Примечание.

   В этом руководстве требуются следующие версии каждого средства, предварительно установленного в вашей среде:

   Инструмент	Версия
   Docker	≥ 20.10.0
   Node.js	≥ 18.0150
   NPM	≥ 9.5.0
   Azure CLI	≥ 2.46.0

7. Закройте терминал.

8. Остальные действия, описанные в этом руководстве, происходят в контексте этого контейнера разработки.

Тестирование API приложения MERN с помощью контейнера MongoDB

Начните с запуска API примера приложения с локальным контейнером MongoDB, чтобы убедиться, что приложение работает.

1. Запустите контейнер MongoDB с помощью Docker и опубликуйте типичный порт MongoDB (27017).

   docker pull mongo:6.0
   
   docker run --detach --publish 27017:27017 mongo:6.0
   

2. На боковой панели выберите расширение MongoDB.

   

3. Добавьте новое подключение к расширению MongoDB с помощью строка подключенияmongodb://localhost.

   

4. После успешного подключения откройте файл игровой площадки data/products.mongodb .

5. Щелкните иконку Выполнить все, чтобы выполнить скрипт.

   

6. Запуск тестовой среды должен привести к формированию списка документов в локальной коллекции MongoDB. Ниже приведен усеченный пример выходных данных.

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

   Примечание.

   Идентификаторы объектов (_id) создаются случайным образом и отличаются от выходных данных этого усеченного примера.

7. Создайте в каталоге server/ новый .env файл.

8. В файле server/.env добавьте переменную среды для этого значения:

   Переменная среды	Значение
   CONNECTION_STRING	Строка подключения в кластер Azure Cosmos DB для MongoDB (vCore). Сейчас используйте mongodb://localhost:27017?directConnection=true.

   CONNECTION_STRING=mongodb://localhost:27017?directConnection=true
   

9. Измените контекст терминала на сервер или папку.

   cd server
   

10. Установите зависимости из диспетчера пакетов npm.

    npm install
    

11. Запустите приложение Node.js и Express.

    npm start
    

12. API автоматически открывает окно браузера, чтобы убедиться, что он возвращает массив документов продукта.

13. Закройте дополнительную вкладку или окно браузера.

14. Закройте терминал.

Тестирование приложения MERN с помощью кластера Azure Cosmos DB для MongoDB (vCore)

Теперь давайте проверим, что приложение работает без проблем с Azure Cosmos DB для MongoDB (vCore). Для этой задачи заполните существующий кластер начальными данными с помощью интерфейса MongoDB, а затем обновите строку подключения API.

1. Войдите на портал Azure (https://portal.azure.com).

2. Перейдите на страницу существующего кластера Azure Cosmos DB для MongoDB (vCore).

3. На странице кластера Azure Cosmos DB для MongoDB (vCore) выберите пункт меню навигации по строкам подключения.

   

4. Запишите значение из поля строки подключения.

   

   Внимание

   Строка подключения на портале не включает значения имени пользователя и пароля. Необходимо заменить заполнители <user> и <password> на учетные данные, которые вы использовали при первоначальном создании кластера.

5. Вернитесь в интегрированную среду разработки (IDE), откройте новый терминал.

6. Запустите оболочку MongoDB с помощью команды mongosh и ранее записанной строки подключения. Удостоверьтесь, что вы заменили метки <user> и <password> учетными данными, которые вы использовали при первоначальном создании кластера.

   mongosh "<mongodb-cluster-connection-string>"
   

   Примечание.

   Может потребоваться кодировать определенные значения для строка подключения. В этом примере имя кластера — msdocs-cosmos-tutorialclusteradminимя пользователя и парольP@ssw.rd. В пароле @ символ должен быть закодирован с помощью %40. Ниже приведен пример строка подключения с правильной кодировкой пароля.

   CONNECTION_STRING=mongodb+srv://clusteradmin:P%40ssw.rd@msdocs-cosmos-tutorial.mongocluster.cosmos.azure.com/?tls=true&authMechanism=SCRAM-SHA-256&retrywrites=false&maxIdleTimeMS=120000
   

7. В командной оболочке выполните команды ниже для создания базы данных, создания коллекции и заполнения начальными данными.

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

8. Команды должны привести к списку документов в локальной коллекции MongoDB. Ниже приведен усеченный пример выходных данных.

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

   Примечание.

   Идентификаторы объектов (_id) создаются случайным образом и отличаются от выходных данных этого усеченного примера.

9. Закройте оболочку MongoDB.

   exit
   

10. В каталоге client/ создайте новый файл .env.

11. В файле client/.env добавьте переменную среды для этого значения:

    Переменная среды	Значение
    CONNECTION_STRING	Строка подключения к кластеру Azure Cosmos DB для MongoDB (vCore). Используйте ту же строку подключения, которую вы использовали с Mongo оболочкой.

    CONNECTION_STRING=<your-connection-string>
    

12. Убедитесь, что приложение использует службу базы данных, изменив контекст терминала на папку server/, установив зависимости с помощью Node Package Manager (npm), а затем запустите приложение.

    cd server
    
    npm install
    
    npm start
    

13. API автоматически открывает окно браузера, чтобы убедиться, что он возвращает массив документов продукта.

14. Закройте дополнительную вкладку или окно браузера. Затем закройте терминал.

Развертывание приложения MERN в службе приложений Azure

Разверните службу и клиент в службе приложений Azure, чтобы доказать, что приложение работает полноценно. Используйте секреты в веб-приложениях для хранения переменных среды с учетными данными и конечными точками API.

1. В интегрированной среде разработки (IDE) откройте новый терминал.

2. Создайте переменную оболочки для имени предварительно существующей группы ресурсов с именем resourceGroupName.

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

3. Создайте переменные оболочки для двух веб-приложений с именем serverAppName и clientAppName.

   # 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"
   

4. Если вы еще этого не сделали, войдите в Azure CLI с помощью команды az login --use-device-code.

5. Измените текущий рабочий каталог на путь server/.

   cd server
   

6. Создайте новое веб-приложение для серверного компонента приложения MERN с помощью az webapp up.

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

7. Создайте новый параметр строки подключения для серверного веб-приложения с именем CONNECTION_STRINGaz webapp config connection-string set. Используйте то же значение для строки подключения, которое вы использовали с оболочкой MongoDB и файлом .env, как ранее в этом руководстве.

   az webapp config connection-string set \
       --resource-group $resourceGroupName \
       --name $serverAppName \
       --connection-string-type custom \
       --settings "CONNECTION_STRING=<mongodb-connection-string>"
   

8. Получите URI для веб-приложения сервера с az webapp show и сохраните его в переменной оболочки с именем serverUri.

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

9. Используйте пакет open-cli и команду из NuGet npx, чтобы открыть окно браузера, используя URI для серверного веб-приложения. Убедитесь, что серверное приложение возвращает данные массива JSON из кластера MongoDB (vCore).

   npx open-cli "https://$serverUri/products" --yes
   

   Совет

   Иногда развертывания могут выполняться асинхронно. Если вы не видите ожидаемые действия, подождите еще одну минуту и обновите окно браузера.

10. Измените рабочий каталог на клиент или путь.

    cd ../client
    

11. Создайте новое веб-приложение для клиентского компонента приложения MERN с помощью az webapp up.

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

12. Создайте новый параметр приложения с именем REACT_APP_API_ENDPOINT для клиентского веб-приложения с az webapp config appsettings set. Используйте конечную точку API сервера, хранящуюся в переменной оболочки serverUri .

    az webapp config appsettings set \
        --resource-group $resourceGroupName \
        --name $clientAppName \
        --settings "REACT_APP_API_ENDPOINT=https://$serverUri"
    

13. Получите универсальный код ресурса (URI) для клиентского веб-приложения и az webapp show сохраните его в имени переменной оболочки d clientUri.

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

14. open-cli Используйте пакет и команду из NuGet, npx чтобы открыть окно браузера с помощью URI для клиентского веб-приложения. Убедитесь, что клиентское приложение отображает данные из API серверного приложения.

    npx open-cli "https://$clientUri" --yes
    

    Совет

    Иногда развертывания могут выполняться асинхронно. Если вы не видите ожидаемые действия, подождите еще одну минуту и обновите окно браузера.

15. Закройте терминал.

Очистка ресурсов

Если вы работаете в своей подписке, после завершения проекта целесообразно удалить ресурсы, которые вам больше не нужны. Ресурсы, которые остаются включенными, могут стоить денег. Вы можете удалить ресурсы по отдельности либо удалить всю группу ресурсов.

1. Чтобы удалить всю группу ресурсов, используйте az group delete.

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

2. Убедитесь, что группа ресурсов удаляется с помощью az group list.

   az group list
   

Очистка среды разработки

Вы также можете очистить среду разработки или вернуть ее в типичное состояние.

GitHub Codespaces

Удаление среды GitHub Codespaces гарантирует, что вы можете максимально увеличить объем бесплатных прав на базовые часы, которые вы получаете для вашей учетной записи.

1. Войдите на панель мониторинга GitHub Codespaces (https://github.com/codespaces).

2. Найдите текущие пространства кода, полученные из azure-samples/msdocs-azure-cosmos-db-mongodb-mern-web-app репозитория GitHub.

   

3. Откройте контекстное меню для пространства кода и нажмите кнопку "Удалить".

   

Visual Studio Code

Для очистки локальной среды не обязательно требуется, но вы можете остановить запущенный контейнер разработки и вернуться к запуску Visual Studio Code в контексте локальной рабочей области.

1. Откройте палитру команд, найдите команды "Контейнеры разработки", а затем выберите "Контейнеры разработки: открыть папку локально".

   

Совет

Visual Studio Code остановит запущенный контейнер разработки, но контейнер по-прежнему существует в Docker в остановленном состоянии. Вы всегда можете удалить экземпляр контейнера, образ контейнера и тома из Docker, чтобы освободить больше места на локальном компьютере.

Следующий шаг

Теперь, когда вы создали свое первое приложение для кластера MongoDB (vCore), узнайте, как перенести данные в Azure Cosmos DB.

Перенос данных