Руководство. Подключение веб-приложения Node.js к Azure DocumentDB

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

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

Предпосылки

Чтобы завершить работу с этим руководством, вам потребуется следующее:

• подписка Azure

  • Если у вас нет подписки Azure, создайте бесплатную учетную запись.

• Существующий кластер Azure DocumentDB

  • Если у вас нет кластера, создайте новый кластер

• Учетная запись GitHub с правами GitHub Codespaces

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

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

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

Это важно

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

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

   

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

   Снимок экрана с подтверждением перед созданием нового кодового пространства.

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

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

   Подсказка

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

   

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

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

   Замечание

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

   Tool	Версия
   Докер	≥ 20.10.0
   Node.js	≥ 18.0150
   npm	≥ 9.5.0
   Azure CLI (Интерфейс командной строки для Azure)	≥ 2.46.0

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

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

Visual Studio Code

Расширение Dev Containers для 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
   

   Замечание

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

   Tool	Версия
   Докер	≥ 20.10.0
   Node.js	≥ 18.0150
   npm	≥ 9.5.0
   Azure CLI (Интерфейс командной строки для Azure)	≥ 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 DocumentDB. Теперь используйте mongodb://localhost:27017?directConnection=true.

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

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

   cd server
   

10. Установите зависимости из Node Package Manager (npm).

    npm install
    

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

    npm start
    

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

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

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

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

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

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

2. Перейдите на существующую страницу кластера Azure DocumentDB.

3. На странице кластера Azure DocumentDB выберите пункт меню навигации по строкам подключения .

   

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

   

   Это важно

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

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

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

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

   Замечание

   Может потребоваться закодировать определенные значения для строки подключения. В этом примере имя кластера — msdocs-azure-documentdb-tutorialclusteradminимя пользователя и пароль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
   

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 DocumentDB. Используйте ту же строку подключения, которую вы использовали с оболочкой 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. Создайте новый параметр строки подключения для веб-приложения сервера, названного CONNECTION_STRING с именем az 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 из кластера.

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

   Подсказка

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

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

    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. Используйте пакет и команду из NuGet open-cli, чтобы, используя URI для клиентского веб-приложения, открыть окно браузера npx. Убедитесь, что клиентское приложение отображает данные из 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 гарантирует, что вы можете максимально увеличить объем бесплатных прав на базовые часы, которые вы получаете для вашей учетной записи.

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. Откройте Command Palette, найдите команды Dev Containers, а затем выберите Dev Containers: Reopen Folder Locally.

   

Подсказка

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

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

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