إعدادات مشروع Google Cloud

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

لمزيد من المعلومات العامة عن نشر إضافة في Marketplace، يُرجى الاطّلاع على مقالة نشر تطبيق.

إنشاء مشروع على Google Cloud

هناك نوعان من المشاريع التي يمكنك إنشاؤها: مشروع خاص يُستخدَم لأجل تطوير التطبيقات ومشروع عام يمكن للمستخدمين النهائيين الوصول إليه. يشير التصنيفان "عام" و "خاص" إلى مستوى ظهور تطبيقك في Google Workspace Marketplace. لا يمكن للمستخدمين تثبيت تطبيق خاص في Marketplace إلا ضمن النطاق الذي تم فيه إنشاؤه، في حين يتوفّر تطبيق Marketplace المتاح للجميع لأي نطاق في Google Workspace. يجب أن يكونا استقطابَين منفصلَين، لأنّه لا يمكن أن يكون المشروع متاحًا للجميع وفي الوقت نفسه خاصًا. يجب مراجعة التطبيقات المتاحة للجميع والموافقة عليها قبل إتاحتها في السوق.

للحصول على معلومات عامة عن إنشاء مشروع على Google Cloud، يُرجى الانتقال إلى مقالة إنشاء مشروع على Google Cloud.

إنشاء مشروع علني على Google Cloud

يمثّل هذا المشروع التطبيق الإضافي الذي يمكن للمشرفين والمعلّمين والطلاب الوصول إليه. يجب أن يراجع فريق Google Workspace Marketplace المشروع العلني ويمنحه الموافقة قبل إطلاقه أو تثبيته.

  1. أنشئ مشروعًا جديدًا على Google Cloud في نطاق الإصدار العلني.

    إنشاء مشروع على Google Cloud

  2. فعِّل Classroom API في مشروعك على Cloud.

    تفعيل Classroom API

  3. فعِّل حزمة تطوير البرامج (SDK) في Google Workspace Marketplace في مشروعك على Cloud.

    تفعيل حزمة تطوير البرامج (SDK) في Google Workspace Marketplace

  4. اضبط حزمة تطوير البرامج (SDK) في Marketplace إعدادات التطبيق مستوى عرض التطبيق على علني وضَع علامة في المربّع غير مُدرَج.

  5. أكمِل الحقول المطلوبة في صفحة بطاقة بيانات المتجر لحزمة SDK في Marketplace وانقر على نشر.

  6. سيراجع فريق Google Workspace Marketplace تطبيقك. سيقوم العميل بالتواصل معك باستخدام عنوان البريد الإلكتروني للمطوّر المحدّد في حزمة SDK الخاصة بالسوق. بعد الموافقة على التطبيق، أزِل العلامة من المربّع غير مُدرَج ليتمكّن المعلّمون والمشرفون من العثور عليه في Marketplace.

إنشاء مشروع خاص على Google Cloud

يمثّل هذا المشروع الخاص تطبيق الإضافة المستخدَم لتطوير التطبيق. ولا يمكن للمستخدمين خارج النطاق الذي تم إنشاؤه فيه الوصول إليه، ولكن لا يلزم الموافقة عليه قبل التثبيت. لذلك، تنصح Google باستخدام هذا المشروع لتطوير الإضافة واختبارها في بيئة خاضعة للرقابة.

يجب أن يكون لديك إذن الوصول إلى نطاق Google Workspace for Education باستخدام ترخيص Teaching & Learning أو Plus لإنشاء مشروع خاص. إذا لم يكن لديك إذن الوصول إلى هٰذا النطاق، اتّبِع الخطوات التالية لإعداد نطاق تجريبي على Google Workspace for Education، ثم ترقيته إلى ترخيص Plus، والسماح له بالوصول إلى واجهة برمجة التطبيقات لإضافة Classroom:

  1. أكمِل الخطوات للحصول على نطاق اختبار للمطوّرين.

  2. أثناء تسجيل الدخول كمشرف في النطاق التجريبي، أنشئ مشروعًا جديدًا على Google Cloud.

    إنشاء مشروع على Google Cloud

    إذا لم تتمكّن من الوصول إلى Google Cloud Console أو إنشاء مشاريع Cloud، تحقّق مما يلي في وحدة تحكّم المشرف:

    • انتقِل إلى صفحة إعدادات الحساب > إعدادات الوصول المستنِد إلى العمر وحددتبلغ أعمار كل المستخدمين في هذه المجموعة أو الوحدة التنظيمية 18 عامًا أو أكبر.
    • ضمن التطبيقات > الخدمات الإضافية من Google:
    • تكون Google Cloud Platform مفعّلة للجميع.
    • إعدادات إنشاء المشروع هي السماح للمستخدمين بإنشاء مشاريع.
    • إعدادات الوصول إلى Cloud Shell هي السماح بالوصول إلى Cloud Shell.

  3. أكمِل نموذج طلب ترقية النطاق التجريبي وأرسِله. يؤدي إرسال هذا النموذج إلى طلب ترقية Google لنطاقك التجريبي إلى Google Workspace for Education Plus من خلال عشرة تراخيص والسماح لمشروعك على Cloud بالوصول إلى واجهة برمجة التطبيقات لإضافات Classroom.

    ستصلك رسالة إلكترونية عند اكتمال عمليات الترقية وإضافة التطبيقات إلى القائمة المسموح بها. يمكنك منح تراخيص Plus لحسابات المعلّمين الاختبارية في وحدة تحكّم المشرف. ضمن الدليل > المستخدمون، أنشئ حسابات المعلّمين الاختبارية أو اختَرها. في كل تراخيص المعلّم، تأكَّد من أنّ Google Workspace for Education Plus مخصّصة.

  4. فعِّل Classroom API في مشروعك على Cloud.

    تفعيل Classroom API

  5. فعِّل حزمة تطوير البرامج (SDK) في Google Workspace Marketplace في مشروعك على Cloud.

    تفعيل حزمة تطوير البرامج (SDK) في Google Workspace Marketplace

  6. اضبط Marketplace SDK إعدادات التطبيق مستوى وصول التطبيق على خاص.

  7. أكمِل الحقول المطلوبة في صفحة بطاقة بيانات المتجر لحزمة SDK في Marketplace وانقر على نشر. بعد نشر بطاقة بيانات التطبيق، يمكن للمستخدمين في النطاق العثور على التطبيق وتثبيته في Google Workspace Marketplace أو عن طريق الانتقال إلى عنوان URL للتطبيق المعروض في صفحة بطاقة بيانات المتجر.

