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

توضّح هذه السلسلة من الجولات الإرشادية جميع الأجزاء المتحركة في إضافة Classroom عاملة. تتناول كل خطوة من خطوات الجولة الإرشادية مفاهيم محدّدة، وتطبّقها في تطبيق ويب واحد. والهدف من ذلك هو مساعدتك في إعداد إضافة عملية وضبطها وإطلاقها.

يجب أن يتفاعل تطبيقك الإضافي مع مشروع على Google Cloud. إذا لم تكن على دراية بـ Google Cloud، ننصحك بقراءة أدلة بدء الاستخدام. يمكنك إدارة بيانات الاعتماد وإذن الوصول إلى واجهة برمجة التطبيقات وحزمة تطوير البرامج (SDK) في Google Workspace Marketplace من خلال Google Cloud Console. لمزيد من المعلومات حول حزمة تطوير البرامج (SDK) في Marketplace، يُرجى الانتقال إلى صفحة دليل بطاقة بيانات Google Workspace Marketplace.

يتناول هذا الدليل المواضيع التالية:

  • استخدِم Google Cloud لإنشاء صفحة لعرضها في إطار iframe في Classroom.
  • إضافة ميزة "الدخول المُوحَّد" (SSO) من Google والسماح للمستخدمين بتسجيل الدخول
  • إجراء طلبات بيانات من واجهة برمجة التطبيقات لربط الإضافة بمهمة
  • تلبية متطلبات إرسال الإضافات الرئيسية والميزات المطلوبة

يفترض هذا الدليل أنّك على دراية بالبرمجة والمفاهيم الأساسية لتطوير الويب. ننصحك بشدة بقراءة دليل إعداد المشاريع قبل البدء في الجولات الإرشادية. تحتوي هذه الصفحة على تفاصيل مهمة حول الإعدادات لا يتم تناولها بشكل كامل في الجولات الإرشادية.

أمثلة على العناصر المنفّذة

يتوفّر مثال مرجعي كامل في Python. تتوفّر عمليات التنفيذ الجزئية أيضًا في Java وNode.js. هذه التطبيقات هي مصادر الرمز النموذجي المتوفّر في الصفحات اللاحقة.

مكان تنزيل التطبيق

تتوفّر أمثلة Python وJava في مستودعات GitHub:

يمكن تنزيل نموذج Node.js كملف مضغوط:

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

راجِع الأقسام التالية لإعداد مشروع جديد للإضافات.

شهادة HTTPS

على الرغم من أنّه يمكنك استضافة تطبيقك على أي بيئة تطوير، لن تتوفّر إضافة Classroom إلا من خلال https://. لذلك، تحتاج إلى خادم مزوّد بتشفير SSL لنشر تطبيقك أو اختباره ضمن إطار iframe الخاص بالإضافة.

يمكن استخدام localhost مع شهادة SSL، وننصحك باستخدام mkcert إذا كنت بحاجة إلى إنشاء شهادة للتطوير المحلي.

مشروع Google Cloud

عليك إعداد مشروع على Google Cloud لاستخدامه مع هذه الأمثلة. للحصول على نظرة عامة حول الخطوات اللازمة للبدء، يمكنك الاطّلاع على دليل إنشاء مشروع على Google Cloud. يتضمّن قسم إعداد مشروع Google Cloud في الجولة الإرشادية الأولى أيضًا خطوات حول إجراءات الإعدادات المحدّدة التي يجب اتّخاذها.

عند الانتهاء، نزِّل معرّف عميل OAuth 2.0 كملف JSON. عليك إضافة ملف بيانات الاعتماد هذا إلى دليل المثال الذي تم فك ضغطه. اطّلِع على فهم الملفات لمعرفة المواقع الجغرافية المحدّدة.

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

اتّبِع الخطوات التالية لإنشاء بيانات اعتماد OAuth جديدة:

  • انتقِل إلى صفحة بيانات اعتماد Google Cloud. تأكَّد من اختيار المشروع الصحيح في أعلى الشاشة.
  • انقر على إنشاء بيانات اعتماد واختَر معرّف عميل OAuth من القائمة المنسدلة.
  • في الصفحة التالية:
    • اضبط نوع التطبيق على تطبيق ويب.
    • ضمن معرّفات الموارد المنتظمة (URI) المعتمَدة لإعادة التوجيه، انقر على إضافة معرّف موارد منتظم (URI). أضِف المسار الكامل لمسار معاودة الاتصال الخاص بتطبيقك. على سبيل المثال، https://my.domain.com/auth-callback أو https://localhost:5000/callback. ستنشئ هذا المسار وتتعامل معه في وقت لاحق من هذا الدليل الإرشادي. يمكنك تعديل هذه المسارات أو إضافة المزيد منها في أي وقت.
    • انقر على إنشاء.
  • بعد ذلك، ستتلقّى مربّع حوار يتضمّن بيانات الاعتماد التي أنشأتها حديثًا. اختَر الخيار تنزيل ملف JSON. انسخ ملف JSON الذي تم تنزيله إلى دليل الخادم.

المتطلبات الأساسية الخاصة باللغة

يمكنك الاطّلاع على ملف README في كل مستودع للحصول على أحدث قائمة بالمتطلبات الأساسية.

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 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

فهم الملفات

توضّح الأقسام التالية تنسيق أدلة الأمثلة.

أسماء الأدلة

يحتوي كل مستودع على عدة أدلة تبدأ أسماؤها برقم، مثل /01-basic-app/. تتوافق الأرقام مع خطوات إرشادية محدّدة. يحتوي كل دليل على تطبيق ويب يعمل بكامل وظائفه وينفّذ الميزات الموضّحة في جولة إرشادية معيّنة. على سبيل المثال، يحتوي دليل /01-basic-app/ على التنفيذ النهائي لإرشادات إنشاء إضافة.

محتويات الدليل

تختلف محتويات الدليل حسب لغة التنفيذ:

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.