مشاركة عبر

إعداد التطوير المحلي ل Azure Static Web Apps

  • مقالة

عند نشرها على السحابة، يربط موقع Azure Static Web Apps معا العديد من الخدمات التي تعمل معا كما لو كانت نفس التطبيق. تتضمن هذه الخدمات:

  • تطبيق الويب الثابت
  • واجهة برمجة تطبيقات وظائف Azure
  • خدمات المصادقة والتخويل
  • خدمات التوجيه والتكوين

يجب أن تتواصل هذه الخدمات مع بعضها البعض، وتعالج Azure Static Web Apps هذا التكامل لك في السحابة.

ومع ذلك، عند تشغيل التطبيق محليا، لا يتم ربط هذه الخدمات معا تلقائيا.

لتوفير تجربة مماثلة لما تحصل عليه في Azure، يوفر Azure Static Web Apps CLI الخدمات التالية:

  • خادم موقع ثابت محلي
  • وكيل لخادم تطوير إطار عمل الواجهة الأمامية
  • وكيل لنقاط نهاية واجهة برمجة التطبيقات الخاصة بك - متوفر من خلال Azure Functions Core Tools
  • خادم مصادقة وتخويل وهمية
  • تنفيذ التوجيهات المحلية وإعدادات التكوين

إشعار

غالبا ما تتطلب المواقع التي تم إنشاؤها باستخدام إطار عمل الواجهة الأمامية إعداد تكوين وكيل لمعالجة الطلبات تحت api المسار بشكل صحيح. عند استخدام Azure Static Web Apps CLI، تكون قيمة موقع الوكيل هي /api، وبدون CLI تكون القيمة http://localhost:7071/api.

كيفية عمله

يوضح المخطط التالي كيفية معالجة الطلبات محليا.

Diagram showing the Azure Static Web App CLI request and response flow.

هام

انتقل إلى http://localhost:4280 للوصول إلى التطبيق الذي يقدمه CLI.

  • تتم إعادة توجيه الطلبات المقدمة إلى المنفذ 4280 إلى الخادم المناسب استنادا إلى نوع الطلب.

  • تتم معالجة طلبات المحتوى الثابت، مثل HTML أو CSS، إما بواسطة خادم المحتوى الثابت CLI الداخلي، أو بواسطة خادم إطار عمل الواجهة الأمامية لتصحيح الأخطاء.

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

  • يعالج وقتتشغيل Functions Core Tools 1 الطلبات إلى واجهة برمجة تطبيقات الموقع.

  • يتم إرجاع الاستجابات من جميع الخدمات إلى المتصفح كما لو كانت جميعها تطبيقا واحدا.

بمجرد بدء تشغيل واجهة المستخدم وتطبيقات Azure Functions API بشكل مستقل، ثم ابدأ تشغيل Static Web Apps CLI وأشره إلى التطبيقات قيد التشغيل باستخدام الأمر التالي:

swa start http://localhost:<DEV-SERVER-PORT-NUMBER> --api-location http://localhost:7071

اختياريا، إذا كنت تستخدم swa init الأمر ، فإن Static Web Apps CLI يبحث في التعليمات البرمجية للتطبيق الخاص بك وينشئ ملف تكوين swa-cli.config.json ل CLI. عند استخدام ملف swa-cli.config.json ، يمكنك تشغيل swa start لتشغيل التطبيق محليا.

1 يتم تثبيت Azure Functions Core Tools تلقائيا بواسطة CLI إذا لم تكن موجودة بالفعل على نظامك.

توضح المقالة التالية بالتفصيل خطوات تشغيل تطبيق مستند إلى عقدة، ولكن العملية هي نفسها لأي لغة أو بيئة.

المتطلبات الأساسية

  • موقع Azure Static Web Apps الحالي: إذا لم يكن لديك واحد، فابدأ بتطبيق vanilla-api starter.
  • Node.js مع npm: قم بتشغيل إصدار Node.js LTS، والذي يتضمن الوصول إلى npm.
  • Visual Studio Code: يستخدم لتصحيح أخطاء تطبيق واجهة برمجة التطبيقات، ولكنه غير مطلوب ل CLI.

الشروع في العمل

افتح محطة طرفية إلى المجلد الجذر لموقع Azure Static Web Apps الحالي.

  1. تثبيت CLI.

    npm install -D @azure/static-web-apps-cli

    تلميح

    إذا كنت ترغب في تثبيت SWA CLI عالميا، فاستخدم -g بدلا من -D. ومع ذلك، يوصى بشدة بتثبيت SWA كتبعية تطوير.

  2. أنشئ تطبيقك إذا طلب تطبيقك ذلك.

    قم بتشغيل npm run build، أو الأمر المكافئ لمشروعك.

  3. تهيئة المستودع ل CLI.

    swa init

    أجب عن الأسئلة التي يطرحها CLI للتحقق من صحة إعدادات التكوين.

  4. ابدأ تشغيل CLI.

    swa start

  5. انتقل إلى http://localhost:4280 لعرض التطبيق في المستعرض.

طرق أخرى لبدء تشغيل CLI