OAuth 2.0

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

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

اطّلِع على صفحة نطاقات OAuth لواجهات برمجة تطبيقات Google للحصول على قائمة تفصيلية بجميع النطاقات المتاحة واستخداماتها. اطّلِع على صفحة إعداد 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 للوصول إلى بيانات مستخدمي Google.

يُرجى الاطّلاع على الأسئلة الشائعة حول إثبات ملكية واجهة برمجة التطبيقات OAuth للحصول على مزيد من المعلومات عن عملية إثبات الملكية.

بطاقة بيانات Google Workspace Marketplace

للحصول على معلومات عامة حول ضبط حزمة تطوير البرامج (SDK) في Google Workspace Marketplace، يُرجى الانتقال إلى مقالتَي تفعيل حزمة تطوير البرامج (SDK) في Google Workspace Marketplace وضبطها وإنشاء بطاقة بيانات متجر على Google Workspace Marketplace.

اعتبارات متعلقة بإضافة المنتجات إلى بطاقة بيانات المتجر

يحدِّد بطاقة بيانات "متجر حِزم تطوير البرامج (SDK) في السوق" لمشروعك العلني على Google Cloud اسم تطبيقك و أوصافه المخصّصة للمستخدمين النهائيين. يمكنك تقديم هذه التفاصيل بلغات متعددة ضمن تفاصيل التطبيق.

اتّبِع هذه الإرشادات في بياناتك:

  • ضمن تفاصيل التطبيق:

    • تجنَّب استخدام علامات الترقيم في اسم التطبيق. على سبيل المثال، استخدِم "إضافة My Add-on من My Company" بدلاً من "My Company: My Add-on" أو "My Add-on، من My Company".

    • يجب ألا يتضمّن الوصف القصير والوصف التفصيلي النص نفسه تمامًا.

    + تأكَّد من اختيار قيمة لحقل السعر. يتضمّن هذا الحقل خيارات مجاني ومدفوع مع فترة تجريبية مجانية ومدفوع مع ميزات مجانية ومدفوع. لست بحاجة إلى تحديد مبلغ التكلفة في بطاقة بيانات السوق.

    • تأكَّد من اختيار قيمة للحقل الفئة. قد تكون المراجع الأكاديمية أو أدوات المعلّمين والمشرفين خيارَين جيدَين لإضافة ميزة إلى Classroom.

    • اطّلِع على العناصر المدرَجة في وصف تفاصيل التطبيق في Marketplace للحصول على مزيد من المعلومات.

الدمج مع خدمات الترخيص والفوترة من 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 في ميزة "اكتشاف المرفقات" للعثور على محتوى أو أنشطة بهدف إرفاقها بالمهمة الدراسية.

يجب أيضًا تحديد جميع بادئات عناوين URL التي يُسمح من خلالها بإضافة المرفقات من إضافتك. تزيد هذه الميزة من مستوى الأمان من خلال منع المرفقات من مصادر غير مصرّح بها.

راجِع صفحة دليل إطارات iframe للحصول على مزيد من التفاصيل حول هذه الحقول.

الحسابات الاختبارية

أنشئ حسابات اختبارية على نطاقك التجريبي للتأكّد من السلوك الصحيح لإضافة الخاصة. يجب توفُّر حسابَي طالب لاختبار التبديل بين الطلاب في إطار iframe الخاص بميزة "مراجعة أعمال الطلاب".

الحسابات الاختبارية المقترَحة:

  • المعلمة "تامي"، tammy.teacher@<your demo domain>
  • سام طالب، sam.student@<your demo domain>
  • "سالي طالبة"، sally.student@<نطاقك التجريبي>

اتّبِع الإجراء التالي لإنشاء حساب تجريبي جديد:

  1. سجِّل الدخول إلى وحدة تحكّم المشرف.
  2. انتقِل إلى المستخدمون.
  3. انقر على إضافة مستخدم جديد (راجِع الشكل 1).
  4. أدخِل معلومات المستخدم وخصِّص الأدوار المناسبة.

انقر على &quot;إضافة مستخدم جديد&quot;. الشكل 1. مكان ظهور رابط إضافة مستخدم جديد ضمن وحدة تحكّم المشرف

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

  1. سجِّل الدخول إلى وحدة تحكّم المشرف.
  2. انتقِل إلى المجموعات.
  3. انقر على إنشاء مجموعة (راجِع الشكل 2).
  4. أدخِل أعضاء المجموعة ومالكيها.

انقر على &quot;إنشاء مجموعة&quot;. الشكل 2: مكان رابط إنشاء مجموعة ضمن وحدة تحكّم المشرف