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

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

للحصول على معلومات عامة حول نشر إضافة في السوق، راجع نشر تطبيق.

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

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

ملاحظة مهمة: لا يمكنك تحويل مشروع خاص إلى مشروع عام. أنشِئ مشروعًا خاصًا لتطوير الإضافة ومشروعًا عامًا لتمثيل الإصدار الجاهز للإنتاج.

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

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

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

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

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

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

   تحذير: يُرجى التأكّد من أنّ المشروع ينتمي إلى نطاق العرض التوضيحي وأنك سجّلت الدخول إلى Google Cloud Console باستخدام حساب مشرف للنطاق التجريبي.

3. تفعيل Classroom API.

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

5. اضبط حزمة SDK للسوق إعداد التطبيق مستوى رؤية التطبيق على خاص.

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

   ملاحظة: أرسِل كلاً من نموذج النطاقات التجريبية في Google for Education من صفحة الحصول على نطاق تجريبي للمطوّرين ونموذج طلب ترقية النطاق التجريبي الذي تمت مناقشته هنا.

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

يمثل هذا المشروع الإضافة التي يمكن الوصول إليها من قبل المشرفين والمعلمين والطلاب.

1. أنشِئ مشروعًا جديدًا على Google Cloud وفعِّل حزمة تطوير البرامج (SDK) في Google Workspace Marketplace. اضبط إعداد التطبيق مستوى ظهور التطبيق على علني وغير مُدرَج. لا يمكنك مشاركة أو تحويل المشروع الخاص المستخدم أثناء الاختبار الداخلي؛ يجب أن يكون رقم مشروع جديدًا.
2. يمكنك مشاركة رقم تعريف مشروع Google Cloud مع شريك Google لإضافة المشروع إلى القائمة المسموح بها للإضافات. يمنح هذا المشروع إمكانية الوصول إلى الميزات الإضافية الجديدة لواجهة برمجة تطبيقات Classroom API.
3. بعد الموافقة على الإضافة، يغيّر فريق Google Workspace Marketplace الإضافة من "غير مُدرَجة" إلى "مدرَجة" ليتمكّن المعلّمون من العثور عليها في المتجر.

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

تحذير: تأكَّد من أنّ المشروع ينتمي إلى نطاق الإنتاج وأنك قد سجّلت الدخول إلى Google Cloud Console باستخدام حساب مستخدم لذلك النطاق. إذا لم يكن الأمر كذلك، لا يمكن أن تظهر ميزات إضافة Classroom ضمن صفحة إعداد تطبيق "حزمة تطوير البرامج" (SDK) للسوق.

OAuth 2.0

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

ملاحظة مهمة: إذا كانت الإضافة تطلب نطاقات إضافية، أدرِجها في شاشة موافقة OAuth، وعلامة التبويب Marketplace SDK App Configuration و رمز تطبيق الإضافة. وقد يؤدي عدم تطابق النطاقات في هذه المواقع إلى حدوث مشاكل للمستخدمين أثناء تثبيت الإضافة.

راجِع صفحة نطاقات OAuth لواجهات Google APIs للحصول على قائمة تفصيلية بجميع النطاقات المتاحة واستخداماتها. راجِع صفحة إعداد OAuth في مستندات Workspace للحصول على معلومات عامة حول إعدادات OAuth.

أذونات المستخدمين

يجب أن يطلب تطبيق الويب أحد النطاقات التالية على الأقل:

• https://www.googleapis.com/auth/userinfo.email، الذي يسمح للتطبيق بعرض عنوان البريد الإلكتروني للمستخدم.
• https://www.googleapis.com/auth/userinfo.profile، الذي يُتيح للتطبيق الاطّلاع على المعلومات الشخصية مثل الاسم العمودي، والاسم الأول واسم العائلة، والمعلومات الشخصية الأخرى التي أتاحها المستخدم للجميع.

بعد تفويض المستخدم لأحد هذه النطاقات في إضافتك، يتم تحديدها من خلال مَعلمة طلب البحث login_hint. يتمّ تمرير هذه المَعلمة إلى أيّ من عناوين URL لتطبيق الويب عند فتح إطار iframe. إذا لم يصرّح المستخدم بأحد هذه النطاقات، يتم تمرير المَعلمة hd ("النطاق المستضاف") إلى عناوين URL الخاصة بتطبيق الويب بدلاً من ذلك.

تحذير: يجب أن يطلب تطبيقك واحدًا على الأقل من أحد نطاقات userinfo.email أو userinfo.profile لتلقّي login_hint في الزيارات اللاحقة التي يجريها المستخدم نفسه.

login_hint وhd هما مَعلمتان عاديتان 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

ملاحظة: لا يمكنك إنشاء فيديو تجريبي لإرساله كجزء من عملية التحقّق من بروتوكول OAuth. بدلاً من ذلك، انشر الإضافة بدون التحقّق من OAuth. يؤدي ذلك إلى تنبيه فريق مراجعة Google Workspace Marketplace لإنشاء فيديو توضيحي نيابةً عنك. بعد ذلك، يرسل إليك فريق المراجعة الفيديو حتى تتمكّن من تضمينه في نموذج التحقّق من بروتوكول OAuth.

