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

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. استخدِم الأوامر التالية لتثبيت المكتبات المطلوبة للإرشادات المفصّلة الأولى.

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

Node.js

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

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

ثبِّت وحدات node المطلوبة باستخدام 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.
• تتوفّر أجهزة توجيه 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.