يواجه المعلّمون الذين يستخدمون كلاً من Classroom والأدوات الخارجية صعوبة في إعداد دوراتهم التدريبية وقوائم الطلاب على عدة منصات. ويمكن إجراء ذلك يدويًا، إما من خلال استخدام عمليات تحميل ملفات CSV أو إدخال عناوين البريد الإلكتروني واحدًا تلو الآخر. باستخدام Classroom API، يمكن للأدوات التابعة لجهات خارجية أن تقلّل من أعباء المعلّمين من خلال الدمج مع حالة الاستخدام الأكثر شيوعًا لواجهة برمجة التطبيقات، وهي استيراد قوائم الطلاب.
تتيح عملية استيراد قائمة الطلاب المسجّلين للمنصات التابعة لجهات خارجية استرداد البيانات الوصفية الخاصة بدورة تدريبية، والمعلّمين، والطلاب على أساس كل دورة تدريبية على حدة باستخدام أذونات المعلِّم أو المشرف. يمكن للمعلّمين استرداد تفاصيل الدورات التدريبية التي يدرّسونها، بينما يمكن للمشرفين الوصول إلى تفاصيل جميع الدورات التدريبية في نطاق بأكمله. تتيح هذه المرونة للمطوّرين إعداد قوائم الطلاب المسجّلين في صفوف Classroom بسلاسة على منصاتهم، سواء على مستوى المعلّم الفردي أو على مستوى النطاق بأكمله باستخدام بيانات اعتماد المشرف.
قبل التعرّف على التفاصيل الفنية الخاصة بعملية دمج استيراد قوائم الطلاب، لنستعرض أولاً مثالاً على سير العمل:
في التطبيق الخارجي، يختار المعلّم خيار استيراد دورة تدريبية في Classroom.
يطلب التطبيق التابع لجهة خارجية طريقة
courses.listمن خلال Classroom API، ما يؤدي إلى عرض استجابة JSON تتضمّن جميع الدورات التدريبية الخاصة بالمعلّم.من ردّ json، يعرض التطبيق التابع لجهة خارجية عناوين الدورات التدريبية الخاصة بالمعلّم ليختار منها دورة تدريبية. سيحتاج التطبيق إلى تتبُّع أرقام تعريف الدورات التدريبية للانتقال إلى الخطوة التالية.
باستخدام معرّف الدورة التدريبية المحدّد، يستدعي التطبيق التابع لجهة خارجية الطريقتَين
students.listوteachers.listويعرض جميع الأسماء على موقعه الإلكتروني ليؤكّدها المعلّمون قبل استيرادها.باستخدام رسائل البريد الإلكتروني التي تم عرضها في ملفات JSON الخاصة بالردود
students.listوteachers.list، يدعو التطبيق التابع لجهة خارجية المستخدمين للانضمام إلى الدورة التدريبية التي تم استيرادها حديثًا على منصته.
بالنسبة إلى كل طريقة مذكورة في سير العمل، يمكنك استخدام أداة API Explorer للاطّلاع على طريقة عمل كل طريقة بالتفصيل. ننصحك أيضًا بقراءة ما يلي قبل الانتهاء من هذا الدليل:
البدء
قبل تنفيذ تفاصيل استيراد قائمة 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، يجب أن يطلب تطبيقك إذنًا من المستخدمين. هناك ثلاثة نطاقات مطلوبة لتنفيذ سير العمل هذا:
- 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، يمكنك الاطّلاع على دليل إدارة الإشعارات الفورية.