تتضمّن هذه الصفحة المعلومات التي تحتاج إلى معرفتها حول إنشاء مشاريع Google Cloud وإعدادها لاستخدام إضافات Classroom. تُستخدَم مشاريع Google Cloud لتنفيذ ميزة "الدخول المُوحَّد من Google" من خلال بروتوكول OAuth 2.0، وللسماح بالطلبات التي تقدّمها الإضافة، ولإدارة بطاقة بيانات الإضافة في متجر Google Workspace Marketplace.
للحصول على مزيد من المعلومات العامة حول نشر إضافة على Marketplace، يُرجى الاطّلاع على نشر تطبيق.
إنشاء مشروع على Google Cloud
هناك نوعان من المشاريع التي يمكن إنشاؤها: مشروع خاص يُستخدم في التطوير ومشروع عام يمكن للمستخدمين النهائيين الوصول إليه. يشير التصنيفان "عام" و"خاص" إلى إمكانية ظهور تطبيقك في Google Workspace Marketplace، إذ لا يمكن للمستخدمين تثبيت تطبيق خاص من Marketplace إلا إذا كانوا ضمن النطاق الذي تم إنشاء التطبيق فيه، بينما يكون تطبيق Marketplace العام متاحًا لأي نطاق في Google Workspace. يجب أن يكونا تطبيقَين منفصلَين، لأنّه لا يمكن أن يكون المشروع علنيًا وخاصًا في الوقت نفسه. يجب مراجعة التطبيقات العامة والموافقة عليها قبل إتاحتها في السوق.
للحصول على معلومات عامة حول إنشاء مشاريع Google Cloud، يُرجى الانتقال إلى مقالة إنشاء مشروع على Google Cloud.
إنشاء مشروع علني على Google Cloud
يمثّل هذا المشروع تطبيق الإضافة الذي يمكن للمشرفين والمعلّمين والطلاب الوصول إليه. يجب أن يراجع فريق Google Workspace Marketplace المشروع العام ويوافق عليه قبل إطلاقه أو تثبيته.
أنشئ مشروعًا جديدًا على Google Cloud في نطاق الإنتاج.
فعِّل Classroom API في مشروعك على Google Cloud.
فعِّل حزمة تطوير البرامج (SDK) في Google Workspace Marketplace في مشروعك على Cloud.
تفعيل حزمة تطوير البرامج (SDK) في Google Workspace Marketplace
اضبط إعدادات التطبيق في حزمة تطوير البرامج (SDK) في Marketplace على إمكانية الوصول إلى التطبيق علني، وضَع علامة في المربّع غير مُدرَج.
أكمِل الحقول المطلوبة في صفحة بطاقة بيانات المتجر ضمن حزمة تطوير البرامج (SDK) في Marketplace، ثم انقر على نشر.
سيراجع فريق Google Workspace Marketplace تطبيقك. سيتواصلون معك باستخدام عنوان البريد الإلكتروني للمطوّر المحدّد في حزمة تطوير البرامج (SDK) الخاصة بـ Marketplace. بعد الموافقة على التطبيق، أزِل العلامة من المربّع غير مُدرَج ليتمكّن المعلّمون والمشرفون من العثور عليه في Marketplace.
إنشاء مشروع خاص على Google Cloud
يمثّل مشروع خاص هذا تطبيق الإضافة المستخدَم في عملية التطوير. لا يمكن للمستخدمين خارج النطاق الذي تم إنشاؤه فيه الوصول إليه، ولكن لا يلزم الحصول على موافقة قبل تثبيته. لذلك، تنصح Google باستخدام هذا المشروع لتطوير إضافتك واختبارها في بيئة خاضعة للرقابة.
يجب أن يكون لديك إذن الوصول إلى نطاق Google Workspace for Education مع ترخيص Teaching & Learning أو Plus لإنشاء مشروع خاص. إذا لم يكن لديك إذن الوصول إلى نطاق من هذا النوع، اتّبِع الخطوات التالية لإعداد نطاق تجريبي في Google Workspace for Education وترقيته إلى ترخيص Plus والسماح له بالوصول إلى واجهة برمجة التطبيقات الخاصة بإضافات Classroom:
- أكمِل الخطوات للحصول على نطاق اختبار خاص بالمطوّرين.
أثناء تسجيل الدخول بصفتك مشرفًا في النطاق التجريبي، أنشئ مشروعًا جديدًا في Google Cloud.
إذا لم تتمكّن من الوصول إلى Google Cloud Console أو إنشاء مشاريع Cloud، تحقَّق من ما يلي في وحدة تحكّم المشرف:
- انتقِل إلى صفحة إعدادات الحساب > إعدادات الوصول المستند إلى العمر وحدِّد الخيار تبلغ أعمار كل المستخدمين في هذه المجموعة أو الوحدة التنظيمية 18 عامًا أو أكبر.
- ضمن التطبيقات > خدمات Google الإضافية:
- تكون خدمة Google Cloud Platform مفعّلة للجميع.
- إعدادات إنشاء المشاريع هي السماح للمستخدمين بإنشاء مشاريع.
- إعدادات الوصول إلى Cloud Shell هي السماح بالوصول إلى Cloud Shell.
أكمِل نموذج طلب ترقية النطاق التجريبي وأرسِله. يؤدي إرسال هذا النموذج إلى طلب ترقية نطاقك التجريبي إلى Google Workspace for Education Plus مع عشر تراخيص، كما يسمح لمشروعك على Cloud بالوصول إلى واجهة برمجة التطبيقات الخاصة بإضافات Classroom.
ستتلقّى رسالة إلكترونية عند اكتمال عملية الترقية وعملية الإضافة إلى القائمة المسموح بها. امنح تراخيص Plus لحسابات المعلّمين التجريبية في وحدة تحكّم المشرف. ضمن الدليل > المستخدمون، أنشئ حسابات المعلّمين التجريبية أو اختَرها. في تراخيص كل معلّم، تأكَّد من تعيين Google Workspace for Education Plus.
فعِّل Classroom API في مشروعك على Google Cloud.
فعِّل حزمة تطوير البرامج (SDK) في Google Workspace Marketplace في مشروعك على Cloud.
تفعيل حزمة تطوير البرامج (SDK) في Google Workspace Marketplace
اضبط إعدادات التطبيق في حزمة تطوير البرامج (SDK) في Marketplace ظهور التطبيق على خاص.
أكمِل الحقول المطلوبة في صفحة بطاقة بيانات المتجر ضمن حزمة تطوير البرامج (SDK) في Marketplace، ثم انقر على نشر. بعد نشر بطاقة بيانات التطبيق، يمكن للمستخدمين في النطاق العثور على التطبيق وتثبيته من خلال Google Workspace Marketplace أو من خلال الانتقال إلى عنوان URL للتطبيق المعروض في صفحة "بطاقة بيانات المتجر".
OAuth 2.0
يتطلّب الوصول إلى Classroom API الحصول على موافقة المستخدم على الوصول إلى بياناته. يتم الحصول على هذه الرموز من خلال طلب إذن من Google بالوصول إلى نطاقات OAuth للمستخدم الذي سجّل الدخول، وتلقّي رمز مميّز يمكن استخدامه لاحقًا لإجراء طلبات بيانات من واجهة برمجة التطبيقات إلى Google Classroom. يجب ضبط النطاقات في بطاقة بيانات المتجر على Google Workspace Marketplace ليتمكّن مشرف النطاق من تقديم الموافقة نيابةً عن مستخدمي النطاق في حال تثبيتهم للإضافة.
بما أنّ نطاقات Classroom حسّاسة، عليك طلب التحقّق من OAuth قبل إطلاق الإضافة. وفي حال عدم توفّرها، ستظهر للمستخدمين رسالة تحذيرية تفيد بأنّ التطبيق لم يتم التحقّق منه، ولن يتمكّن سوى عدد قليل من المستخدمين من الوصول إلى منتجك. يمكنك الاطّلاع على نظرة عامة على سلسلة المراجعات لمزيد من المعلومات حول عملية إثبات الملكية.
راجِع صفحة نطاقات OAuth لواجهات Google APIs للاطّلاع على قائمة تفصيلية بجميع النطاقات المتاحة واستخداماتها. اطّلِع على صفحة إعداد OAuth في مستندات Workspace للحصول على معلومات عامة حول إعدادات OAuth.
أذونات المستخدمين
يجب أن يطلب تطبيق الويب إذن الوصول إلى نطاق واحد على الأقل من النطاقات التالية:
-
https://www.googleapis.com/auth/userinfo.email
، الذي يسمح لأحد التطبيقات بالاطّلاع على عنوان البريد الإلكتروني للمستخدم. -
https://www.googleapis.com/auth/userinfo.profile
، الذي يسمح لأحد التطبيقات بالاطّلاع على المعلومات الشخصية، مثل الصورة الشخصية والاسم الأول والأخير وغيرها من المعلومات الشخصية التي أتاحها المستخدم للجميع.
بعد أن يمنح المستخدم الإذن لأحد هذه النطاقات في الإضافة، يتم تحديد هويته من خلال مَعلمة طلب البحث login_hint
. يتم تمرير هذه المَعلمة إلى أي من عناوين URL لتطبيق الويب عند فتح إطار iframe. إذا لم يمنح المستخدم الإذن لأحد هذه النطاقات، لن يتم إرسال login_hint
.
login_hint
هي مَعلمات OpenID Connect عادية يمكنك اختياريًا تمريرها إلى Google عند استخدام ميزة "تسجيل الدخول باستخدام حساب Google" أو طلب رمز OAuth مميز. ويهدف إلى تسهيل تجربة المستخدم النهائي في الحصول على إذن.
نطاقات إضافات Classroom
تخصّ النطاقات التالية إضافات Classroom:
https://www.googleapis.com/auth/classroom.addons.teacher
، ما يتيح الوصول إلى جميع طرق واجهة برمجة التطبيقات.https://www.googleapis.com/auth/classroom.addons.student
، الذي يتيح الوصول إلى عمليات التحقّق من صحة الإطلاق وعمليات قراءة المرفقات.
حتى مع توفّر رمز دخول صالح عبر OAuth يشير إلى بيانات اعتماد المستخدم، تخضع طلبات البيانات من واجهة برمجة التطبيقات لمتطلبات إضافية:
- تتطلّب جميع الطرق أن يكون المستخدم معلّمًا أو طالبًا في الدورة التدريبية المحدّدة من خلال
courseId
في الطلب. - يتطلّب إنشاء المرفقات وتعديلها وحذفها وإعادة الدرجات أن يكون المستخدم معلّمًا.
- يتم التحكّم في الوصول إلى منشور معيّن في Google Classroom من خلال عمليات التحقّق التالية.
- عندما تتضمّن إضافة واحدة على الأقل مرفقًا في مشاركة، يمكنها تقديم طلبات بشأن ما يلي:
- التحقّق من صحة إطلاق إطار iframe
- عمليات قراءة المرفقات وتعديلها وحذفها
- تعديلات العلامات على تلك المشاركة
- عند فتح إطار iframe الخاص بميزة "اقتراح المرفقات" لأول مرة، قد لا تكون الإضافة قد أضافت مرفقًا إلى المشاركة بعد. يتم توفير مَعلمة طلب البحث
addOnToken
التي يمكن استخدامها لتقديم طلبات بشأن ما يلي:- إنشاء مرفق ضمن المشاركة (
addOnToken
مطلوب) - إطلاق عملية التحقّق (يتم التحقّق من
addOnToken
إذا تم توفيره وهو مطلوب عندما لا يكون للملحق مرفق حالي في المشاركة)
- إنشاء مرفق ضمن المشاركة (
- عندما تتضمّن إضافة واحدة على الأقل مرفقًا في مشاركة، يمكنها تقديم طلبات بشأن ما يلي:
التحقّق من OAuth
تستخدم إضافات Classroom واجهات Google API للوصول إلى بيانات مستخدمي Google.
يُرجى الرجوع إلى الأسئلة الشائعة حول إثبات ملكية واجهة برمجة تطبيقات OAuth للحصول على مزيد من المعلومات حول عملية إثبات الملكية.
بطاقة بيانات Google Workspace Marketplace
للحصول على معلومات عامة حول إعداد حزمة تطوير البرامج (SDK) في Google Workspace Marketplace، يُرجى الانتقال إلى تفعيل حزمة تطوير البرامج (SDK) في Google Workspace Marketplace وإعدادها وإنشاء بطاقة بيانات متجر في Google Workspace Marketplace.
اعتبارات بطاقة بيانات المتجر
يحدّد بطاقة بيانات المتجر في حزمة تطوير البرامج (SDK) الخاصة بـ Marketplace في مشروع Google Cloud العام اسم تطبيقك وأوصافه المخصّصة للمستخدمين النهائيين. يمكنك تقديم هذه التفاصيل بلغات متعددة ضمن تفاصيل التطبيق.
اتّبِع هذه الإرشادات في بياناتك:
- ضمن تفاصيل التطبيق:
- تجنَّب استخدام علامات الترقيم في "اسم التطبيق". على سبيل المثال، استخدِم "الإضافة الخاصة بي من قِبل شركتي" بدلاً من "شركتي: الإضافة الخاصة بي" أو "الإضافة الخاصة بي، من قِبل شركتي".
- يجب ألا يحتوي الوصف المختصر والوصف التفصيلي على النص نفسه تمامًا.
- تأكَّد من اختيار قيمة للحقل السعر. يتضمّن هذا الحقل خيارات مجانًا ومدفوع مع فترة تجريبية مجانية ومدفوع مع ميزات مجانية ومدفوع. لست بحاجة إلى تحديد مبلغ التكلفة في بطاقة بيانات Marketplace.
- تأكَّد من اختيار قيمة للحقل الفئة. قد يكون المراجع الأكاديمية أو أدوات المعلّمين والمشرفين خيارًا جيدًا لإضافة Classroom.
- لمزيد من المعلومات، اطّلِع على العناصر المدرَجة في وصف تفاصيل التطبيق في Marketplace.
- ضمن أصول الرسومات:
- أن تكون أي مواد عرض رسومية مقدَّمة غير مشوّشة وتستوفي الأحجام المحدّدة في معايير Google Workspace Marketplace
- يجب أن تكون أي لقطات شاشة مقدَّمة تمثيلاً دقيقًا لتجربة الإضافة.
- ضمن روابط الدعم:
- تأكَّد من توفير رابط يؤدي إلى بنود الخدمة الخاصة بتطبيقك.
- تأكَّد من استيفاء إرشادات بناء هوية العلامة التجارية في واجهات برمجة التطبيقات من Google التي تتناول الأسماء والأوصاف المسموح بها.
- إذا أشرت إلى أي منتجات من Google في بطاقة بياناتك، استخدِم اسمها بالتنسيق الوارد في قائمة العلامات التجارية. تأكَّد من تضمين رمز العلامة التجارية (™) إذا كان ذلك محددًا، واستخدِم "مستندات Google™" بدلاً من "مستندات Google".
الدمج مع خدمات الترخيص والفوترة من Google
إذا كنت مهتمًا بالسماح لتطبيقاتك على Google Workspace Marketplace بالاندماج مع خدمات الترخيص والفوترة من Google، يُرجى الانتقال إلى Marketplace API.
إعدادات التثبيت
يمكن أن تسمح الإضافات بالتثبيت الفردي بالإضافة إلى التثبيت من قِبل المشرف. توضّح هذه الصفحة بعض الاختلافات بين نوعَي التثبيت، ولا تهدف إلى الترويج لأي منهما. يمكنك اختيار ما إذا كنت تريد السماح بالتثبيت الفردي في صفحة "إعدادات التطبيق" في حزمة تطوير البرامج (SDK) في Google Workspace Marketplace.
التثبيت من خلال المشرف
تتيح عمليات التثبيت من المشرف للمشرف إضافة إضافة إلى جميع الحسابات في نطاق أو إلى مجموعات وصول أو وحدات تنظيمية معيّنة. يمكن لمشرف النطاق فقط إجراء عملية تثبيت للمشرف. يمكن للمشرف الموافقة اختياريًا على جميع نطاقات الوصول نيابةً عن جميع المستخدمين في النطاق، ولن يُطلب من المستخدمين الموافقة على أي نطاقات وصول إذا اختار المشرف إجراء ذلك.
في ما يلي بعض الاعتبارات المتعلّقة بتثبيت المشرف.
- عناصر تحكّم أكثر صرامة: يمكن للمشرفين حصر المستخدمين الذين يمكنهم الوصول إلى إضافة.
- التوافق مع الترخيص: إذا كان تطبيقك يتطلّب ترخيصًا، قد يساعد توجيه عمليات التثبيت من خلال مشرف في ضمان توزيع التراخيص واستخدامها بشكل مناسب مع المؤسسة المعنية.
- تقليل العبء على المستخدمين النهائيين: يقلّل التثبيت من قِبل المشرف عبء الإعداد على المعلّمين والطلاب. قد يؤدي ذلك إلى تقديم تجربة أكثر سلاسة للمستخدمين مع عدد أقل من النقرات وفرص أقل لحدوث أي التباس.
لمزيد من المعلومات حول كيفية إجراء عمليات التثبيت من قِبل المشرفين، يُرجى الاطّلاع على مقالة تثبيت تطبيقات Marketplace في نطاقك، ولمزيد من المعلومات حول الوحدات التنظيمية ومجموعات الوصول، يُرجى الاطّلاع على مقالة كيفية عمل البنية التنظيمية.
التثبيت الفردي
تضيف عمليات التثبيت الفردية إضافة إلى حساب المستخدم. يُطلب من المستخدم الموافقة على نطاقات الوصول الخاصة بالإضافة أثناء التثبيت.
في ما يلي بعض الاعتبارات المتعلقة بالتثبيت الفردي.
- تسهيل الاستخدام: يمكن لعدد أكبر من المستخدمين الاطّلاع على الإضافة وتثبيتها من Google Workspace Marketplace. قد يؤدي السماح بالتثبيت الفردي إلى تشجيع المزيد من المعلّمين على استخدام منتجك أو الترويج له.
- اختبار المشرف يمكن للمشرف تثبيت إضافة بشكل فردي لاختبارها أو تقييمها قبل الموافقة عليها أو تثبيتها لمجموعة أكبر.
بالإضافة إلى تثبيت الإضافات نيابةً عن المستخدمين، يمكن للمشرفين أيضًا الاحتفاظ بقائمة مسموح بها للسماح للمستخدمين بتثبيت الإضافات التي تسمح بالتثبيت الفردي. إذا لم تكن الإضافة مُدرَجة في القائمة المسموح بها، سيظل بإمكان المستخدمين الاطّلاع على بطاقة بيانات الإضافة في Google Workspace Marketplace، ولكن لن يتمكّنوا من تثبيتها، بل ستظهر لهم رسالة توضّح أنّ مشرف النطاق لم يسمح بتثبيت الإضافة. لمزيد من المعلومات حول هذا السلوك، يُرجى الاطّلاع على إدارة تطبيقات Google Workspace Marketplace في القائمة المسموح بها.
لمزيد من المعلومات، يُرجى الاطّلاع على مستندات إعدادات التثبيت في Google Workspace Marketplace.
دمج التطبيقات
يجب تقديم عنوان URL لإطار iframe للتشغيل في الحقل معرّف الموارد المنتظم (URI) لإعداد المرفق. يتم استخدام عنوان URL هذا كقيمة src
لـ iframe في إطار iframe الخاص بميزة "اكتشاف المرفقات". يستخدم المعلّمون إطار iframe الخاص بميزة "اقتراحات المرفقات" للعثور على محتوى أو أنشطة لإرفاقها بمهمتهم الدراسية. يمكن ضبطها في وحدة تحكّم مشروع Google Cloud.
يتم استخدام بادئات معرّفات الموارد المنتظمة (URI) للمرفقات المسموح بها للتحقّق من صحة معرّفات الموارد المنتظمة (URI) التي تم ضبطها في
AddOnAttachment
باستخدام الطريقتَين *.addOnAttachments.create
و*.addOnAttachments.patch
. التحقّق هو تطابق حرفي لبادئة السلسلة
ولا يسمح باستخدام أحرف البدل.
يجب أيضًا تحديد جميع بادئات URI التي يُسمح منها بالمرفقات من الإضافة. تزيد هذه الميزة من مستوى الأمان من خلال منع المرفقات من مصادر غير مصرَّح بها.
اضبط كلتا القيمتَين في صفحة إعدادات التطبيق في حزمة تطوير البرامج (SDK) في Marketplace ضمن مشروعك على Google Cloud.
حسابات الاختبار
أنشئ حسابات اختبارية على نطاق العرض التوضيحي للتحقّق من السلوك الصحيح للإضافة الخاصة. يجب توفُّر حسابَي طالبَين لاختبار التبديل بين الطلاب في إطار iframe الخاص بمراجعة أعمال الطلاب.
حسابات الاختبار المقترَحة:
- المعلِّمة "تامي"، tammy.teacher@<your demo domain>
- Sam Student، sam.student@<your demo domain>
- سالي الطالبة، sally.student@<your demo domain>
اتّبِع الإجراء التالي لإنشاء حساب اختبار جديد:
- سجِّل الدخول إلى وحدة تحكّم المشرف.
- انتقِل إلى المستخدمون.
- انقر على إضافة مستخدم جديد (راجِع الشكل 1).
- أدخِل معلومات المستخدم وحدِّد الأدوار المناسبة.
الشكل 1. موقع الرابط إضافة مستخدم جديد ضمن "وحدة تحكّم المشرف"
اتّبِع الإجراء التالي لإنشاء مجموعة اختبار جديدة:
- سجِّل الدخول إلى وحدة تحكّم المشرف.
- انتقِل إلى المجموعات.
- انقر على إنشاء مجموعة (راجِع الشكل 2).
- أدخِل أعضاء المجموعة ومالكيها.
الشكل 2: موقع الرابط إنشاء مجموعة ضمن "وحدة تحكّم المشرف"