تستخدم إضافة Classroom واجهات Google APIs للوصول إلى بيانات مستخدمي Google.

• أثبِت هوية علامتك التجارية.
• التحقّق من نطاقات OAuth الحساسة

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

بيانات Google Workspace Marketplace

تحذير: بعد حفظ خيار مستوى الرؤية أثناء عملية النشر، لا يمكنك تغيير اختيارك لاحقًا.

هناك بعض الأمور التي يجب ملاحظتها عند إنشاء بطاقة بيانات متجر من "السوق" لإضافات Classroom أثناء استخدام هذا البرنامج لاستخدام المنتج قبل إطلاقه.

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

اعتبارات الإدراج

إنّ مستند Marketplace SDK Store Listing الخاص بمشروعك العام على Google Cloud يحدّد اسم تطبيقك وأوصافه للمستخدمين النهائيين. يمكنك تقديم هذه التفاصيل بعدة لغات ضمن تفاصيل التطبيق.

يُرجى اتّباع الإرشادات التالية في بيانات منتجاتك:

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

  • تجنَّب علامات الترقيم في "اسم التطبيق". على سبيل المثال، استخدم "إضافتي بواسطة شركتي" بدلاً من "شركتي: الإضافة الخاصة بي" أو "إضافتي، بواسطة شركتي".

  • يجب ألا يحتوي الوصف المختصر والوصف التفصيلي على النص نفسه بالضبط.

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

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

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

ملاحظة مهمة: يُرجى الاطّلاع على تفاصيل التطبيق لكل لغة يتم تقديم الإضافة بها.

• ضمن أصول الرسومات:

  • إنّ أصول الرسومات المقدَّمة ليست ضبابية وتستوفي الأحجام المحدَّدة في معايير Google Workspace Marketplace.

  • أي لقطات شاشة يتم تقديمها هي تمثيل دقيق لتجربتك في الإضافة.

• ضمن روابط الدعم:

  • تأكَّد من توفير رابط لبنود الخدمة لتطبيقك.

• احرص على اتّباع إرشادات العلامة التجارية لـ Google API التي تتناول الأسماء والأوصاف المسموح بها.

• إذا أشرت إلى أي من منتجات Google في بياناتك، استخدِم اسمه بالتنسيق الوارد في قائمة العلامات التجارية. تأكد من تضمين رمز العلامة التجارية (TM) في حالة تحديده؛ استخدم "Google DocsTM" وليس "مستندات Google".

الدمج مع خدمات الفوترة والفوترة من Google

إذا أردت السماح لتطبيقات Google Workspace Marketplace بالتكامل مع خدمات الفوترة والفوترة من Google، يمكنك الانتقال إلى Marketplace API.

إعدادات التثبيت

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

تثبيت من جانب المشرف

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

في ما يلي بعض الاعتبارات المتعلقة بتثبيت المشرف.

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

يمكنك الاطّلاع على صفحة تثبيت تطبيقات Marketplace في نطاقك للحصول على مزيد من المعلومات حول كيفية إجراء عمليات تثبيت المشرفين وكيفية عمل البنية التنظيمية لمعرفة المزيد من المعلومات عن الوحدات التنظيمية ومجموعات الوصول.

تركيب فردي

تضيف عمليات التثبيت الفردية إضافة إلى حساب المستخدم الخاص. سيُطلب من المستخدم الموافقة على نطاقات الوصول إلى الإضافة أثناء تثبيتها.

في ما يلي بعض الاعتبارات المتعلقة بالتثبيت الفردي.

• تسهيل الاستخدام: يمكن لمزيد من المستخدمين الاطّلاع على إضافتك وتثبيتها من Google Workspace Marketplace. قد يؤدي السماح بالتثبيت الفردي إلى دفع المزيد من المعلمين إلى اعتماد منتجك أو دعمه.
• اختبار المشرف: قد يثبّت المشرف إضافة بشكل فردي لاختبارها أو تقييمها قبل الموافقة عليها أو تثبيتها لمجموعة أوسع.

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

للحصول على مزيد من المعلومات، يمكنك الاطّلاع على مستندات إعدادات التثبيت في Google Workspace Marketplace.

دمج التطبيق

يجب تقديم عنوان URL لإطار iframe للتشغيل في الحقل معرّف الموارد المنتظم (URI) لإعداد المرفقات. يتم استخدام عنوان URL هذا كقيمة src لإطار iframe في إطار iframe لاستكشاف المرفقات. يستخدم المعلمون إطار iframe لاكتشاف المرفقات للعثور على المحتوى أو الأنشطة لإرفاقها بالمهمة الدراسية.

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

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

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

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

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

• "تامي"، المعلّمة، tammy.teacher@<your Demo domain>
• سامي طالب، sam.student@<your Demo domain>
• سالي، طالبة، sally.student@<your Demo domain>

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

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

الشكل 1. موقع رابط إضافة مستخدم جديد ضمن وحدة تحكم المشرف.

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

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

الشكل 2. موقع رابط إنشاء مجموعة داخل وحدة تحكم المشرف.