‏‏الوصف الأمر تعليقات
خدمة مجلد معين swa start ./<OUTPUT_FOLDER_NAME> استبدل <OUTPUT_FOLDER_NAME> باسم مجلد الإخراج.
استخدام خادم تطوير إطار عمل قيد التشغيل swa start http://localhost:3000 يعمل هذا الأمر عندما يكون لديك مثيل للتطبيق الخاص بك يعمل تحت المنفذ 3000. تحديث رقم المنفذ إذا كان التكوين مختلفا.
بدء تشغيل تطبيق Functions في مجلد swa start ./<OUTPUT_FOLDER_NAME> --api-location ./api استبدل <OUTPUT_FOLDER_NAME> باسم مجلد الإخراج. يتوقع هذا الأمر أن تحتوي واجهة برمجة تطبيقات التطبيق الخاص بك على ملفات في api المجلد. تحديث هذه القيمة إذا كان التكوين الخاص بك مختلفا.
استخدام تطبيق Functions قيد التشغيل swa start ./<OUTPUT_FOLDER_NAME> --api-location http://localhost:7071 استبدل <OUTPUT_FOLDER_NAME> باسم مجلد الإخراج. يتوقع هذا الأمر أن يكون تطبيق Azure Functions متوفرا من خلال المنفذ 7071. تحديث رقم المنفذ إذا كان التكوين مختلفا.

محاكي التخويل والمصادقة

يحاكي Static Web Apps CLI تدفق الأمان المطبق في Azure. عند تسجيل دخول مستخدم، يمكنك تحديد ملف تعريف هوية مزيف تم إرجاعه إلى التطبيق.

على سبيل المثال، عند محاولة الانتقال إلى /.auth/login/github، يتم إرجاع صفحة تسمح لك بتعريف ملف تعريف الهوية.

إشعار

يعمل المحاكي مع أي موفر أمان، وليس فقط GitHub.

Local authentication and authorization emulator

يوفر المحاكي صفحة تسمح لك بتوفير القيم الأساسية للعميل التالية:

قيمة ‏‏الوصف
اسم المستخدم اسم الحساب المقترن بموفر الأمان. تظهر هذه القيمة كخاصية userDetails في كيان العميل ويتم إنشاؤها تلقائيا إذا لم توفر قيمة.
معرف المستخدم القيمة التي تم إنشاؤها تلقائيا بواسطة CLI.
الأدوار قائمة بأسماء الأدوار، حيث يكون كل اسم على سطر جديد.
المطالبات قائمة بمطالبات المستخدم، حيث يكون كل اسم على سطر جديد.

بمجرد تسجيل الدخول:

  • يمكنك استخدام /.auth/me نقطة النهاية أو نقطة نهاية دالة لاسترداد كيان العميل الخاص بالمستخدم.

  • التنقل لمسح /.auth/logout كيان العميل وتسجيل خروج المستخدم الوهمي.

التصحيح

هناك سياقان لتصحيح الأخطاء في تطبيق ويب ثابت. الأول لموقع المحتوى الثابت، والثاني لوظائف واجهة برمجة التطبيقات. تصحيح الأخطاء المحلي ممكن من خلال السماح ل Static Web Apps CLI باستخدام خوادم التطوير لأحد هذين السياقين أو كليهما.

توضح لك الخطوات التالية سيناريو شائع يستخدم خوادم التطوير لكل من سياقات تصحيح الأخطاء.

  1. بدء تشغيل خادم تطوير الموقع الثابت. هذا الأمر خاص بإطار العمل الأمامي الذي تستخدمه، ولكنه غالبا ما يأتي في شكل أوامر مثل npm run buildأو npm startأو npm run dev.

  2. افتح مجلد تطبيق API في Visual Studio Code وابدأ جلسة تصحيح الأخطاء.

  3. ابدأ تشغيل Static Web Apps CLI باستخدام الأمر التالي.

    swa start http://localhost:<DEV-SERVER-PORT-NUMBER> --appDevserverUrl http://localhost:7071

    استبدل <DEV_SERVER_PORT_NUMBER> برقم منفذ خادم التطوير.

تظهر لقطات الشاشة التالية المحطات لسيناريو تصحيح الأخطاء النموذجي:

يتم تشغيل موقع المحتوى الثابت عبر npm run dev.

Static site development server

يقوم تطبيق Azure Functions API بتشغيل جلسة تصحيح الأخطاء في Visual Studio Code.

Visual Studio Code API debugging

يتم تشغيل Static Web Apps CLI باستخدام خادمي التطوير.

Azure Static Web Apps CLI terminal

يتم الآن توجيه الطلبات التي تمر عبر المنفذ 4280 إما إلى خادم تطوير المحتوى الثابت أو جلسة تصحيح أخطاء واجهة برمجة التطبيقات.

لمزيد من المعلومات حول سيناريوهات تصحيح الأخطاء المختلفة، مع إرشادات حول كيفية تخصيص المنافذ وعناوين الخادم، راجع مستودع Azure Static Web Apps CLI.

نموذج تكوين تصحيح الأخطاء

يستخدم Visual Studio Code ملفا لتمكين جلسات تصحيح الأخطاء في المحرر. إذا لم ينشئ Visual Studio Code ملف launch.json لك، يمكنك وضع التكوين التالي في .vscode/launch.json.

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Attach to Node Functions",
            "type": "node",
            "request": "attach",
            "port": 9229,
            "preLaunchTask": "func: host start"
        }
    ]
}

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

تكوين التطبيق الخاص بك