جولات تفصيلية

Python

يستخدم مثال Python إطار عمل Flask. يمكنك تنزيل رمز المصدر الكامل من الروابط المقدَّمة.

إذا لزم الأمر، ثبِّت Python 3.7 والإصدارات الأحدث وتأكَّد من توفّر pip.

python3 -m ensurepip --upgrade

ننصحك أيضًا بإعداد بيئة افتراضية جديدة لـ Python وتفعيلها.

python3 -m venv .classroom-addon-env
source .classroom-addon-env/bin/activate

يظهر الرمز requirements.txt في كل دليل فرعي للحلّ المفصّل في الأمثلة التي تم تنزيلها. يمكنك تثبيت المكتبات المطلوبة بسرعة باستخدام pip. استخدِم الأوامر التالية لتثبيت المكتبات المطلوبة ل walkthrough الأولى.

cd flask/01-basic-app
pip install -r requirements.txt

Node.js

يستخدم مثال Node.js إطار عمل Express. يمكنك تنزيل رمز المصدر الكامل من الروابط المقدَّمة.

يتطلّب هذا المثال استخدام الإصدار 16.13 من Node.js أو إصدار أحدث.

ثبِّت وحدات العقدة المطلوبة باستخدام npm.

npm install

Java

يستخدم مثال Java إطار عمل Spring Boot. يمكنك تنزيل رمز المصدر الكامل من الروابط المقدَّمة.

ثبِّت Java 11 والإصدارات الأحدث إذا لم يكن مثبّتًا على جهازك.

يمكن لتطبيقات Spring Boot استخدام Gradle أو Maven لمعالجة عمليات الإنشاء وإدارة التبعيات. يتضمّن هذا المثال حزمة Maven التي تضمن اكتمال عملية الإنشاء بنجاح بدون الحاجة إلى تثبيت Maven نفسه.

في الدليل الذي تم تنزيل المشروع أو نسخه فيه، نفِّذ الطلبات التالية لضمان توفّر المتطلبات الأساسية لتشغيل المشروع.

java --version
./mvnw --version

أو على نظام التشغيل Windows:

java -version
mvnw.cmd --version

Python

• يحتوي جذر الدليل على الملفات التالية:

  • main.py - نقطة دخول تطبيق Python. حدِّد إعدادات الخادم التي تريد استخدامها في هذا الملف، ثم نفِّذها لبدء الخادم.
  • requirements.txt: وحدات Python المطلوبة لتشغيل تطبيق الويب: يمكن تثبيتها تلقائيًا باستخدام pip install -r requirements.txt.

  • client_secret.json: ملف سر العميل الذي تم تنزيله من Google Cloud يُرجى العِلم أنّ هذا الإجراء غير مُدرَج في مثال الأرشيف، ويجب إعادة تسمية ملف بيانات الاعتماد الذي تم تنزيله ونسخه إلى كل دليل جذر.

• config.py - خيارات الضبط لخادم Flask

• يحتوي دليل webapp على محتوى تطبيق الويب. ويشمل ذلك ما يلي:

• دليل /templates/ الذي يتضمّن نماذج Jinja لصفحات مختلفة

• دليل /static/ الذي يتضمّن الصور وCSS وملفات JavaScript المساعدة

• ‫routes.py - طرق معالِج مسارات تطبيقات الويب

• __init__.py: دالة الإعداد لوحدة webapp. يشغِّل ملف الإعدادات هذا خادم Flask ويحمِّل خيارات الإعدادات التي تم ضبطها في config.py.

• ملفات إضافية حسب الحاجة في خطوة معيّنة من الخطوات الإرشادية

Node.js

يمكن العثور على كل خطوة من الخطوات في مجلّدها الفرعي <step>. تحتوي كل خطوة على ما يلي:

