الدرس: ربط تطبيق ويب Node.js ب Azure DocumentDB

في هذا الدرس، تبني تطبيق ويب Node.js يتصل ب Azure DocumentDB. مكدس MongoDB وExpress وReact.jsNode.js (MERN) هو مجموعة شهيرة من التقنيات المستخدمة لبناء العديد من تطبيقات الويب الحديثة. مع Azure DocumentDB، يمكنك بناء تطبيق ويب جديد أو ترحيل تطبيق موجود باستخدام تعريفات MongoDB التي تعرفها بالفعل. في هذا البرنامج التعليمي، سوف تتعلّم:

• إعداد بيئتك
• اختبر تطبيق MERN باستخدام حاوية MongoDB محلية
• اختبر تطبيق MERN باستخدام عنقود
• نشر تطبيق MERN إلى Azure App Service

Prerequisites

لإكمال هذا البرنامج التعليمي، تحتاج إلى الموارد التالية:

• اشتراك Azure

  • إذا لم يكن لديك اشتراك Azure، فقم بإنشاء حساب مجاني

• مجموعة Azure DocumentDB موجودة

  • إذا لم يكن لديك عنقود، أنشئ عنقود جديد

• حساب GitHub مع استحقاق GitHub Codespaces

تكوين بيئة التطوير

بيئة حاوية تطوير متوفرة بجميع التبعيات المطلوبة لإكمال كل تمرين في هذا المشروع. يمكنك تشغيل حاوية التطوير في GitHub Codespaces أو محليا باستخدام Visual Studio Code.

مساحات رموز GitHub

يدير GitHub Codespaces حاوية تطوير تديرها GitHub مع Visual Studio Code for the Web كواجهة مستخدم. لأكثر بيئة تطوير بسيطة، استخدم GitHub Codespaces حتى يكون لديك الأدوات والتبعيات الصحيحة للمطورين مثبتة مسبقا لإكمال وحدة التدريب هذه.

Important

جميع حسابات GitHub يمكنها استخدام Codespaces لمدة تصل إلى 60 ساعة مجانية شهريا مع وجود مثيلتين أساسيتين.

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
   

   إشعار

   يتطلب هذا الدرس الإصدارات التالية من كل أداة، والتي يتم تثبيتها مسبقا في بيئتك:

   Tool	إصدار
   Docker	≥ 20.10.0
   Node.js	≥ 18.0150
   npm	≥ 9.5.0
   Azure CLI	≥ 2.46.0

6. أغلق المحطة.

7. الخطوات المتبقية في هذا الدرس تتم في سياق حاوية التطوير هذه.

إضافة Dev Containers لكود Visual Studio تتطلب تثبيت Docker على جهازك المحلي. تستضيف الإضافة حاوية التطوير محليا باستخدام مضيف Docker مع الأدوات والتبعيات الصحيحة للمطورين المثبتة مسبقا لإكمال وحدة التدريب هذه.

1. افتح كود فيجوال ستوديو في سياق مجلد فارغ.

2. تأكد من تثبيت إضافة Dev Containers في 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	إصدار
   Docker	≥ 20.10.0
   Node.js	≥ 18.0150
   npm	≥ 9.5.0
   Azure CLI	≥ 2.46.0

7. أغلق المحطة.

8. الخطوات المتبقية في هذا الدرس تتم في سياق حاوية التطوير هذه.

اختبر واجهة برمجة تطبيقات تطبيق MERN باستخدام حاوية MongoDB

ابدأ بتشغيل واجهة برمجة تطبيقات التطبيق النموذجي مع حاوية 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 playground.

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. تفتح واجهة برمجة التطبيقات تلقائيا نافذة متصفح للتحقق من أنها ترجع مجموعة من مستندات المنتج.

13. أغلق تبويب أو نافذة المتصفح الإضافية.

14. أغلق المحطة.

اختبار تطبيق MERN باستخدام عنقود Azure DocumentDB

الآن، دعونا نتأكد من أن التطبيق يعمل بسلاسة مع Azure DocumentDB. لهذه المهمة، قم بملء البيانات البذرية في المجموعة الموجودة مسبقا باستخدام shell MongoDB ثم تحديث سلسلة الاتصال الخاصة ب API.

