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

توضّح هذه السلسلة من الجولات التفصيلية جميع العناصر المتغيرة لعملية عمل إضافة Classroom تتناول كل خطوة في جولة تفصيلية والمفاهيم وتنفيذها في تطبيق ويب واحد. الهدف هو مساعدتك في إعداد إضافة وظيفية وتهيئتها وإطلاقها.

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

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

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

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

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

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

مكان التنزيل

تتوفر أمثلة بايثون وJava في مستودعات جيت هب:

• مستودع Python

• مستودع Java

يمكن تنزيل نموذج Node.js كملف ZIP:

• أرشيف Node.js

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

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

شهادة HTTPS

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

يمكن استخدام localhost مع شهادة طبقة المقابس الآمنة (SSL). ضع في الاعتبار mkcert إذا تحتاج إلى إنشاء شهادة للتطوير المحلي.

مشروع Google Cloud

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

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

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

نقطة رئيسية: يجب أن يستخدم تطبيق الويب بيانات اعتماد OAuth 2.0 المُدارة في Google. Google Cloud.

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

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

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

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

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

التعرّف على الملفات

تصف الأقسام التالية تنسيق أمثلة الأدلة.

أسماء الأدلة

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

محتوى الدليل

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

Python

• يحتوي جذر الدليل على الملفات التالية:

  • main.py - نقطة إدخال تطبيق Python. تحديد الخادم الذي تريد استخدامه في هذا الملف، ثم قم بتشغيله إلى بدء تشغيل الخادم.
  • requirements.txt: وحدات Python المطلوبة لتشغيل تطبيق الويب يمكن تثبيت هذه التطبيقات تلقائيًا باستخدام pip install -r requirements.txt.

  • client_secret.json - ملف سر العميل الذي تم تنزيله من Google السحابة الإلكترونية يُرجى العِلم أنّ النموذج لم يتم تضمينه في أرشيف الأمثلة. CANNOT TRANSLATE إعادة تسمية ملف بيانات الاعتماد الذي تم تنزيله ونسخه في كل جذر الدليل.

    ملاحظة مهمة: يجب تقديم ملف سر العميل من ملف مشروع 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.

تشغيل نموذج الخادم

نقطة رئيسية: لا يمكن فتح تطبيق الويب إلا في Google Classroom عبر HTTPS. يمكنك الاطّلاع على قسم شهادة بروتوكول HTTPS للحصول على تفاصيل إضافية.

يجب تشغيل الخادم لاختباره. اتّبِع هذه التعليمات قم بتشغيل نموذج الخادم باللغة التي تختارها:

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

تشغيل الخادم

تحذير: قبل تشغيل الخادم، يجب إعداد مشروع Google Cloud للوصول إلى Classroom API وبيانات الاعتماد المطلوبة.

شغِّل تطبيق Python لتشغيل الخادم كما هو مكوَّن في الخطوة السابقة.

python main.py

انقر على عنوان URL الذي يظهر لعرض تطبيق الويب في أحد المتصفِّحات لتأكيد أن إنه يعمل بشكل صحيح.

Node.js

إعداد الخادم

لتشغيل الخادم عبر HTTPS، تحتاج إلى إنشاء شهادة ذاتية الذي يُستخدم لتشغيل التطبيق عبر HTTPS. يجب أن تكون بيانات الاعتماد هذه تم الحفظ باسم sslcert/cert.pem وsslcert/key.pem في جذر المستودع. المجلد. قد تحتاج إلى إضافة هذه المفاتيح إلى سلسلة مفاتيح نظام التشغيل من أجل في المتصفّح لقبولها.

تأكّد من أن *.pem في ملف .gitignore لأنك لا تريد. إتمام الملف في git.

تشغيل الخادم

تحذير: قبل تشغيل الخادم، يجب إعداد مشروع Google Cloud للوصول إلى Classroom API وبيانات الاعتماد المطلوبة.

يمكنك تشغيل التطبيق باستخدام الأمر التالي بدلاً من 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.

تشغيل الخادم

تحذير: قبل تشغيل الخادم، يجب إعداد مشروع Google Cloud للوصول إلى Classroom API وبيانات الاعتماد المطلوبة.

تشغيل الخادم من خلال تنفيذ طريقة 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.