يواجه المعلمون الذين يستفيدون من كل من 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) لتقليل وقت الردّ على طلب البيانات من واجهة برمجة التطبيقات. |
| 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
- توفير إذن وصول للقراءة إلى سمة email للمعلّمين والطلاب
مزامنة قوائم الطلاب المسجّلين مع إشعارات النشر/الاشتراكات
مع تقدم العام الدراسي، قد تتغير قوائم الطلاب المسجّلين عندما يسقط الطلاب أو يضيفون الدورات التدريبية. من خلال إضافة إشعارات النشر/الاشتراك، يصبح بإمكانك مزامنة تطبيقك التابع لجهة خارجية مع قوائم Classroom. لتلقّي الإشعارات، يمكنك إعداد موضوع Google Cloud Pub/Sub، ثم تسجيل الموضوع باستخدام Classroom API. هذا التسجيل هو طلب من Classroom لإرسال البيانات من الخلاصة المحددة إلى الموضوع المحدّد. ستكون هذه الخلاصة هي العوامل المشغِّلة للأحداث لإعادة المزامنة مع قائمة المعلّمين في Classroom.
سيتطلب استخدام الإشعارات الفورية نطاقًا إضافيًا واحدًا لا يجب إرساله للتحقُّق:
- https://www.googleapis.com/auth/classroom.push-notifications
- يسمح لتطبيقك بالتسجيل للحصول على أي نشاط إشعارات فورية
لمزيد من التفاصيل حول كيفية الدمج مع الإشعارات الفورية في Classroom، يمكنك الاطّلاع على دليل إدارة الإشعارات الفورية.