1. سجّل الدخول إلى مدخل Azure (https://portal.azure.com).

2. انتقل إلى صفحة التجمع الحالية في Azure DocumentDB.

3. من صفحة مجموعة Azure DocumentDB، اختر خيار قائمة التنقل في سلاسل الاتصال .

   

4. سجل القيمة من حقل سلسلة الاتصال .

   

   Important

   سلسلة الاتصال في البوابة لا تتضمن قيم اسم المستخدم وكلمة المرور. يجب عليك استبدال <user> ال و <password> المؤقتين ببيانات الاعتماد التي استخدمتها عند إنشاء العنقود الأصلي.

5. افتح طرفية جديدة داخل بيئة التطوير المتكاملة (IDE) الخاصة بك.

6. شغل MongoDB Shell باستخدام mongosh الأمر وسلسلة الاتصال التي سجلتها سابقا. تأكد من استبدال <user> ال and <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
   

7. داخل ال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({});
   

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 DocumentDB. استخدم نفس سلسلة الاتصال التي استخدمتها مع قشرة مونغو.

    CONNECTION_STRING=<your-connection-string>
    

12. التحقق من أن التطبيق يستخدم خدمة قاعدة البيانات عن طريق تغيير سياق الطرفية إلى الخادم/ المجلد، وتثبيت التبعيات من Node Package Manager (npm)، ثم تشغيل التطبيق.

    cd server
    
    npm install
    
    npm start
    

13. تفتح واجهة برمجة التطبيقات تلقائيا نافذة متصفح للتحقق من أنها ترجع مجموعة من مستندات المنتج.

14. أغلق تبويب أو نافذة المتصفح الإضافية. ثم، أغلق المحطة.

نشر تطبيق MERN إلى Azure App Service

أثبت أن التطبيق يعمل من طرف إلى طرف عن طريق نشر الخدمة والعميل إلى خدمة تطبيقات Azure. استخدم الأسرار في تطبيقات الويب لتخزين متغيرات البيئة باستخدام بيانات الاعتماد ونقاط نهاية API.

1. داخل بيئة التطوير المتكاملة (IDE)، افتح طرفية جديدة.

2. إنشاء متغير shell لاسم مجموعة الموارد الموجودة مسبقا باسم resourceGroupName.

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

3. أنشئ متغيرات shell لتطبيقين ويب هما 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 استخدم نفس القيمة لسلسلة الاتصال التي استخدمتها مع shell 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 واحتفظ به في متغير shell اسمه d serverUri.

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

9. استخدم الحزمة open-cli والأمر من NuGet مع npx لفتح نافذة متصفح باستخدام رابط المستخدم الخاص بتطبيق الويب الخاص بالخادم. تحقق من أن تطبيق الخادم يعيد بيانات مصفوفة JSON الخاصة بك من العنقود.

   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_ENDPOINTaz webapp config appsettings set. استخدم نقطة نهاية واجهة برمجة تطبيقات الخادم المخزنة في متغير serverUri shell.

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

13. احصل على رابط المستخدم لتطبيق الويب الخاص az webapp show بالعميل واحتفظ به في متغير shell اسمه d clientUri.

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

14. استخدم الحزمة open-cli والأمر من NuGet مع npx لفتح نافذة متصفح باستخدام URI الخاص بتطبيق الويب الخاص بالعميل. تحقق من أن تطبيق العميل يعرض البيانات من واجهة برمجة تطبيقات الخادم.

    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

حذف بيئة كودسبيس في GitHub يضمن قدرتك على تعظيم كمية الساعات الأساسية المجانية التي تحصل عليها لحسابك.

1. تسجيل الدخول إلى لوحة تحكم GitHub Codespaces (https://github.com/codespaces).

2. ابحث عن حاوية التطوير التي تعمل حاليا من azure-samples/msdocs-azure-cosmos-db-mongodb-mern-web-app مستودع GitHub.

   

3. افتح قائمة السياق الخاصة بمساحة الكود ثم اختر حذف.

   

ليس من الضروري أن تنظف بيئتك المحلية، لكن يمكنك إيقاف حاوية التطوير الجارية والعودة لتشغيل كود Visual Studio في سياق مساحة عمل محلية.

1. افتح لوحة الأوامر، وابحث عن أوامر حاويات التطوير ، ثم اختر حاويات التطوير: إعادة فتح المجلد محليا.

   

تلميح

يوقف كود فيجوال ستوديو حاوية التطوير الجارية، لكن الحاوية لا تزال موجودة في دوكر في حالة توقف. يمكنك دائما حذف نسخة الحاوية، وصورة الحاوية، ووحدات التخزين من Docker لتوفير مساحة أكبر على جهازك المحلي.

الخطوة التالية

نقل بياناتك