• يمكن العثور على الملفات الثابتة، مثل JavaScript وCSS والصور، في مجلد ./<step>/public.
• يمكن العثور على أجهزة التوجيه السريعة في مجلدات ./<step>/routes.
• يمكن العثور على نماذج HTML في مجلدات ./<step>/views.
• تطبيق الخادم هو ./<step>/app.js.

Java

يتضمّن دليل المشروع ما يلي:

• يحتوي الدليل src.main على رمز المصدر والإعدادات لتشغيل التطبيق بنجاح. يتضمّن هذا الدليل ما يلي: + يحتوي دليل java.com.addons.spring علىملفَي Application.java وController.java. يتحمّل ملف Application.java مسؤولية تشغيل خادم التطبيقات، بينما يعالج ملف Controller.java منطق نقاط النهاية. + يحتوي الدليل resources على الدليل templates الذي يتضمّن ملفات HTML وJavaScript. يحتوي أيضًا على ملف application.properties الذي يحدِّد المنفذ لتشغيل الخادم والمسار إلى ملف ملف تخزين المفاتيح والمسار إلى الدليل templates. يتضمّن هذا المثال ملف تخزين المفاتيح في الدليل resources. يمكنك تخزينه في المكان الذي تفضّله، ولكن تأكَّد من تعديل ملف application.properties بالمسار وفقًا لذلك.
  • يحتوي pom.xml على المعلومات اللازمة لإنشاء المشروع وتحديد التبعيات المطلوبة.
  • يحتوي .gitignore على أسماء ملفات لا يجب تحميلها إلى git. تأكَّد من إضافة مسار ملف تخزين المفاتيح في هذا .gitignore. في المثال المقدَّم، يكون هذا العنصر هو secrets/*.p12 (يتم مناقشة الغرض من متجر المفاتيح في القسم أدناه). بالنسبة إلى الخطوات 2 وما بعد، يجب أيضًا تضمين مسار ملف client_secret.json لضمان عدم تضمين أسرارك في مستودع بعيد. بالنسبة إلى الجولة الإرشادية 3 والمراحل اللاحقة، يجب إضافة المسار إلى ملف قاعدة بيانات H2 وملف datastore factory. يمكنك الاطّلاع على مزيد من المعلومات حول إعداد مستودعات البيانات هذه في الخطوة الثالثة من الشرح التفصيلي حول معالجة الزيارات المتكرّرة.
  • mvnw وmvnw.cmd هما ملفّا التشغيل لبرنامج Maven لنظامَي التشغيل Unix و Windows، على التوالي. على سبيل المثال، يؤدي تشغيل ./mvnw --version على نظام التشغيل Unix إلى عرض إصدار Apache Maven، بالإضافة إلى معلومات أخرى.
  • يحتوي دليل .mvn على إعدادات لملف Maven wrapper.

Python

بيانات اعتماد OAuth

أنشئ بيانات اعتماد OAuth ونزِّلها كما هو موضّح سابقًا. ضَع ملف JSON في الدليل الجذر بجانب ملف إشعال الخادم الخاص بتطبيقك.

ضبط الخادم

تتوفّر لك عدة خيارات لتشغيل خادم الويب. في نهايةملف Python، أضِف أحد الخيارَين التاليَين:

1. localhost غير مؤمَّن تجدر الإشارة إلى أنّ هذا الإجراء مناسب للاختبار المباشر في نافذة متصفّح فقط، ولا يمكن تحميل النطاقات غير الآمنة في ملف iframe الخاص بإضافة Classroom.

   if __name__ == "__main__":
     # Disable OAuthlib's HTTPs verification.
     os.environ["OAUTHLIB_INSECURE_TRANSPORT"] = "1"
   
     # Run the web app at http://localhost:5000.
     app.run(debug=True)
   

2. تأمين localhost يجب تحديد مجموعة من ملفات مفاتيح بروتوكول أمان طبقة النقل (SSL) للوسيطة ssl_context.

   if __name__ == "__main__":
     # Run the web app at https://localhost:5000.
     app.run(host="localhost",
             ssl_context=("localhost.pem", "localhost-key.pem"),
             debug=True)
   

3. خادم Gunicorn هذا مناسب لنشر خادم أو سحابة سحابية جاهزَين للاستخدام. ننصحك بضبط متغيّر بيئة PORT لاستخدامه مع خيار الإطلاق هذا.

   if __name__ == "__main__":
     # Run the web app at https://<your domain>:<server_port>.
     # Defaults to https://<your domain>:8080.
     server_port = os.environ.get("PORT", "8080")
     app.run(debug=True, port=server_port, host="0.0.0.0")
   

بدء تشغيل الخادم

شغِّل تطبيق Python لبدء تشغيل الخادم على النحو الذي تم ضبطه في الخطوة السابقة.

python main.py

انقر على عنوان URL الذي يظهر لعرض تطبيق الويب في متصفّح للتأكّد من عمله بشكل صحيح.

Node.js

ضبط الخادم

لتشغيل الخادم عبر HTTPS، عليك إنشاء شهادة ذاتية تُستخدَم لتشغيل التطبيق عبر HTTPS. يجب حفظ بيانات الاعتماد هذه باسمَي sslcert/cert.pem وsslcert/key.pem في مجلّد ملفّات ملفّات الدليل العميق للمستودع. قد تحتاج إلى إضافة هذه المفاتيح إلى سلسلة مفاتيح نظام التشغيل لكي يقبلها المتصفّح.

تأكَّد من أنّ *.pem متوفّرة في ملف .gitignore لأنّك لا تريد إرسال الملف إلى git.

بدء تشغيل الخادم

يمكنك تشغيل التطبيق باستخدام الأمر التالي مع استبدال step01 بالخطوة الصحيحة التي تريد تنفيذها كخادم (على سبيل المثال، step01 لـ 01-basic-app وstep02 لـ 02-sign-in).

npm run step01

أو

npm run step02

يؤدي ذلك إلى تشغيل خادم الويب على https://localhost:5000.

يمكنك إنهاء الخادم باستخدام Control + C في المحطة الطرفية.

Java

ضبط الخادم

لتشغيل الخادم عبر HTTPS، عليك إنشاء شهادة ذاتية تُستخدَم لتشغيل التطبيق عبر HTTPS.

ننصحك باستخدام mkcert لتطوير التطبيقات على الجهاز. بعد تثبيت mkcert، تُنشئ الأوامر التالية شهادة مخزّنة على الجهاز لاستخدامها مع بروتوكول HTTPS.

mkcert -install
mkcert -pkcs12 -p12-file <path_to_keystore> <domain_name>

يتضمّن هذا المثال ملف ملف تخزين المفاتيح في دليل الموارد. يمكنك حفظه في المكان الذي تفضّله، ولكن تأكَّد من تعديل ملف application.properties بالمسار وفقًا لذلك. اسم النطاق هو النطاق الذي تُشغِّل المشروع عليه (على سبيل المثال، localhost).

تأكَّد من أنّ *.p12 متوفّرة في ملف .gitignore لأنّك لا تريد إرسال الملف إلى git.

بدء تشغيل الخادم

ابدأ الخادم من خلال تشغيل طريقة main في ملف Application.java. في IntelliJ، على سبيل المثال، يمكنك النقر بزر الماوس الأيمن على Application.java > Run 'Application' في directory src/main/java/com/addons/spring أو فتح ملفApplication.java للانقر على السهم الأخضر على يمين توقيع الأسلوبmain(String[] args). بدلاً من ذلك، يمكنك تشغيل المشروع في ملف تعريف مستخدم الطرفية:

./mvnw spring-boot:run

أو على نظام التشغيل Windows:

mvnw.cmd spring-boot:run

يؤدي ذلك إلى تشغيل الخادم على https://localhost:5000 أو على المنفذ الذي حدّدته في application.properties.