يواجه المعلّمون الذين يستخدمون كلًّا من Classroom والأدوات التابعة لجهات خارجية تحديًا بشأن إعداد الدورات التدريبية وقوائم الطلاب على منصات متعددة. ويمكن إجراء ذلك يدويًا، إما من خلال استخدام عمليات تحميل ملفات CSV أو إدخال عناوين البريد الإلكتروني واحدة تلو الأخرى. ومع ذلك، باستخدام Classroom API، يمكن للأدوات التابعة لجهات خارجية تقليل أحمال عمل المعلّمين من خلال الدمج مع حالة الاستخدام الأكثر شيوعًا لواجهة برمجة التطبيقات: استيراد القوائم.
يتيح استيراد قوائم الطلاب المسجّلين للمنصات التابعة لجهات خارجية استرداد البيانات الوصفية للدورات التدريبية، والمعلّمين، والطلاب على أساس كل دورة تدريبية على حدة باستخدام إما أذونات المعلّم أو أذونات المشرف. يمكن للمعلّمين استرداد تفاصيل الدورات التدريبية التي يقدّمونها، في حين يمكن للمشرفين الوصول إلى تفاصيل جميع الدورات التدريبية في ملف شخصي كامل. وتتيح هذه المرونة للمطوّرين أن يتيحوا بسلاسة إعداد قوائم الطلاب في 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) لتقليل وقت الاستجابة لطلب البيانات من واجهة برمجة التطبيقات. |
| 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، يمكنك الاطّلاع على دليل إدارة الإشعارات الفورية.