إعدادات مشروع 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 وانقر على PUBLISH.

  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 أو إنشاء مشاريع على السحابة الإلكترونية، عليك التحقّق مما يلي في وحدة تحكّم المشرف:

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

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

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

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

    تفعيل Classroom API

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

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

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

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

    • يجب ألا يتضمن كل من الوصف الموجز والوصف التفصيلي النص نفسه بالضبط.

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

    • تأكَّد من أنّك اخترت قيمة للحقل Category (الفئة). قد تكون المراجع الأكاديمية أو أدوات المعلّمين والمشرفين خيارَين جيدَين لإضافة ميزة إلى 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: موقع رابط إنشاء مجموعة في وحدة تحكم المشرف.