Руководство по подключению веб-приложения 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 могут использовать пространства Кода до 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. Создайте в каталоге или сервере новый 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. В каталоге клиента или каталога создайте новый ENV-файл .

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

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

    CONNECTION_STRING=<your-connection-string>
    

12. Убедитесь, что приложение использует службу базы данных, изменив контекст терминала на сервер или папку, установив зависимости от узла диспетчер пакетов (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. Измените текущий рабочий каталог на сервер или путь.

   cd server
   

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

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

7. Создайте новый параметр строка подключения для серверного веб-приложения с az webapp config connection-string setименем CONNECTION_STRING . Используйте то же значение для строка подключения, который вы использовали с оболочкой 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 сервера и сохраните его в имени переменной оболочки d 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. Создайте новый параметр приложения для клиентского веб-приложения с az webapp config appsettings setименем REACT_APP_API_ENDPOINT . Используйте конечную точку 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.

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