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

Python

يستخدم مثال بايثون إطار عمل Flask. يمكنك تنزيل رمز المصدر الكامل من الرابط أعلاه.

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

python3 -m ensurepip --upgrade

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

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

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

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

Node.js

يستخدم مثال Node.js إطار العمل السريع. يمكنك تنزيل رمز المصدر الكامل من الرابط أعلاه.

يتطلّب هذا المثال توفُّر Node.js v16.13 أو إصدار أحدث.

ثبِّت وحدات العُقد المطلوبة باستخدام 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 - نقطة دخول تطبيق بايثون. حدد تهيئة الخادم التي تريد استخدامها في هذا الملف، ثم شغلها لبدء تشغيل الخادم.
  • 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 ومصنع مخزن بيانات الملفات. يمكن العثور على مزيد من المعلومات حول إعداد متاجر البيانات هذه في الجولة التفصيلية الثالثة حول التعامل مع الزيارات المتكرّرة.
  • mvnw وmvnw.cmd هما البرنامجان التنفيذيان لبرنامج Maven الذي يضم ملفات Unix وWindows، على التوالي. على سبيل المثال، يؤدي تشغيل ./mvnw --version على Unix إلى إخراج إصدار Apache Maven، بالإضافة إلى معلومات أخرى.
  • يحتوي دليل .mvn على إعدادات برنامج تضمين Maven.

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_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:3000.

يمكنك إنهاء الخادم الذي يتضمّن 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' في دليل 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.