يواجه المعلّمون الذين يستخدمون كلًّا من Classroom والأدوات التابعة لجهات خارجية تحديًا في إعداد الدورات التدريبية وقوائم الطلاب على منصات متعددة. ويمكن إجراء ذلك يدويًا، إما من خلال استخدام عمليات تحميل ملفات CSV أو إدخال عناوين البريد الإلكتروني واحدة تلو الأخرى. ومع ذلك، باستخدام Classroom API، يمكن للأدوات التابعة لجهات خارجية تقليل أحمال عمل المعلّمين من خلال الدمج مع حالة الاستخدام الأكثر شيوعًا لواجهة برمجة التطبيقات: استيراد قوائم الطلاب.
يتيح استيراد قوائم الطلاب المسجّلين للمنصات التابعة لجهات خارجية استرداد البيانات الوصفية للدورات التدريبية، والمعلّمين، والطلاب على أساس كل دورة تدريبية على حدة باستخدام إما أذونات المعلّم أو أذونات المشرف. يمكن للمعلّمين استرداد تفاصيل الدورات التدريبية التي يقدّمونها، في حين يمكن للمشرفين الوصول إلى تفاصيل جميع الدورات التدريبية في ملف شخصي كامل. تتيح هذه المرونة للمطوّرين إضافة قوائم طلاب Google Classroom بسلاسة إلى منصاتهم على مستوى معلّم فردي أو على مستوى نطاق كامل باستخدام بيانات اعتماد المشرف.
قبل الخوض في التفاصيل الفنية حول الشكل المحتمل لدمج استيراد القوائم، لنراجع أولاً مثالاً على سير العمل:
في التطبيق التابع لجهة خارجية، يختار المعلّم خيار استيراد دورة تدريبية في Classroom.
يستدعي التطبيق التابع لجهة خارجية الطريقة
courses.listمن خلال Classroom API، ما سيؤدي إلى عرض استجابة JSON تتضمّن جميع الدورات التدريبية للمعلّم.من خلال استجابة json، يعرض التطبيق التابع لجهة خارجية عناوين الدورات التدريبية للمعلّم ليختار منها. سيحتاج التطبيق إلى تتبُّع أرقام تعريف الدورات التدريبية للمتابعة إلى الخطوة التالية.
باستخدام رقم تعريف الدورة التدريبية المحدّد، يستدعي التطبيق التابع لجهة خارجية الطريقتَين
students.listوteachers.listويعرض جميع الأسماء على موقعه الإلكتروني ليؤكد المعلّمون على استيرادها.باستخدام عناوين البريد الإلكتروني المعروضة في ملفَي json للردّ
students.listوteachers.list، يدعو التطبيق التابع لجهة خارجية المستخدمين للانضمام إلى الدورة التدريبية التي تم استيرادها حديثًا على منصته.
لكل طريقة من الطرق المذكورة في سير العمل، يمكنك استخدام "مستكشف واجهة برمجة التطبيقات" لمعرفة سلوك كل طريقة بالضبط. ننصحك أيضًا بالاطّلاع على المراجع التالية قبل الانتهاء من هذا الدليل:
البدء
قبل تنفيذ تفاصيل استيراد قائمة الطلاب في Classroom، عليك تحديد معلومات الدورة التدريبية والمستخدمين التي ستحتاج إلى استرجاعها من خلال واجهة برمجة التطبيقات. يمكنك الاطّلاع على البيانات الوصفية المتاحة للدورة التدريبية في المستندات المرجعية، ولكن يمكن تلخيص بعض الحقول المطلوبة أو الشائعة أدناه:
| الحقل | استخدام |
|---|---|
| id | مطلوب لطلبات واجهة برمجة التطبيقات التي تسترجع بيانات الطلاب أو المعلّمين |
| الاسم | يُنصح باستخدام هذا الخيار لسهولة استخدام المستخدِم، أي العرض على موقعك الإلكتروني. |
| ownerId | مطلوب عند الاستيراد على مستوى النطاق لتحديد المعلّم الرئيسي للدورة التدريبية بشكل صحيح |
يتم استرداد معلومات الدورة التدريبية هذه في خطوة courses.list من سير العمل
أعلاه. في هذا الطلب، يمكنك تحديد مَعلمات طلب معيّنة. على الرغم من أنّه ليس هناك مَعلمة واحدة مطلوبة لهذه الطريقة، في ما يلي بعض المَعلمات المقترَحة:
| المَعلمة | استخدام |
|---|---|
| courseState | في حال عدم تحديد هذا الحقل، ستعرض واجهة برمجة التطبيقات الدورات التدريبية لجميع حالات الدورة التدريبية الستة. ننصحك بتحديد ACTIVE لاسترداد الدورات التدريبية التي يستخدمها المعلّمون حاليًا. |
| pageSize | بالنسبة إلى المعلّمين الذين يستوردون دوراتهم التدريبية، ننصحك بتحديد قيمة صغيرة (أقل من 10) لسمة pageSize لتقليل وقت استجابة طلب البيانات من واجهة برمجة التطبيقات. |
| pageToken | مطلوب إذا كنت تستخدِم طلبات مُقسّمة إلى صفحات. |
| teacherId | يُنصح باستخدام هذا الخيار لأنّ مشرفي النطاق يدرّسون الدورات التدريبية غالبًا. في حال عدم تحديد نطاق، سيعرض الطلب الدورات التدريبية للمعلّمين في النطاق بأكمله. |
| fields | ننصحك بتقليل وقت استجابة طلب البيانات من واجهة برمجة التطبيقات. |
باستخدام أرقام تعريف الدورات التدريبية التي تم استرجاعها سابقًا، يمكن لتطبيقك الآن استرجاع
قائمة الطلاب والمعلّمين المشاركين في هذه الدورة التدريبية أو الدورات التدريبية. رقم تعريف الدورة التدريبية هذا هو
مَعلمة طلب البحث الوحيدة المطلوبة لكل من teachers.list وstudents.list، ولكن
قد تحتاج إلى تحديد المَعلمتَينpageSize وfields
كذلك لتقليل وقت استجابة طلبات البيانات من واجهة برمجة التطبيقات.
يمكن العثور على جميع الحقول المتاحة لموارد
الطالب
والمعلّم
في المستندات الخاصة بكل منهما. الحقلَان الأكثر استخدامًا ومطلوبَين عادةً في حقل profile هما:
profile.name وprofile.emailAddress.
| الحقل | استخدام |
|---|---|
| profile.name | يُنصح باستخدام هذا الخيار لسهولة استخدام المستخدِم، أي العرض على موقعك الإلكتروني. |
| profile.emailAddress | مطلوب للتطبيقات التي تبحث عن تحديد الطلاب بشكل فريد |
لاسترداد أيّ من تفاصيل الدورات التدريبية أو قوائم الطلاب هذه واستخدامها من Classroom، يجب أن يطلب تطبيقك تفويضًا من المستخدمين. هناك ثلاثة (3) مجالات مطلوبة لتنفيذ سير العمل هذا:
- https://www.googleapis.com/auth/classroom.courses.readonly
- منح إذن بالقراءة فقط إلى دورات Google Classroom
- https://www.googleapis.com/auth/classroom.rosters.readonly
- إتاحة إذن الوصول للقراءة فقط إلى قوائم الطلاب في دورات Google Classroom (المعلّمون والطلاب)
- https://www.googleapis.com/auth/classroom.profile.emails
- يوفّر إذن الوصول للقراءة إلى البريد الإلكتروني للمعلّمين والطلاب
مزامنة قوائم المستخدمين مع إشعارات Pub/Sub
مع تقدّم العام الدراسي، قد تتغيّر قوائم الطلاب عندما يسحبون مقررات أو يدرسون مقررات جديدة. ستتيح لك إضافة إشعارات Pub/Sub مزامنة تطبيقك التابع لجهة خارجية مع قوائم طلاب Classroom. لتلقّي الإشعارات، عليك إعداد موضوع Google Cloud Pub/Sub ثم تسجيل الموضوع باستخدام واجهة برمجة التطبيقات Classroom API. هذا التسجيل هو طلب موجَّه إلى Classroom لإرسال البيانات من الخلاصة المحدّدة إلى الموضوع المحدّد. ستكون هذه الخلاصة هي عوامل تشغيل الأحداث لإعادة المزامنة مع قائمة الطلاب في Classroom الخاصة بالمعلّم.
سيتطلب استخدام الإشعارات الفورية نطاقًا إضافيًا واحدًا، ولا يلزم إرساله لإثبات ملكيته:
- https://www.googleapis.com/auth/classroom.push-notifications
- السماح لتطبيقك بالتسجيل لأي نشاط إشعار فوري
لمزيد من التفاصيل حول كيفية الدمج مع الإشعارات الفورية في Classroom، يمكنك الاطّلاع على دليل إدارة الإشعارات الفورية.