توضّح هذه السلسلة من الجولات التفصيلية جميع الأجزاء المتحركة لإضافة Classroom قيد العمل. تتناول كل خطوة تفصيلية مفاهيم محددة، وتنفذها في تطبيق ويب واحد. الهدف هو مساعدتك في إعداد وتهيئة وإطلاق إضافة عملية.
يجب أن تتفاعل الإضافة مع مشروع على Google Cloud. إذا لم تكن معتادًا على استخدام Google Cloud، ننصحك بقراءة أدلة البدء. يمكنك إدارة بيانات الاعتماد والوصول إلى واجهة برمجة التطبيقات وحزمة GWM SDK في Google Cloud Console. لمزيد من المعلومات حول حزمة تطوير البرامج (SDK) لأداة GWM، انتقِل إلى صفحة دليل بيانات Google Workspace Marketplace.
يشمل هذا الدليل المواضيع التالية:
- يمكنك استخدام Google Cloud لإنشاء صفحة لعرضها في إطار iframe في Classroom.
- إضافة خدمة الدخول المُوحَّد (SSO) إلى Google والسماح للمستخدمين بتسجيل الدخول.
- يمكنك إجراء طلبات بيانات من واجهة برمجة التطبيقات لإرفاق الإضافة بمهمة.
- يجب استيفاء متطلبات إرسال الإضافة الأساسية والميزات المطلوبة.
يفترض هذا الدليل أنّك على دراية بالمفاهيم الأساسية للبرمجة وتطوير الويب. نوصي بضرورة قراءة دليل تهيئة المشروع قبل البدء في الجولات التفصيلية. تحتوي هذه الصفحة على تفاصيل مهمة للإعدادات لم يتم تناولها بالكامل في الجولات التفصيلية.
أمثلة على العناصر المنفّذة
تتوفّر أمثلة مرجعية كاملة في JavaScript وPython وJava. وهذه العمليات هي مصادر الرمز النموذجي الذي تم العثور عليه في الصفحات اللاحقة.
أماكن تنزيل الملفات
ويمكن تنزيل أرشيفات كاملة من الأمثلة باستخدام الروابط أدناه.
المتطلبات الأساسية
راجِع الأقسام التالية لإعداد مشروع إضافات جديد.
شهادة 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
يستخدم مثال بايثون إطار عمل 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
فهم الملفات
تصف الأقسام التالية تنسيق نماذج الأدلة.
أسماء الأدلة
ويحتوي كل أرشيف على عدة أدلة تبدأ أسماؤها برقم، مثل /01-basic-app/
. تتوافق الأرقام مع خطوات تفصيلية محددة. ويحتوي كل دليل على تطبيق ويب يعمل بكامل طاقته وينفذ الميزات الموضحة في جولة تفصيلية محددة. على سبيل المثال، يحتوي دليل /01-basic-app/
على التنفيذ النهائي للجولة التفصيلية إنشاء إضافة.
محتوى الدليل
يختلف محتوى الدليل وفقًا للغة التنفيذ:
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، أضِف واحدًا مما يلي:
"
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)
الحفاظ على أمان "
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)
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
.