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

Python

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

إذا لزم الأمر، ثبِّت الإصدار 3.7 أو الإصدارات الأحدث من Python وتأكّد من توفّر 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 لدينا إطار عمل Express. يمكنك تنزيل رمز المصدر الكامل من الروابط المتوفّرة.

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

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

npm install

Java

يستخدم مثال Java إطار عمل التمهيد الربيعي. يمكنك تنزيل رمز المصدر الكامل من الروابط المتوفّرة.

تثبيت 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.
• يمكن العثور على أجهزة توجيه Express في ./<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) للوسيطة 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' في الدليل 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.